Path

ez components / documentation / api reference / 2009.1.2 / persistentobject

eZ Components 2009.1.2

PersistentObject: ezcPersistentIdentityMap

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Interface: ezcPersistentIdentityMap

Identity map interface. [source]
An instance of a class implementing this interface is used in ezcPersistentSessionIdentityDecorator to performs the internal work of storing and retrieving object identities.

Method Summary

public void addRelatedObject( $sourceObject, $relatedObject, [$relationName = null], $relationName )
Appends a new $relatedObject to a related object set of $sourceObject.
public object($class)|null getIdentity( $class, $id )
Returns the object of $class with $id or null.
public array(object($relatedClass))|null getRelatedObjects( $sourceObject, $relatedClass, [$relationName = null], $relationName )
Returns the set of related objects of $relatedClass for $sourceObject.
public array(object($relatedClass))|null getRelatedObjectSet( $sourceObject, $setName )
Returns the named set of related objects for $sourceObject with $setName.
public void removeIdentity( $class, $id )
Removes the object of $class width $id from the map.
public void removeRelatedObject( $sourceObject, $relatedObject, [$relationName = null], $relationName )
Removes a $relatedObject from the sets of related objects of $sourceObject.
public void reset( )
Resets the complete identity map.
public void setIdentity( $object )
Records the identity of $object.
public array(mixed=>object($relatedClass)) setRelatedObjects( $sourceObject, $relatedObjects, $relatedClass, [$relationName = null], [$replaceIdentities = false], $replaceIdentities )
Records a set of $relatedObjects to $sourceObject.
public array(ezcPersistentObject) setRelatedObjectSet( $sourceObject, $relatedObjects, $setName, [$replaceIdentities = false], $replaceIdentities )
Records a named set of $relatedObjects for $sourceObject.

Methods

addRelatedObject

void addRelatedObject( ezcPersistentObject $sourceObject, ezcPersistentObject $relatedObject, [ $relationName = null], string $relationName )
Appends a new $relatedObject to a related object set of $sourceObject.
Appends the given $relatedObject to the set of related objects for $sourceObject with the class of $relatedObject and optionally $relationName.
In case that no set of related objects with the specific class has been recorded for $object, yet, the call is ignored and related objects are newly fetched whenever getRelatedObjects() is called.
Note: All named related object sub-sets for $relatedObject are automatically invalidated by a call to the method. The identity map can not determine, to which named related object sub-set the $relatedObject might be added.

Parameters

Name Type Description
$sourceObject ezcPersistentObject  
$relatedObject ezcPersistentObject  
$relationName string  
$relationName  

Throws

ClassDescription
ezcPersistentRelationNotFoundException if no relation from $sourceObject to $relatedObject is defined.
ezcPersistentIdentityMissingException if no identity has been recorded for $sourceObject or $relatedObject, yet.
ezcPersistentIdentityRelatedObjectAlreadyExistsException if the given $relatedObject is already part of the set of related objects it should be added to.

getIdentity

object($class)|null getIdentity( string $class, mixed $id )
Returns the object of $class with $id or null.
Returns the object of $class with $id, if its identity has already been recorded. Otherwise null is returned.

Parameters

Name Type Description
$class string  
$id mixed  

getRelatedObjects

array(object($relatedClass))|null getRelatedObjects( ezcPersistentObject $sourceObject, string $relatedClass, [ $relationName = null], string $relationName )
Returns the set of related objects of $relatedClass for $sourceObject.
Returns the set of related objects of $relatedClass for $sourceObject. This might also be an empty set (empty array). In case no related objects are recorded, yet, null is returned.

Parameters

Name Type Description
$sourceObject ezcPersistentObject  
$relatedClass string  
$relationName string  
$relationName  

Throws

ClassDescription
ezcPersistentRelationNotFoundException if not relation between the class of $sourceObject and $relatedClass (with optionally $relationName) is defined.

getRelatedObjectSet

array(object($relatedClass))|null getRelatedObjectSet( ezcPersistentObject $sourceObject, string $setName )
Returns the named set of related objects for $sourceObject with $setName.
Returns the named set of related objects for $sourceObject identified by $setName. This might also be an empty set (empty array). In case no related objects with this name are recorded, yet, null is returned.

Parameters

Name Type Description
$sourceObject ezcPersistentObject  
$setName string  

removeIdentity

