Detailed Description

Node adds the concept of relations to PersistentObject.

It is the basic component for building object trees (although a Node can have more than one parents). Relations are stored as values where the value name is the role name. The Node class implements the Composite Pattern. Use the methods addNode(), deleteNode() to build/modify trees.

Author
ingo herwig ingo@.nosp@m.wemo.nosp@m.ve.co.nosp@m.m

Definition at line 34 of file Node.php.

+ Inheritance diagram for Node:

Public Member Functions

 __construct (ObjectId $oid=null, array $initialData=null)
 
 getValueNames ($excludeTransient=false)
 
 getValue ($name)
 
 setValue ($name, $value, $forceSet=false, $trackChange=true)
 
 removeValue ($name)
 
 getIndispensableObjects ()
 
 mergeValues (PersistentObject $object)
 
 getRelationNames ()
 
 addNode (PersistentObject $other, $role=null, $forceSet=false, $trackChange=true, $updateOtherSide=true)
 
 getAddedNodes ()
 
 deleteNode (PersistentObject $other, $role=null, $updateOtherSide=true)
 
 getDeletedNodes ()
 
 setNodeOrder (array $orderedList, array $movedList=null, $role=null)
 
 getNodeOrder ()
 
 loadChildren ($role=null, $buildDepth=BuildDepth::SINGLE)
 
 getNumChildren ($memOnly=true)
 
 getFirstChild ($role=null, $type=null, $values=null, $properties=null, $useRegExp=true)
 
 getChildren ($memOnly=true)
 
 getChildrenEx (ObjectId $oid=null, $role=null, $type=null, $values=null, $properties=null, $useRegExp=true)
 
 getPossibleChildren ()
 
 loadParents ($role=null, $buildDepth=BuildDepth::SINGLE)
 
 getNumParents ($memOnly=true)
 
 getParent ()
 
 getFirstParent ($role=null, $type=null, $values=null, $properties=null, $useRegExp=true)
 
 getParents ($memOnly=true)
 
 getParentsEx (ObjectId $oid=null, $role=null, $type=null, $values=null, $properties=null, $useRegExp=true)
 
 getPossibleParents ()
 
 getNodeRelation ($object)
 
 getRelatives ($hierarchyType, $memOnly=true)
 
 getNumRelatives ($hierarchyType, $memOnly=true)
 
 acceptVisitor ($visitor)
 
 addRelation ($name)
 
 getDisplayValue ()
 
 __toString ()
 
- Public Member Functions inherited from DefaultPersistentObject
 __construct (ObjectId $oid=null, array $initialData=null)
 
 getType ()
 
 getMapper ()
 
 getOID ()
 
 setOID (ObjectId $oid)
 
 getState ()
 
 setState ($state)
 
 delete ()
 
 __clone ()
 
 copyValues (PersistentObject $object, $copyPkValues=true)
 
 mergeValues (PersistentObject $object)
 
 clearValues ()
 
 afterCreate ()
 
 beforeInsert ()
 
 afterInsert ()
 
 afterLoad ()
 
 beforeUpdate ()
 
 afterUpdate ()
 
 beforeDelete ()
 
 afterDelete ()
 
 getValue ($name)
 
 setValue ($name, $value, $forceSet=false, $trackChange=true)
 
 hasValue ($name)
 
 removeValue ($name)
 
 validateValues ()
 
 validateValue ($name, $value)
 
 getChangedValues ()
 
 getOriginalValues ()
 
 getIndispensableObjects ()
 
 getProperty ($name)
 
 setProperty ($name, $value)
 
 getPropertyNames ()
 
 getValueProperty ($name, $property)
 
 setValueProperty ($name, $property, $value)
 
 getValuePropertyNames ($name)
 
 getValueNames ($excludeTransient=false)
 
 getDisplayValue ()
 
 dump ()
 
 __toString ()
 
 serialize ()
 
 unserialize ($serialized)
 

Static Public Member Functions

static filter (array $nodeList, ObjectId $oid=null, $type=null, $values=null, $properties=null, $useRegExp=true)
 

Public Attributes

const RELATION_STATE_UNINITIALIZED = -1
 
const RELATION_STATE_INITIALIZING = -2
 
const RELATION_STATE_INITIALIZED = -3
 
const RELATION_STATE_LOADED = -4
 
- Public Attributes inherited from PersistentObject
const STATE_CLEAN = 0
 
const STATE_DIRTY = 1
 
const STATE_NEW = 2
 
const STATE_DELETED = 3
 

