RetailCRM-Mirror/doctrine2
1
0
Fork 0
mirror of synced 2025-01-31 12:32:59 +03:00
Code Issues Projects Releases Wiki Activity

Several fixes for comments

Browse Source 
updated @param and @throws annotations
This commit is contained in:
Thomas Rothe 2012-09-06 18:10:30 +02:00 committed by Thomas Rothe
parent ab990cfba6
commit 7beffb5a5f
1 changed files with 101 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
lib/Doctrine/ORM/UnitOfWork.php
View File

@ -206,7 +206,7 @@ class UnitOfWork implements PropertyChangedListener
/** /**
* The EventManager used for dispatching events. * The EventManager used for dispatching events.
* *
* @var EventManager * @var \Doctrine\Common\EventManager
*/ */
private $evm; private $evm;
@ -256,6 +256,9 @@ class UnitOfWork implements PropertyChangedListener
* 5) All entity deletions * 5) All entity deletions
* *
* @param null|object|array $entity * @param null|object|array $entity
*
* @throws \Exception
*
* @return void * @return void
*/ */
public function commit($entity = null) public function commit($entity = null)
@ -390,6 +393,9 @@ class UnitOfWork implements PropertyChangedListener
* 4. Only if entity is properly managed. * 4. Only if entity is properly managed.
* *
* @param object $entity * @param object $entity
*
* @throws \InvalidArgumentException
*
* @return void * @return void
*/ */
private function computeSingleEntityChangeSet($entity) private function computeSingleEntityChangeSet($entity)
@ -440,6 +446,8 @@ class UnitOfWork implements PropertyChangedListener
/** /**
* Gets the changeset for an entity. * Gets the changeset for an entity.
* *
* @param object $entity
*
* @return array * @return array
*/ */
public function getEntityChangeSet($entity) public function getEntityChangeSet($entity)
@ -708,8 +716,13 @@ class UnitOfWork implements PropertyChangedListener
/** /**
* Computes the changes of an association. * Computes the changes of an association.
* *
* @param AssociationMapping $assoc * @param array $assoc
* @param mixed $value The value of the association. * @param mixed $value The value of the association.
*
* @throws ORMInvalidArgumentException
* @throws ORMException
*
* @return void
*/ */
private function computeAssociationChanges($assoc, $value) private function computeAssociationChanges($assoc, $value)
{ {
@ -779,6 +792,10 @@ class UnitOfWork implements PropertyChangedListener
} }
} }
/**
* @param ClassMetadata $class
* @param object $entity
*/
private function persistNew($class, $entity) private function persistNew($class, $entity)
{ {
$oid = spl_object_hash($entity); $oid = spl_object_hash($entity);
@ -822,7 +839,8 @@ class UnitOfWork implements PropertyChangedListener
* @ignore * @ignore
* @param ClassMetadata $class The class descriptor of the entity. * @param ClassMetadata $class The class descriptor of the entity.
* @param object $entity The entity for which to (re)calculate the change set. * @param object $entity The entity for which to (re)calculate the change set.
* @throws InvalidArgumentException If the passed entity is not MANAGED. *
* @throws ORMInvalidArgumentException If the passed entity is not MANAGED.
*/ */
public function recomputeSingleEntityChangeSet(ClassMetadata $class, $entity) public function recomputeSingleEntityChangeSet(ClassMetadata $class, $entity)
{ {
@ -1025,6 +1043,8 @@ class UnitOfWork implements PropertyChangedListener
/** /**
* Gets the commit order. * Gets the commit order.
* *
* @param array $entityChangeSet
*
* @return array * @return array
*/ */
private function getCommitOrder(array $entityChangeSet = null) private function getCommitOrder(array $entityChangeSet = null)
@ -1099,6 +1119,9 @@ class UnitOfWork implements PropertyChangedListener
* If the entity already has an identifier, it will be added to the identity map. * If the entity already has an identifier, it will be added to the identity map.
* *
* @param object $entity The entity to schedule for insertion. * @param object $entity The entity to schedule for insertion.
*
* @throws ORMInvalidArgumentException
* @throws \InvalidArgumentException
*/ */
public function scheduleForInsert($entity) public function scheduleForInsert($entity)
{ {
@ -1134,6 +1157,7 @@ class UnitOfWork implements PropertyChangedListener
* Checks whether an entity is scheduled for insertion. * Checks whether an entity is scheduled for insertion.
* *
* @param object $entity * @param object $entity
*
* @return boolean * @return boolean
*/ */
public function isScheduledForInsert($entity) public function isScheduledForInsert($entity)
@ -1145,6 +1169,8 @@ class UnitOfWork implements PropertyChangedListener
* Schedules an entity for being updated. * Schedules an entity for being updated.
* *
* @param object $entity The entity to schedule for being updated. * @param object $entity The entity to schedule for being updated.
*
* @throws ORMInvalidArgumentException
*/ */
public function scheduleForUpdate($entity) public function scheduleForUpdate($entity)
{ {
@ -1194,6 +1220,7 @@ class UnitOfWork implements PropertyChangedListener
* at commit time. * at commit time.
* *
* @param object $entity * @param object $entity
*
* @return boolean * @return boolean
*/ */
public function isScheduledForUpdate($entity) public function isScheduledForUpdate($entity)
@ -1206,6 +1233,7 @@ class UnitOfWork implements PropertyChangedListener
* Checks whether an entity is registered to be checked in the unit of work. * Checks whether an entity is registered to be checked in the unit of work.
* *
* @param object $entity * @param object $entity
*
* @return boolean * @return boolean
*/ */
public function isScheduledForDirtyCheck($entity) public function isScheduledForDirtyCheck($entity)
@ -1256,6 +1284,7 @@ class UnitOfWork implements PropertyChangedListener
* of work. * of work.
* *
* @param object $entity * @param object $entity
*
* @return boolean * @return boolean
*/ */
public function isScheduledForDelete($entity) public function isScheduledForDelete($entity)
@ -1267,6 +1296,7 @@ class UnitOfWork implements PropertyChangedListener
* Checks whether an entity is scheduled for insertion, update or deletion. * Checks whether an entity is scheduled for insertion, update or deletion.
* *
* @param $entity * @param $entity
*
* @return boolean * @return boolean
*/ */
public function isEntityScheduled($entity) public function isEntityScheduled($entity)
@ -1286,6 +1316,9 @@ class UnitOfWork implements PropertyChangedListener
* *
* @ignore * @ignore
* @param object $entity The entity to register. * @param object $entity The entity to register.
*
* @throws ORMInvalidArgumentException
*
* @return boolean TRUE if the registration was successful, FALSE if the identity of * @return boolean TRUE if the registration was successful, FALSE if the identity of
* the entity in question is already managed. * the entity in question is already managed.
*/ */
@ -1317,6 +1350,7 @@ class UnitOfWork implements PropertyChangedListener
* This parameter can be set to improve performance of entity state detection * This parameter can be set to improve performance of entity state detection
* by potentially avoiding a database lookup if the distinction between NEW and DETACHED * by potentially avoiding a database lookup if the distinction between NEW and DETACHED
* is either known or does not matter for the caller of the method. * is either known or does not matter for the caller of the method.
*
* @return int The entity state. * @return int The entity state.
*/ */
public function getEntityState($entity, $assume = null) public function getEntityState($entity, $assume = null)
@ -1392,6 +1426,9 @@ class UnitOfWork implements PropertyChangedListener
* *
* @ignore * @ignore
* @param object $entity * @param object $entity
*
* @throws ORMInvalidArgumentException
*
* @return boolean * @return boolean
*/ */
public function removeFromIdentityMap($entity) public function removeFromIdentityMap($entity)
@ -1425,6 +1462,7 @@ class UnitOfWork implements PropertyChangedListener
* @ignore * @ignore
* @param string $idHash * @param string $idHash
* @param string $rootClassName * @param string $rootClassName
*
* @return object * @return object
*/ */
public function getByIdHash($idHash, $rootClassName) public function getByIdHash($idHash, $rootClassName)
@ -1440,6 +1478,7 @@ class UnitOfWork implements PropertyChangedListener
* @ignore * @ignore
* @param string $idHash * @param string $idHash
* @param string $rootClassName * @param string $rootClassName
*
* @return mixed The found entity or FALSE. * @return mixed The found entity or FALSE.
*/ */
public function tryGetByIdHash($idHash, $rootClassName) public function tryGetByIdHash($idHash, $rootClassName)
@ -1455,6 +1494,7 @@ class UnitOfWork implements PropertyChangedListener
* Checks whether an entity is registered in the identity map of this UnitOfWork. * Checks whether an entity is registered in the identity map of this UnitOfWork.
* *
* @param object $entity * @param object $entity
*
* @return boolean * @return boolean
*/ */
public function isInIdentityMap($entity) public function isInIdentityMap($entity)
@ -1482,6 +1522,7 @@ class UnitOfWork implements PropertyChangedListener
* @ignore * @ignore
* @param string $idHash * @param string $idHash
* @param string $rootClassName * @param string $rootClassName
*
* @return boolean * @return boolean
*/ */
public function containsIdHash($idHash, $rootClassName) public function containsIdHash($idHash, $rootClassName)
@ -1509,6 +1550,9 @@ class UnitOfWork implements PropertyChangedListener
* *
* @param object $entity The entity to persist. * @param object $entity The entity to persist.
* @param array $visited The already visited entities. * @param array $visited The already visited entities.
*
* @throws ORMInvalidArgumentException
* @throws UnexpectedValueException
*/ */
private function doPersist($entity, array &$visited) private function doPersist($entity, array &$visited)
{ {
@ -1578,7 +1622,9 @@ class UnitOfWork implements PropertyChangedListener
* *
* @param object $entity The entity to delete. * @param object $entity The entity to delete.
* @param array $visited The map of the already visited entities. * @param array $visited The map of the already visited entities.
* @throws InvalidArgumentException If the instance is a detached entity. *
* @throws ORMInvalidArgumentException If the instance is a detached entity.
* @throws UnexpectedValueException
*/ */
private function doRemove($entity, array &$visited) private function doRemove($entity, array &$visited)
{ {
@ -1627,10 +1673,12 @@ class UnitOfWork implements PropertyChangedListener
* Merges the state of the given detached entity into this UnitOfWork. * Merges the state of the given detached entity into this UnitOfWork.
* *
* @param object $entity * @param object $entity
* @return object The managed copy of the entity. *
* @throws OptimisticLockException If the entity uses optimistic locking through a version * @throws OptimisticLockException If the entity uses optimistic locking through a version
* attribute and the version check against the managed copy fails. * attribute and the version check against the managed copy fails.
* *
* @return object The managed copy of the entity.
*
* @todo Require active transaction!? OptimisticLockException may result in undefined state!? * @todo Require active transaction!? OptimisticLockException may result in undefined state!?
*/ */
public function merge($entity) public function merge($entity)
@ -1645,10 +1693,15 @@ class UnitOfWork implements PropertyChangedListener
* *
* @param object $entity * @param object $entity
* @param array $visited * @param array $visited
* @return object The managed copy of the entity. * @param object $prevManagedCopy
* @param array $assoc
*
* @throws OptimisticLockException If the entity uses optimistic locking through a version * @throws OptimisticLockException If the entity uses optimistic locking through a version
* attribute and the version check against the managed copy fails. * attribute and the version check against the managed copy fails.
* @throws InvalidArgumentException If the entity instance is NEW. * @throws ORMInvalidArgumentException If the entity instance is NEW.
* @throws EntityNotFoundException
*
* @return object The managed copy of the entity.
*/ */
private function doMerge($entity, array &$visited, $prevManagedCopy = null, $assoc = null) private function doMerge($entity, array &$visited, $prevManagedCopy = null, $assoc = null)
{ {
@ -1895,6 +1948,7 @@ class UnitOfWork implements PropertyChangedListener
* any local, unpersisted changes. * any local, unpersisted changes.
* *
* @param object $entity The entity to refresh. * @param object $entity The entity to refresh.
*
* @throws InvalidArgumentException If the entity is not MANAGED. * @throws InvalidArgumentException If the entity is not MANAGED.
*/ */
public function refresh($entity) public function refresh($entity)
@ -1909,7 +1963,8 @@ class UnitOfWork implements PropertyChangedListener
* *
* @param object $entity The entity to refresh. * @param object $entity The entity to refresh.
* @param array $visited The already visited entities during cascades. * @param array $visited The already visited entities during cascades.
* @throws InvalidArgumentException If the entity is not MANAGED. *
* @throws ORMInvalidArgumentException If the entity is not MANAGED.
*/ */
private function doRefresh($entity, array &$visited) private function doRefresh($entity, array &$visited)
{ {
@ -2060,7 +2115,8 @@ class UnitOfWork implements PropertyChangedListener
* *
* @param object $entity * @param object $entity
* @param array $visited * @param array $visited
* @param array $insertNow *
* @return void
*/ */
private function cascadePersist($entity, array &$visited) private function cascadePersist($entity, array &$visited)
{ {
@ -2144,6 +2200,12 @@ class UnitOfWork implements PropertyChangedListener
* @param object $entity * @param object $entity
* @param int $lockMode * @param int $lockMode
* @param int $lockVersion * @param int $lockVersion
*
* @throws ORMInvalidArgumentException
* @throws TransactionRequiredException
* @throws OptimisticLockException
*
* @return void
*/ */
public function lock($entity, $lockMode, $lockVersion = null) public function lock($entity, $lockMode, $lockVersion = null)
{ {
@ -2279,13 +2341,20 @@ class UnitOfWork implements PropertyChangedListener
$this->collectionDeletions[$coid] = $coll; $this->collectionDeletions[$coid] = $coll;
} }
/**
* @param PersistentCollection $coll
*
* @return bool
*/
public function isCollectionScheduledForDeletion(PersistentCollection $coll) public function isCollectionScheduledForDeletion(PersistentCollection $coll)
{ {
return isset($this->collectionsDeletions[spl_object_hash($coll)]); return isset($this->collectionDeletions[spl_object_hash($coll)]);
} }
/** /**
* @param ClassMetadata $class * @param ClassMetadata $class
*
* @return \Doctrine\Common\Persistence\ObjectManagerAware|object
*/ */
private function newInstance($class) private function newInstance($class)
{ {
@ -2306,6 +2375,7 @@ class UnitOfWork implements PropertyChangedListener
* @param string $className The name of the entity class. * @param string $className The name of the entity class.
* @param array $data The data for the entity. * @param array $data The data for the entity.
* @param array $hints Any hints to account for during reconstitution/lookup of the entity. * @param array $hints Any hints to account for during reconstitution/lookup of the entity.
*
* @return object The managed entity instance. * @return object The managed entity instance.
* @internal Highly performance-sensitive method. * @internal Highly performance-sensitive method.
* *
@ -2578,7 +2648,9 @@ class UnitOfWork implements PropertyChangedListener
/** /**
* Initializes (loads) an uninitialized persistent collection of an entity. * Initializes (loads) an uninitialized persistent collection of an entity.
* *
* @param PeristentCollection $collection The collection to initialize. * @param \Doctrine\ORM\PersistentCollection $collection The collection to initialize.
*
* @return void
* @todo Maybe later move to EntityManager#initialize($proxyOrCollection). See DDC-733. * @todo Maybe later move to EntityManager#initialize($proxyOrCollection). See DDC-733.
*/ */
public function loadCollection(PersistentCollection $collection) public function loadCollection(PersistentCollection $collection)
@ -2612,6 +2684,7 @@ class UnitOfWork implements PropertyChangedListener
* present at the time the entity was reconstituted from the database. * present at the time the entity was reconstituted from the database.
* *
* @param object $entity * @param object $entity
*
* @return array * @return array
*/ */
public function getOriginalEntityData($entity) public function getOriginalEntityData($entity)
@ -2654,6 +2727,7 @@ class UnitOfWork implements PropertyChangedListener
* order as the identifier field names as returned by ClassMetadata#getIdentifierFieldNames(). * order as the identifier field names as returned by ClassMetadata#getIdentifierFieldNames().
* *
* @param object $entity * @param object $entity
*
* @return array The identifier values. * @return array The identifier values.
*/ */
public function getEntityIdentifier($entity) public function getEntityIdentifier($entity)
@ -2667,6 +2741,7 @@ class UnitOfWork implements PropertyChangedListener
* *
* @param mixed $id The entity identifier to look for. * @param mixed $id The entity identifier to look for.
* @param string $rootClassName The name of the root class of the mapped entity hierarchy. * @param string $rootClassName The name of the root class of the mapped entity hierarchy.
*
* @return mixed Returns the entity with the specified identifier if it exists in * @return mixed Returns the entity with the specified identifier if it exists in
* this UnitOfWork, FALSE otherwise. * this UnitOfWork, FALSE otherwise.
*/ */
@ -2757,9 +2832,9 @@ class UnitOfWork implements PropertyChangedListener
/** /**
* Gets a collection persister for a collection-valued association. * Gets a collection persister for a collection-valued association.
* *
* @param AssociationMapping $association * @param array $association
* *
* @return AbstractCollectionPersister * @return \Doctrine\ORM\Persisters\AbstractCollectionPersister
*/ */
public function getCollectionPersister(array $association) public function getCollectionPersister(array $association)
{ {
@ -2901,6 +2976,7 @@ class UnitOfWork implements PropertyChangedListener
* Helper method to initialize a lazy loading proxy or persistent collection. * Helper method to initialize a lazy loading proxy or persistent collection.
* *
* @param object * @param object
*
* @return void * @return void
*/ */
public function initializeObject($obj) public function initializeObject($obj)
@ -2920,6 +2996,7 @@ class UnitOfWork implements PropertyChangedListener
* Helper method to show an object as string. * Helper method to show an object as string.
* *
* @param object $obj * @param object $obj
*
* @return string * @return string
*/ */
private static function objToStr($obj) private static function objToStr($obj)
@ -2931,10 +3008,13 @@ class UnitOfWork implements PropertyChangedListener
* Marks an entity as read-only so that it will not be considered for updates during UnitOfWork#commit(). * Marks an entity as read-only so that it will not be considered for updates during UnitOfWork#commit().
* *
* This operation cannot be undone as some parts of the UnitOfWork now keep gathering information * This operation cannot be undone as some parts of the UnitOfWork now keep gathering information
* on this object that might be necessary to perform a correct udpate. * on this object that might be necessary to perform a correct update.
*
*
* @param object $object
*
* @throws ORMInvalidArgumentException
* *
* @throws \InvalidArgumentException
* @param $object
* @return void * @return void
*/ */
public function markReadOnly($object) public function markReadOnly($object)
@ -2949,9 +3029,11 @@ class UnitOfWork implements PropertyChangedListener
/** /**
* Is this entity read only? * Is this entity read only?
* *
* @throws \InvalidArgumentException * @param object $object
* @param $object *
* @return void * @throws ORMInvalidArgumentException
*
* @return bool
*/ */
public function isReadOnly($object) public function isReadOnly($object)
{ {