## Apache Zeta Components Manual :: Docs For Class ezcPersistentIdentityMap

### PersistentObject::ezcPersistentIdentityMap

### Interface ezcPersistentIdentityMap

Identity map interface.

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

Source for this file: /PersistentObject/src/interfaces/identity_map.php

Version: | //autogen//

### Method Summary

public void | `addRelatedObject( $sourceObject , $relatedObject , [ $relationName = null] )` 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] )` 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] )` 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] )` Records a set of $relatedObjects to $sourceObject.
public array(ezcPersistentObject) | `setRelatedObjectSet( $sourceObject , $relatedObjects , $setName , [ $replaceIdentities = false] )` Records a named set of $relatedObjects for $sourceObject.

### Methods

#### addRelatedObject

void addRelatedObject( ezcPersistentObject $sourceObject , ezcPersistentObject $relatedObject , [string $relationName = null] )

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 |

##### Exceptions:

Type | Description
--- | ---
`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 , [string $relationName = null] )

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 |

##### Exceptions:

Type | Description
--- | ---
`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 , [string $relationName = null] )

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 |

##### Exceptions:

Type | Description
--- | ---
`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] , [bool $replaceIdentities = false] )

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 |

##### Exceptions:

Type | Description
--- | ---
`ezcPersistentIdentityRelatedObjectsInconsistentException` | if an object in $relatedObjects is not of $relatedClass.

#### setRelatedObjectSet

array(ezcPersistentObject) setRelatedObjectSet( ezcPersistentObject $sourceObject , $relatedObjects , string $setName , [bool $replaceIdentities = false] )

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 |

##### Exceptions:

Type | Description
--- | ---
`ezcPersistentIdentityRelatedObjectsInconsistentException` | if an object in $relatedObjects is not of $relatedClass.

Documentation generated by phpDocumentor 1.4.3