Protected Member Functions

 loadRelations (array $roles, $buildDepth=BuildDepth::SINGLE)
 
 getRelations ($hierarchyType='all')
 
- Protected Member Functions inherited from DefaultPersistentObject
 setOIDInternal (ObjectId $oid, $triggerListeners)
 
 setValueInternal ($name, $value)
 
 validateValueAgainstValidateType ($name, $value)
 

Static Protected Member Functions

static mergeObjectLists ($list1, $list2)
 

Constructor & Destructor Documentation

__construct ( ObjectId  $oid = null,
array  $initialData = null 
)

Constructor.

Parameters
$oidObjectId instance (optional)
$initialDataAssociative array with initial data to override default data (optional)

Definition at line 55 of file Node.php.

Member Function Documentation

getValueNames (   $excludeTransient = false)
See also
PersistentObject::getValueNames()

Implements PersistentObject.

Definition at line 71 of file Node.php.

getValue (   $name)
See also
PersistentObject::getValue()

Implements PersistentObject.

Definition at line 87 of file Node.php.

setValue (   $name,
  $value,
  $forceSet = false,
  $trackChange = true 
)
See also
PersistentObject::setValue()

Implements PersistentObject.

Definition at line 115 of file Node.php.

removeValue (   $name)
See also
PersistentObject::removeValue()

Implements PersistentObject.

Definition at line 144 of file Node.php.

getIndispensableObjects ( )
See also
PersistentObject::getIndispensableObjects()

Implements PersistentObject.

Definition at line 156 of file Node.php.

static filter ( array  $nodeList,
ObjectId  $oid = null,
  $type = null,
  $values = null,
  $properties = null,
  $useRegExp = true 
)
static

Get Nodes that match given conditions from a list.

Parameters
$nodeListAn array of nodes to filter or a single Node.
$oidThe object id that the Nodes should match (optional, default: null)
$typeThe type that the Nodes should match (either fully qualified or simple, if not ambiguous) (optional, default: null)
$valuesAn associative array holding key value pairs that the Node values should match (values are interpreted as regular expression, optional, default: null)
$propertiesAn associative array holding key value pairs that the Node properties should match (values are interpreted as regular expression, optional, default: null)
$useRegExpBoolean whether to interpret the given values/properties as regular expressions or not (default: true)
Returns
An Array holding references to the Nodes that matched.

Definition at line 174 of file Node.php.

mergeValues ( PersistentObject  $object)
See also
PersistentObject::mergeValues

Implements PersistentObject.

Definition at line 231 of file Node.php.

static mergeObjectLists (   $list1,
  $list2 
)
staticprotected

Merge two object lists using the following rules:

  • proxies in list1 are replaced by the appropriate objects from list2
  • proxies/objects from list2 that don't exist in list1 are added to list1
    Parameters
    $list1Array of PersistentObject(Proxy) instances
    $list2Array of PersistentObject(Proxy) instances
    Returns
    Associative array with keys 'result' and 'added' and arrays of all and only added objects respectively.

Definition at line 259 of file Node.php.

getRelationNames ( )

Get the names of all relations.

Returns
An array of relation names.

Definition at line 294 of file Node.php.

addNode ( PersistentObject  $other,
  $role = null,
  $forceSet = false,
  $trackChange = true,
  $updateOtherSide = true 
)

Add a Node to the given relation.

Delegates to setValue internally.

Parameters
$otherPersistentObject
$roleThe role of the Node in the created relation. If null, the role will be the Node's simple type (without namespace) (default: null)
$forceSet
See also
PersistentObject::setValue()
Parameters
$trackChange
See also
PersistentObject::setValue()
Parameters
$updateOtherSideBoolean whether to update also the other side of the relation (default: true)
Returns
Boolean whether the operation succeeds or not

Definition at line 313 of file Node.php.

getAddedNodes ( )

Get the object ids of the nodes that were added since the node was loaded.

Persistence mappers use this method when persisting the node relations.

Returns
Associative array with the roles as keys and an array of PersistentObject instances as values

Definition at line 363 of file Node.php.

deleteNode ( PersistentObject  $other,
  $role = null,
  $updateOtherSide = true 
)

Delete a Node from the given relation.

Parameters
$otherThe Node to delete.
$roleThe role of the Node. If null, the role is the Node's type (without namespace) (default: null)
$updateOtherSideBoolean whether to update also the other side of the relation (default: true)

Definition at line 373 of file Node.php.

getDeletedNodes ( )

Get the object ids of the nodes that were deleted since the node was loaded.

Persistence mappers use this method when persisting the node relations.

