Apache Zeta Components - high quality PHP components

Tutorial
API

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