PersistentObject Class Reference
[Persistence]

PersistentObject is the base class of all persistent objects. It implements the basic persistence methods (save(), delete()) which will be delegated to the PersistenceMapper class that contsructed the object. The PersistentObject holds the object data in an associative array of the following structure:. More...

Inheritance diagram for PersistentObject:

[legend]


Public Member Functions
	PersistentObject ($type, $oid=null)
	getType ()
	setType ($type)
	getBaseType ()
	getOID ()
	setOID ($oid)
	getDBID ()
	setDBID ($id)
	getMapper ()
&	getDataConverter ()
	save ()
	delete ($recursive=true)
	getState ()
	setState ($state)
	setImmutable ()
	getLock ()
&	duplicate ()
	copyValues (&$object, $dataTypes=array())
	copyValueIntern (&$node, $valueName, $dataType, &$targetNode, $dataTypes)
	clearValues ($dataTypes=array())
	clearValueIntern (&$node, $valueName, $dataType, $dataTypes)
	updateOID ()
	afterCreate ()
	beforeInsert ()
	afterInsert ()
	afterLoad ()
	beforeUpdate ()
	afterUpdate ()
	beforeDelete ()
	afterDelete ()
	hasValue ($name, $type=null)
	getValue ($name, $type=null)
	removeValue ($name, $type=null)
	getUnconvertedValue ($name, $type=null)
	getConvertedValue ($name, $type=null)
	getValueTypes ($name)
	validateValue ($name, $value, $type=null)
	setValue ($name, $value, $type=null, $forceSet=false)
	getValueProperties ($name, $type=null)
	setValueProperties ($name, $properties, $type=null)
	getValueProperty ($name, $property, $type=null)
	setValueProperty ($name, $property, $value, $type=null)
	getValueNames ($type=null)
	getDataTypes ()
	getProperty ($name)
	setProperty ($name, $value)
	getPropertyNames ()
	addChangeListener (&$listener)
	removeChangeListener (&$listener)
	propagateValueChange ($name, $type, $oldValue, $newValue)
	propagatePropertyChange ($name, $oldValue, $newValue)
	propagateStateChange ($oldValue, $newValue)
	getObjectDisplayName ()
	getObjectDescription ()
	getDisplayValue ()
	getValueDisplayName ($name, $type=null)
	getValueDescription ($name, $type=null)
	toString ($verbose=false)
Data Fields
	$_oid = null
	$_type = ''
	$_data = array()
	$_properties = array()
	$_mapper = null
	$_state = STATE_CLEAN
	$_isImmutable = false
	$_changeListeners = array()

Detailed Description

PersistentObject is the base class of all persistent objects. It implements the basic persistence methods (save(), delete()) which will be delegated to the PersistenceMapper class that contsructed the object. The PersistentObject holds the object data in an associative array of the following structure:.

 * datatype1---valueName1---value
 *                          properties---propertyName1---value
 *                                       propertyName2---value
 *                                       ...
 *             valueName2---value
 *                          properties---propertyName1---value
 *                                       ...
 *             ...
 * datatype2---valueName1---value
 *                          properties---propertyName1---value
 *                                       ...
 *             ...
 * ...
 *
 * e.g.: $this->_data[DATATYPE_ATTRIBUTE]['name']['value']                 gives the value of the attribute 'name' which is of app_data_type DATATYPE_ATTRIBUTE
 *       $this->_data[DATATYPE_ATTRIBUTE]['name']['properties']['visible'] gives the value of the visibility property of the 
 *                                                                         attribute 'name'
 *

Author:: ingo herwig <ingo@wemove.com>

Definition at line 69 of file class.PersistentObject.php.

Member Function Documentation

PersistentObject	(	$	type,
		$	oid = `null`
	)

Constructor. The object will be bound to the appripriate PersistenceMapper automatically, if the the PersistenceFacade knows the type.

Parameters:

	type	The object type.
	oid	The object id (, optional will be calculated if not given or not valid).

Definition at line 86 of file class.PersistentObject.php.

References PersistenceFacade::composeOID(), PersistenceFacade::getInstance(), PersistenceFacade::isValidOID(), setOID(), and setState().

Referenced by Node::Node().

Here is the call graph for this function:

