/**
* Returns the related objects of a given $relatedClass for $object.
*
* This method returns the related objects of type $relatedClass for the
* given $object. This method (in contrast to {@link getRelatedObject()})
* always returns an array of found objects, no matter if only 1 object
* was found (e.g. {@link ezcPersistentManyToOneRelation}), none or several
* ({@link ezcPersistentManyToManyRelation}).
*
* In case the set of related objects has already been fetched earlier, the
* request to the database is not repeated, but the recorded object set is
* returned. If the set of related objects was not recorded, yet, it is
* fetched from the database and recorded afterwards.
*
* Example:
* <code>
* $person = $session->load( "Person", 1 );
* $relatedAddresses = $session->getRelatedObjects( $person, "Address" );
* echo "Number of addresses found: " . count( $relatedAddresses );
* </code>
*
* Relations that should preferably be used with this method are:
* <ul>
* <li>{@link ezcPersistentOneToManyRelation}</li>
* <li>{@link ezcPersistentManyToManyRelation}</li>
* </ul>
* For other relation types {@link getRelatedObject()} is recommended.
*
* If multiple relations are defined for the $relatedClass (using {@link
* ezcPersistentRelationCollection}), the parameter $relationName becomes
* mandatory to determine which relation definition to use. For normal
* relations, this parameter is silently ignored.
*
* @param object $object
* @param string $relatedClass
* @param string $relationName
*
* @return array(int=>object($relatedClass))
*
* @throws ezcPersistentRelationNotFoundException
* if the given $object does not have a relation to $relatedClass.
*/
public function getRelatedObjects($object, $relatedClass, $relationName = null)
{
if (!$this->properties['options']->refetch) {
$relatedObjs = $this->identityMap->getRelatedObjects($object, $relatedClass, $relationName);
if ($relatedObjs !== null) {
return $relatedObjs;
}
}
$relatedObjs = $this->session->getRelatedObjects($object, $relatedClass, $relationName);
$storedRelatedObjs = $this->identityMap->setRelatedObjects($object, $relatedObjs, $relatedClass, $relationName, $this->properties['options']->refetch);
return $storedRelatedObjs;
}