void removeIdentity( string $class, mixed $id )
Removes the object of $class width $id from the map.
Removes the identity of the object of $class with $id from the map and deletes all references of it. If the identity does not exist, the call is silently ignored.

Parameters

Name Type Description
$class string  
$id mixed  

removeRelatedObject

void removeRelatedObject( ezcPersistentObject $sourceObject, ezcPersistentObject $relatedObject, [ $relationName = null], string $relationName )
Removes a $relatedObject from the sets of related objects of $sourceObject.
Removes the $relatedObject from all recorded sets of related objects (named and unnamed) for $sourceObject. This method (in contrast to addRelatedObject()) does not invalidate named related object sets, but simply removes the $relatedObject from them.

Parameters

Name Type Description
$sourceObject ezcPersistentObject  
$relatedObject ezcPersistentObject  
$relationName string  
$relationName  

Throws

ClassDescription
ezcPersistentIdentityMissingException if no identity for $sourceObject has been recorded, yet.

reset

void reset( )
Resets the complete identity map.
Removes all stored identities from the map and resets it into its initial state.

setIdentity

void setIdentity( ezcPersistentObject $object )
Records the identity of $object.
Records the identity of $object. If an identity is already recorded for this object, it is silently replaced. The user of this method must take care of checking for already recorded identities of the given $object itself.

Parameters

Name Type Description
$object ezcPersistentObject  

setRelatedObjects

array(mixed=>object($relatedClass)) setRelatedObjects( ezcPersistentObject $sourceObject, $relatedObjects, string $relatedClass, [string $relationName = null], [ $replaceIdentities = false], bool $replaceIdentities )
Records a set of $relatedObjects to $sourceObject.
Records the given set of $relatedObjects for $sourceObject. $relationName is the optional name of the relation, which must be provided, if multiple relations from $sourceObject to the class of the objects in $relatedObjects exist.
In case a set of related objects has already been recorded for $sourceObject and the class of the objects in $relatedObjects (and optionally $relationName), the existing set is silently replaced and all references to it are removed.
If for any object in $relatedObjects no identity is recorded, yet, it will be recorded. Otherwise, the object will be replaced by its existing identity in the set. Except for if the $replaceIdentities parameter is set to true: In this case a new identity will be recorded for every object in $relatedObjects, replacing potentially existing ones silently.
If the given array of $relatedObjects is inconsistent (any contained object is not of $relatedClass), an ezcPersistentIdentityRelatedObjectsInconsistentException is thrown.
To avoid a call to getRelatedObjects() after this method has been called, the recorded set of related objects (including potentially replaced identities) is returned.

Parameters

Name Type Description
$sourceObject ezcPersistentObject  
$relatedObjects array(ezcPersistentObject)  
$relatedClass string  
$relationName string  
$replaceIdentities bool  
$replaceIdentities  

Throws

ClassDescription
ezcPersistentIdentityRelatedObjectsInconsistentException if an object in $relatedObjects is not of $relatedClass.

setRelatedObjectSet

array(ezcPersistentObject) setRelatedObjectSet( ezcPersistentObject $sourceObject, $relatedObjects, string $setName, [ $replaceIdentities = false], bool $replaceIdentities )
Records a named set of $relatedObjects for $sourceObject.
Records the given array of $relatedObjects with as a "named related object sub-set" for $sourceObject, using $setName. A named "named related object sub-set" contains only objects related to $sourceObject, but not necessarily all such objects of a certain class. Such a set is the result of ezcPersistentSessionIdentityDecorator::find() with a find query generated by ezcPersistentSessionIdentityDecorator::createFindQueryWithRelations() and manipulated using a WHERE clause.
In case a named set of related objects with $setName has already been recorded for $sourceObject, this set is silently replaced.
If for any of the objects in $relatedObjects no identity is recorded, yet, it will be recorded. Otherwise, the object will be replaced by its existing identity in the set. Except for if $replaceIdentities is set to true: In this case a new identity will be recorded for every object in $relatedObjects.
The method returns the created set of related objects to avoid another call to getRelatedObjectSet() by the using objct.

Parameters

Name Type Description
$sourceObject ezcPersistentObject  
$relatedObjects array(ezcPersistentObject)  
$setName string  
$replaceIdentities bool  
$replaceIdentities  

Throws

ClassDescription
ezcPersistentIdentityRelatedObjectsInconsistentException if an object in $relatedObjects is not of $relatedClass.

Last updated: Tue, 01 Sep 2009