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

### PersistentObject::ezcPersistentBasicIdentityMap

### Class ezcPersistentBasicIdentityMap

Default identity map used in ezcPersistentSessionIdentityDecorator.

An instance of this class is used in ezcPersistentSessionIdentityDecorator to perform the internal work of storing and retrieving object identities.

Source for this file: /PersistentObject/src/identity_maps/basic.php

### Implements interfaces:

- ezcPersistentIdentityMap

Version: | //autogen//

### Member Variables

protected ezcPersistentDefinitionManager | `$definitionManager` Definition manager used by ezcPersistentSession.

protected array(string=>array(mixed=>ezcPersistentIdentity))

`$identities = array()`
Object identities.

Structure:

1. <?php
2. array(
3. '<className>'=>array(
4. '<id1>'=>ezcPersistentIdentity (),
5. '<id2>'=>ezcPersistentIdentity (),
6. // ...
7. ),
8. '<anotherClassName>'=>array(
9. '<idA>'=>ezcPersistentIdentity (),
10. '<idB>'=>ezcPersistentIdentity (),
11. // ...
12. ),
13. // ...
14. );
15. ?>

### Method Summary

public ezcPersistentBasicIdentityMap | `__construct( $definitionManager )` Creates a new identity map.
public void | `addRelatedObject( $sourceObject , $relatedObject , [ $relationName = null] )` Appends a new $relatedObject to a related object set of $sourceObject.
protected string | `createRelationStoreName( $relatedClass , $relationName )` Creates the related object set identifier for $relatedClass and $relationName.
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.
protected void | `removeAllReferences( $sets )` Removes all references to all $sets from all objects in $sets.
public void | `removeIdentity( $class , $id )` Removes the object of $class width $id from the map.
protected void | `removeIdentityReferences( $identity )` Removes all references to $identity.
protected void | `removeReferences( $set )` Removes all references to $set from the objects in $set.
public void | `removeRelatedObject( $sourceObject , $relatedObject , [ $relationName = null] )` Removes a $relatedObject from the sets of related objects of $sourceObject.
protected void | `replaceIdentityReferences( $oldIdentity , $newIdentity )` Replaces all references to $oldIdentity with a reference to $newIdentity.
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

#### __construct

ezcPersistentBasicIdentityMap __construct( ezcPersistentDefinitionManager $definitionManager )

Creates a new identity map.

Creates a new identity map, which makes use of the given $definitionManager to determine object identities and relations.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$definitionManager` | ezcPersistentDefinitionManager |

#### 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.

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::addRelatedObject()` | Appends a new $relatedObject to a related object set of $sourceObject.

#### createRelationStoreName

string createRelationStoreName( string $relatedClass , string $relationName )

Creates the related object set identifier for $relatedClass and $relationName.

Determines the unique name for relations of $relatedClass with $relationName (can be null).

##### Parameters:

Name | Type | Description
--- | --- | ---
`$relatedClass` | string |
`$relationName` | string |

#### 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 |

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::getIdentity()` | Returns the object of $class with $id or null.

#### 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.

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::getRelatedObjects()` | Returns the set of related objects of $relatedClass for $sourceObject.

#### 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 |

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::getRelatedObjectSet()` | Returns the named set of related objects for $sourceObject with $setName.

#### removeAllReferences

void removeAllReferences( $sets )

Removes all references to all $sets from all objects in $sets.

Removes all references to all object $sets from all objects contained in each of the $sets.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$sets` | array(ArrayObject) |

#### 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 |

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::removeIdentity()` | Removes the object of $class width $id from the map.

#### removeIdentityReferences

void removeIdentityReferences( ezcPersistentIdentity $identity )

Removes all references to $identity.

Scans all sets referred in ezcPersistentIdentity::$references and removes $identity from them. This is used, if the $identity is to be removeIdenity(), to ensure it does not occur in any related set or named related set anymore.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$identity` | ezcPersistentIdentity |

#### removeReferences

void removeReferences( $set )

Removes all references to $set from the objects in $set.

Maintains the ezcPersistentIdentity::$references attribute by removing all refereneces to $set from all object identities contained in $set.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$set` | ArrayObject |

#### 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.

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::removeRelatedObject()` | Removes a $relatedObject from the sets of related objects of $sourceObject.

#### replaceIdentityReferences

void replaceIdentityReferences( ezcPersistentIdentity $oldIdentity , ezcPersistentIdentity $newIdentity )

Replaces all references to $oldIdentity with a reference to $newIdentity.

Scans all sets refered in ezcPersistentIdentity::$references of the $oldIdentity and replaces the references to $oldIdentity with $newIdentity in them. This mechanism is used whenever an identity is to be replaced by a new one.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$oldIdentity` | ezcPersistentIdentity |
`$newIdentity` | ezcPersistentIdentity |

#### reset

void reset( )

Resets the complete identity map.

Removes all stored identities from the map and resets it into its initial state.

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::reset()` | Resets the complete identity map.

#### 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 |

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::setIdentity()` | Records the identity of $object.

#### 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.

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::setRelatedObjects()` | Records a set of $relatedObjects to $sourceObject.

#### 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.

##### Implementation of:

Method | Description
--- | ---
`ezcPersistentIdentityMap::setRelatedObjectSet()` | Records a named set of $relatedObjects for $sourceObject.

Documentation generated by phpDocumentor 1.4.3