getType ( )

Get the type of the object.

Returns:: The objects type.

Definition at line 113 of file class.PersistentObject.php.

Referenced by Node::getNumChildren(), Node::getNumParents(), getObjectDescription(), getObjectDisplayName(), Node::getPath(), and updateOID().

setType ( $ type )

Set the type of the object.

Parameters:

type

The objects type.

Definition at line 121 of file class.PersistentObject.php.

getBaseType ( )

Get the base type of the object. This might differ from the type, if the object may exist in different roles and has one of these roles currently. The default implementation ' returns the object's type.

Returns:: The objects base type.

Definition at line 131 of file class.PersistentObject.php.

getOID ( )

Get the object id of the PersistentObject.

Returns:: The PersistentObject's oid.

Reimplemented in NullNode.

Definition at line 139 of file class.PersistentObject.php.

Referenced by delete(), Node::deleteChild(), getLock(), Node::getNextSibling(), Node::getPreviousSibling(), User::hasRole(), Node::loadChildren(), Node::loadParents(), Node::toString(), and Node::updateParent().

setOID ( $ oid )

Set the object id of the PersistentObject.

Parameters:

oid

The PersistentObject's oid.

Definition at line 147 of file class.PersistentObject.php.

References PersistenceFacade::decomposeOID(), and setValue().

Referenced by AuthUser::login(), PersistentObject(), and setDBID().

Here is the call graph for this function:

getDBID ( )

Get the id of the object in the persistent storage.

Note:: This is NOT a application unique id

Returns:: The id.

Reimplemented in NullNode.

Definition at line 166 of file class.PersistentObject.php.

References PersistenceFacade::getOIDParameter().

Referenced by UserRDBBase::addChild(), RoleRDBBase::addChild(), UserRDBBase::deleteChild(), RoleRDBBase::deleteChild(), UserRDBBase::getChildrenEx(), RoleRDBBase::getChildrenEx(), UserRDBBase::getLocktableChildren(), UserRDBBase::getNMUserRoleChildren(), RoleRDBBase::getNMUserRoleChildren(), User::getUserId(), UserRDBBase::loadChildren(), and RoleRDBBase::loadChildren().

Here is the call graph for this function:

setDBID ( $ id )

Set the id of the object in the persistent storage.

Note:: This is NOT a application unique id

Parameters:

id

The id.

Definition at line 176 of file class.PersistentObject.php.

References PersistenceFacade::composeOID(), and setOID().

Here is the call graph for this function:

getMapper ( )

Get the PersistenceMapper of the object.

Returns:: A reference to a PersistenceMapper class

Definition at line 184 of file class.PersistentObject.php.

& getDataConverter ( )

Get the DataConverter used when loading/saving values.

Returns:: A reference to the dataConverter instance

Definition at line 192 of file class.PersistentObject.php.

Referenced by getConvertedValue(), and getUnconvertedValue().

save ( )

Save data. This call will be delegated to the PersistenceMapper class.

Definition at line 201 of file class.PersistentObject.php.

References afterInsert(), afterUpdate(), beforeInsert(), beforeUpdate(), and getState().

Here is the call graph for this function:

delete ( $ recursive = true )

Delete data. This call will be delegated to the PersistenceMapper class.

Parameters:

recursive

True/False whether to physically delete it's children too [default: true]

Definition at line 226 of file class.PersistentObject.php.

References afterDelete(), beforeDelete(), and getOID().

Here is the call graph for this function:

getState ( )

Get the object's state:

Returns:: One of the STATE constant values:

Definition at line 244 of file class.PersistentObject.php.

Referenced by save().

setState ( $ state )

Set the state of the object to one of the STATE constants.

Attention:: Internal use only.

Definition at line 252 of file class.PersistentObject.php.

References propagateStateChange().

Referenced by Table::deleteRow(), Table::insertRow(), PersistentObject(), setValue(), setValueProperties(), Table::setValueProperties(), and Table::Table().

Here is the call graph for this function:

setImmutable ( )

Set object immutable. Sets the editable property of each value to false. and disables save/delete methods.

Note:: This operation is not reversible (reload the object to get a mutable one)

Definition at line 286 of file class.PersistentObject.php.