Returns
Associative array with the roles as keys and an array of ObjectId instances as values

Definition at line 432 of file Node.php.

setNodeOrder ( array  $orderedList,
array  $movedList = null,
  $role = null 
)

Define the order of related Node instances.

The mapper is responsible for persisting the order of the given Node instances in relation to this Node.

Note
Note instances, that are not explicitly sortable by a sortkey (
See also
PersistenceMapper::getDefaultOrder()) will be ignored. If a given Node instance is not related to this Node yet, an exception will be thrown. Any not persisted definition of a previous call will be overwritten
Parameters
$orderedListArray of ordered Node instances
$movedListArray of repositioned Node instances (optional, improves performance)
$roleRole name of the Node instances (optional)

Definition at line 447 of file Node.php.

getNodeOrder ( )

Get the order of related Node instances, if it was defined using the Node::setNodeOrder() method.

Returns
Associative array of with keys 'ordered', 'moved', 'role' or null

Definition at line 461 of file Node.php.

loadChildren (   $role = null,
  $buildDepth = BuildDepth::SINGLE 
)

Load the children of a given role and add them.

If all children should be loaded, set the role parameter to null.

Parameters
$roleThe role of children to load (maybe null, to load all children) (default: null)
$buildDepthOne of the BUILDDEPTH constants or a number describing the number of generations to build (default: BuildDepth::SINGLE)

Definition at line 472 of file Node.php.

getNumChildren (   $memOnly = true)

Get the number of children of the Node.

Parameters
$memOnlyBoolean whether to only get the number of loaded children or all children (default: true).
Returns
The number of children.

Definition at line 486 of file Node.php.

getFirstChild (   $role = null,
  $type = null,
  $values = null,
  $properties = null,
  $useRegExp = true 
)

Get the first child that matches given conditions.

Parameters
$roleThe role that the child should match (optional, default: null).
$typeThe type that the child should match (either fully qualified or simple, if not ambiguous) (optional, default: null).
$valuesAn associative array holding key value pairs that the child values should match (optional, default: null).
$propertiesAn associative array holding key value pairs that the child properties should match (optional, default: null).
$useRegExpBoolean whether to interpret the given values/properties as regular expressions or not (default: true)
Returns
Node instance or null.

Definition at line 500 of file Node.php.

getChildren (   $memOnly = true)

Get the Node's children.

Parameters
$memOnlyBoolean whether to only get the loaded children or all children (default: true).
Returns
Array PersistentObject instances.

Definition at line 515 of file Node.php.

getChildrenEx ( ObjectId  $oid = null,
  $role = null,
  $type = null,
  $values = null,
  $properties = null,
  $useRegExp = true 
)

Get the children that match given conditions.

Note
This method will only return objects that are already loaded, to get all objects in the given relation (including proxies), use the Node::getValue() method and filter the returned list afterwards.
Parameters
$oidThe object id that the children should match (optional, default: null).
$roleThe role that the children should match (optional, default: null).
$typeThe type that the children should match (either fully qualified or simple, if not ambiguous) (optional, default: null).
$valuesAn associative array holding key value pairs that the children values should match (optional, default: null).
$propertiesAn associative array holding key value pairs that the children properties should match (optional, default: null).
$useRegExpBoolean whether to interpret the given values/properties as regular expressions or not (default: true)
Returns
Array containing children Nodes that matched (proxies not included).

Definition at line 533 of file Node.php.

getPossibleChildren ( )

Get possible children of this node type (independent of existing children).

Returns
An Array with role names as keys and RelationDescription instances as values.

Definition at line 565 of file Node.php.

loadParents (   $role = null,
  $buildDepth = BuildDepth::SINGLE 
)

Load the parents of a given role and add them.

If all parents should be loaded, set the role parameter to null.

Parameters
$roleThe role of parents to load (maybe null, to load all parents) (default: null)
$buildDepthOne of the BUILDDEPTH constants or a number describing the number of generations to build (default: BuildDepth::SINGLE)

Definition at line 581 of file Node.php.

getNumParents (   $memOnly = true)

Get the number of parents of the Node.

Parameters
$memOnlyBoolean whether to only get the number of loaded parents or all parents (default: true).
Returns
The number of parents.

Definition at line 595 of file Node.php.

getParent ( )

Get the Node's parent.

This method exists for compatibility with previous versions. It returns the first parent.

Returns
Node

Definition at line 604 of file Node.php.

getFirstParent (   $role = null,
  $type = null,
  $values = null,
  $properties = null,
  $useRegExp = true 
)

Get the first parent that matches given conditions.

