/**
* Create a relation between $object and $relatedObject.
*
* This method is used to create a relation between the given source
* $object and the desired $relatedObject. The related object is not stored
* in the database automatically, only the desired properties are set. An
* exception is {@ezcPersistentManyToManyRelation}s, where the relation
* record is stored automatically and there is no need to store
* $relatedObject explicitly after establishing the relation.
*
* If there are multiple relations defined between the class of $object and
* $relatedObject (via {@link ezcPersistentRelationCollection}), the
* $relationName parameter becomes mandatory to determine, which exact
* relation should be used.
*
* Newly added related objects are stored in the identity map and added to
* recorded relation sets. If not set of related object set is recorded,
* yet, the adding is ignored.
*
* Note: All named related object sets (see {@link
* ezcPersistentFindWithRelationsQuery}) for $object are invalidated and
* removed from the identity map, to avoid inconsistencies.
*
* @param ezcPersistentObject $object
* @param ezcPersistentObject $relatedObject
* @param string $relationName
*
* @throws ezcPersistentRelationOperationNotSupportedException
* if a relation to create is marked as "reverse" {@link
* ezcPersistentRelation->reverse}.
* @throws ezcPersistentRelationNotFoundException
* if the deisred relation is not defined.
*/
public function addRelatedObject($object, $relatedObject, $relationName = null)
{
$this->session->addRelatedObject($object, $relatedObject, $relationName);
$this->identityMap->addRelatedObject($object, $relatedObject);
}