References getDataTypes(), getValueNames(), and setValueProperty().

Referenced by getLock().

Here is the call graph for this function:

getLock ( )

Get the lock on the object.

Returns:: lock The lock as provided by LockManager::getLock() or null if not locked

Note:: If the object is locked it's set immutable. This is not reversible (reload the object to get a mutable one)

Definition at line 300 of file class.PersistentObject.php.

References LockManager::getInstance(), getOID(), and setImmutable().

Here is the call graph for this function:

& duplicate ( )

Get a copy of the object (ChangeListeners and Lock are not copied)

Returns:: A reference to copy.

Definition at line 312 of file class.PersistentObject.php.

copyValues	(	&$	object,
		$	dataTypes = `array()`
	)

Copy all non-empty values to a given instance (ChangeListeners are triggered)

Parameters:

	object	A reference to the PersistentObject to copy the values to.
	dataTypes	An array of datatypes. Only values of that datatypes will be copied. Empty array means all datatypes [default:empty array]

Definition at line 332 of file class.PersistentObject.php.

copyValueIntern	(	&$	node,
		$	valueName,
		$	dataType,
		&$	targetNode,
		$	dataTypes
	)

Private callback for copying values

See also:: NodeProcessor

Definition at line 341 of file class.PersistentObject.php.

clearValues ( $ dataTypes = array() )

Clear all values. Set each value to null.

Parameters:

dataTypes

An array of datatypes. Only values of that datatypes will be cleared. Empty array means all datatypes [default:empty array]

Definition at line 355 of file class.PersistentObject.php.

clearValueIntern	(	&$	node,
		$	valueName,
		$	dataType,
		$	dataTypes
	)

Private callback for clearing values

See also:: NodeProcessor

Definition at line 364 of file class.PersistentObject.php.

updateOID ( )

Recalculate the object id

Definition at line 372 of file class.PersistentObject.php.

References PersistenceFacade::composeOID(), getType(), and getValue().

Referenced by setValue().

Here is the call graph for this function:

afterCreate ( )

Persistence hook methods. Subclasses may override this to implement special application requirements. The default implementations do nothing. This method is called once after creation of this object. At this time it is not known in the store.

Definition at line 394 of file class.PersistentObject.php.

beforeInsert ( )

This method is called once before inserting the newly created object into the store.

Definition at line 398 of file class.PersistentObject.php.

Referenced by save().

afterInsert ( )

This method is called once after inserting the newly created object into the store.

Definition at line 402 of file class.PersistentObject.php.

Referenced by save().

afterLoad ( )

This method is called always after loading the object from the store.

Definition at line 406 of file class.PersistentObject.php.

beforeUpdate ( )

This method is called always before updating the modified object in the store.

Definition at line 410 of file class.PersistentObject.php.

Referenced by save().

afterUpdate ( )

This method is called always after updating the modified object in the store.

Definition at line 414 of file class.PersistentObject.php.

Referenced by save().

beforeDelete ( )

This method is called once before deleting the object from the store.

Definition at line 418 of file class.PersistentObject.php.

Referenced by delete().

afterDelete ( )

This method is called once after deleting the object from the store.

Definition at line 422 of file class.PersistentObject.php.

Referenced by delete().

hasValue	(	$	name,
		$	type = `null`
	)

Values and Properties Check if the node has a given item.

Parameters:

	name	The name of the item to query.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item value of any type that matches will be returned)

Returns:: True/False wether the item exists or not.

Definition at line 435 of file class.PersistentObject.php.

References getValueNames().

Here is the call graph for this function:

getValue	(	$	name,
		$	type = `null`
	)

Get the value of a named item.

Parameters:

	name	The name of the item to query.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item value of any type that matches will be returned)

Returns:: The value of the item / null if it doesn't exits.

Definition at line 446 of file class.PersistentObject.php.

