Zeta Components - high quality PHP components

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:

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