Parameters
$roleThe role that the parent should match (optional, default: null).
$typeThe type that the parent should match (either fully qualified or simple, if not ambiguous) (optional, default: null).
$valuesAn associative array holding key value pairs that the parent values should match (optional, default: null).
$propertiesAn associative array holding key value pairs that the parent properties should match (optional, default: null).
$useRegExpBoolean whether to interpret the given values/properties as regular expressions or not (default: true)
Returns
Node instance or null.

Definition at line 624 of file Node.php.

getParents (   $memOnly = true)

Get the Nodes parents.

Parameters
$memOnlyBoolean whether to only get the loaded parents or all parents (default: true).
Returns
Array PersistentObject instances.

Definition at line 640 of file Node.php.

getParentsEx ( ObjectId  $oid = null,
  $role = null,
  $type = null,
  $values = null,
  $properties = null,
  $useRegExp = true 
)

Get the parents that match given conditions.

Note
This method will only return objects that are already loaded, to get all objects in the given relation (including proxies), use the Node::getValue() method and filter the returned list afterwards.
Parameters
$oidThe object id that the parent should match (optional, default: null).
$roleThe role that the parents should match (optional, default: null).
$typeThe type that the parents should match (either fully qualified or simple, if not ambiguous) (optional, default: null).
$valuesAn associative array holding key value pairs that the parent values should match (optional, default: null).
$propertiesAn associative array holding key value pairs that the parent properties should match (optional, default: null).
$useRegExpBoolean whether to interpret the given values/properties as regular expressions or not (default: true)
Returns
Array containing parent Nodes that matched (proxies not included).

Definition at line 658 of file Node.php.

getPossibleParents ( )

Get possible parents of this node type (independent of existing parents).

Returns
An Array with role names as keys and RelationDescription instances as values.

Definition at line 690 of file Node.php.

getNodeRelation (   $object)

Get the relation description for a given node.

Parameters
$objectPersistentObject instance to look for
Returns
RelationDescription instance or null, if the Node is not related

Definition at line 704 of file Node.php.

loadRelations ( array  $roles,
  $buildDepth = BuildDepth::SINGLE 
)
protected

Load all objects in the given set of relations.

Parameters
$rolesAn array of relation (=role) names
$buildDepthOne of the BUILDDEPTH constants or a number describing the number of generations to build (default: BuildDepth::SINGLE)

Definition at line 728 of file Node.php.

getRelations (   $hierarchyType = 'all')
protected

Get the relation descriptions of a given hierarchyType.

Parameters
$hierarchyType
See also
PersistenceMapper::getRelations (default: 'all')
Returns
An array containing the RelationDescription instances.

Definition at line 774 of file Node.php.

getRelatives (   $hierarchyType,
  $memOnly = true 
)

Get the relatives of a given hierarchyType.

Parameters
$hierarchyType
See also
PersistenceMapper::getRelations
Parameters
$memOnlyBoolean whether to only get the relatives in memory or all relatives (including proxies) (default: true).
Returns
An array containing the relatives.

Definition at line 784 of file Node.php.

getNumRelatives (   $hierarchyType,
  $memOnly = true 
)

Get the number of relatives of a given hierarchyType.

Parameters
$hierarchyType
See also
PersistenceMapper::getRelations
Parameters
$memOnlyBoolean whether to only get the number of the relatives in memory or all relatives (default: true).
Returns
The number of relatives.

Definition at line 820 of file Node.php.

acceptVisitor (   $visitor)

Accept a Visitor.

For use with the Visitor Pattern.

Parameters
$visitorVisitor instance.

Definition at line 828 of file Node.php.

addRelation (   $name)

Add an uninitialized relation.

The relation will be initialized (proxies for related objects will be added) on first access.

Parameters
$nameThe relation name (= role)

Definition at line 838 of file Node.php.

getDisplayValue ( )

Output.

See also
PersistentObject::getDisplayValue() Delegates to NodeUtil::getDisplayValue

Implements PersistentObject.

Definition at line 853 of file Node.php.

__toString ( )

Get a string representation of the Node.

Returns
The string representation of the Node.

Definition at line 861 of file Node.php.

Member Data Documentation

const RELATION_STATE_UNINITIALIZED = -1

Definition at line 36 of file Node.php.

const RELATION_STATE_INITIALIZING = -2

Definition at line 37 of file Node.php.

const RELATION_STATE_INITIALIZED = -3

Definition at line 38 of file Node.php.

const RELATION_STATE_LOADED = -4

Definition at line 39 of file Node.php.