Referenced by Table::getColumn(), UserImpl::getConfig(), UserRDBBase::getConfig(), getConvertedValue(), UserImpl::getFirstname(), UserRDBBase::getFirstname(), NMUserRoleBase::getFkRoleId(), NMUserRoleBase::getFkUserId(), LocktableBase::getFkUserId(), UserRDBBase::getId(), RoleRDBBase::getId(), LocktableBase::getId(), AdodbseqBase::getId(), UserImpl::getLogin(), UserRDBBase::getLogin(), UserImpl::getName(), RoleImpl::getName(), UserRDBBase::getName(), RoleRDBBase::getName(), LocktableBase::getObjectid(), UserImpl::getPassword(), UserRDBBase::getPassword(), NMUserRoleBase::getRoleRDBOID(), Table::getRow(), LocktableBase::getSessionid(), LocktableBase::getSince(), getUnconvertedValue(), NMUserRoleBase::getUserRDBOID(), LocktableBase::getUserRDBOID(), setValue(), toString(), and updateOID().

removeValue	(	$	name,
		$	type = `null`
	)

Remove a named item.

Parameters:

	name	The name of the item to remove.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item value of any type that matches will be returned)

Definition at line 469 of file class.PersistentObject.php.

getUnconvertedValue	(	$	name,
		$	type = `null`
	)

Get the unconverted value of a named item.

Parameters:

	name	The name of the item to query.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item value of any type that matches will be returned)

Returns:: The unconverted value of the item / null if it doesn't exits.

Definition at line 490 of file class.PersistentObject.php.

References getDataConverter(), getValue(), and getValueProperty().

Referenced by UserRDBBase::getConfig(), UserRDBBase::getFirstname(), NMUserRoleBase::getFkRoleId(), NMUserRoleBase::getFkUserId(), LocktableBase::getFkUserId(), UserRDBBase::getId(), RoleRDBBase::getId(), LocktableBase::getId(), AdodbseqBase::getId(), UserRDBBase::getLogin(), UserRDBBase::getName(), RoleRDBBase::getName(), LocktableBase::getObjectid(), UserRDBBase::getPassword(), LocktableBase::getSessionid(), and LocktableBase::getSince().

Here is the call graph for this function:

getConvertedValue	(	$	name,
		$	type = `null`
	)

Get the converted value of a named item.

Parameters:

	name	The name of the item to query.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item value of any type that matches will be returned)

Returns:: The converted value of the item / null if it doesn't exits.

Note:: The result is normally equal to that of PersistentObject::getValue() except, when the value is unconverted

Definition at line 506 of file class.PersistentObject.php.

References getDataConverter(), getValue(), and getValueProperty().

Here is the call graph for this function:

getValueTypes ( $ name )

Get the type of a named item.

Parameters:

name

The name of the item to query.

Returns:: An array containig the types of the value (in most cases this array will have length 1).

Definition at line 519 of file class.PersistentObject.php.

validateValue	(	$	name,
		$	value,
		$	type = `null`
	)

Check if data may be set. The method is also called, when setting a value. Controller may call this method before setting data and saving the object.

Parameters:

	name	The name of the item to set.
	value	The value of the item.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item of any type that matches will be modified)

Returns:: Empty string if validation succeeded, an error string else. The default implementation returns an empty string.

Note:: Subclasses will override this method to implement special application requirements.

Definition at line 537 of file class.PersistentObject.php.

Referenced by setValue().

setValue	(	$	name,
		$	value,
		$	type = `null`,
		$	forceSet = `false`
	)

Set the value of a named item if it exists.

Parameters:

	name	The name of the item to set.
	value	The value of the item.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item of any type that matches will be modified)
	forceSet	Set the value even if it is already set (used to notify listeners) [default: false]

Returns:: true if operation succeeds / false else

Definition at line 550 of file class.PersistentObject.php.

References getValue(), propagateValueChange(), setState(), WCMFException::throwEx(), updateOID(), and validateValue().

Referenced by UserImpl::setConfig(), UserRDBBase::setConfig(), UserImpl::setFirstname(), UserRDBBase::setFirstname(), NMUserRoleBase::setFkRoleId(), NMUserRoleBase::setFkUserId(), LocktableBase::setFkUserId(), UserRDBBase::setId(), RoleRDBBase::setId(), LocktableBase::setId(), AdodbseqBase::setId(), UserImpl::setLogin(), UserRDBBase::setLogin(), UserImpl::setName(), RoleImpl::setName(), UserRDBBase::setName(), RoleRDBBase::setName(), LocktableBase::setObjectid(), setOID(), UserImpl::setPassword(), UserRDBBase::setPassword(), NMUserRoleBase::setRoleRDB(), LocktableBase::setSessionid(), LocktableBase::setSince(), and NMUserRoleBase::setUserRDB().

Here is the call graph for this function:

getValueProperties	(	$	name,
		$	type = `null`
	)

Get the properties of a named item.

Parameters:

	name	The name of the item to query.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item value of any type that matches will be returned)

Returns:: An associative array holding the properties of the item / null if it doesn't exits.

Reimplemented in Table.

Definition at line 601 of file class.PersistentObject.php.

Referenced by getValueProperty(), setValueProperty(), and toString().

setValueProperties	(	$	name,
		$	properties,
		$	type = `null`
	)

Set the properties of a named item.

Parameters:

	name	The name of the item to set its properties.
	properties	An associative array holding the properties of the item.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item of any type that matches will be modified)

Returns:: true/false whether the value was set.

Reimplemented in Table.

Definition at line 624 of file class.PersistentObject.php.

References setState().

Referenced by setValueProperty().

Here is the call graph for this function:

getValueProperty	(	$	name,
		$	property,
		$	type = `null`
	)

Get the value of one property of a named item.

Parameters:

	name	The name of the item to set its properties.
	property	The name of the property to set.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item of any type that matches will be modified)

Returns:: The value property/null if not found.

Definition at line 657 of file class.PersistentObject.php.

References getValueProperties().

Referenced by getConvertedValue(), and getUnconvertedValue().

Here is the call graph for this function:

setValueProperty	(	$	name,
		$	property,
		$	value,
		$	type = `null`
	)

Set the value of one property of a named item.

Parameters:

	name	The name of the item to set its properties.
	property	The name of the property to set.
	value	The value to set on the property.
	type	The type of the item as defined in the subclass [optional] (if type is omitted the first item of any type that matches will be modified)

Returns:: true/false whether the value was set.

Definition at line 674 of file class.PersistentObject.php.

References getValueProperties(), and setValueProperties().

Referenced by setImmutable().

Here is the call graph for this function:

getValueNames ( $ type = null )

Get the names of all items.

Parameters:

type

The type of the item as defined in the subclass [optional] (if type is omitted all names will be returned)

Returns:: array of all item names.

Definition at line 690 of file class.PersistentObject.php.

Referenced by Table::getNumRows(), hasValue(), setImmutable(), and toString().

getDataTypes ( )

Get all datatypes.

Returns:: array of all datatypes.

Definition at line 705 of file class.PersistentObject.php.

Referenced by Table::getColumns(), setImmutable(), and toString().

getProperty ( $ name )

Get the value of a named property in the object.

Parameters:

name

The name of the property to query.

Returns:: The value of the property / null if it doesn't exits.

Definition at line 714 of file class.PersistentObject.php.

Referenced by UserRDBBase::getChildrenEx(), RoleRDBBase::getChildrenEx(), Node::getNumChildren(), Node::getNumParents(), Node::loadChildren(), Node::loadParents(), setProperty(), and toString().

setProperty	(	$	name,
		$	value
	)

Set the value of a named property in the object.

Parameters:

	name	The name of the property to set.
	value	The value of the property to set.

Definition at line 726 of file class.PersistentObject.php.

References getProperty(), and propagatePropertyChange().

Here is the call graph for this function:

getPropertyNames ( )

Get the names of all properties in the object.

Returns:: An array consisting the names.

Definition at line 736 of file class.PersistentObject.php.

Referenced by toString().

addChangeListener ( &$ listener )

ChangeListener Support Add a change listener (Must be of type ChangeListener).

Parameters:

listener

The ChangeListener.

Definition at line 749 of file class.PersistentObject.php.

removeChangeListener ( &$ listener )

Remove a change listener (Must be of type ChangeListener).

Parameters:

listener

The ChangeListener.

Definition at line 757 of file class.PersistentObject.php.

propagateValueChange	(	$	name,
		$	type,
		$	oldValue,
		$	newValue
	)

Notify ChangeListeners of value changes.

Parameters:

	name	The name of the item that has changed.
	type	The type of the item that has changed.
	oldValue	The old value of the item that has changed
	newValue	The new value of the item that has changed