[TASK] Streamline return tags in phpdocs
[Packages/TYPO3.CMS.git] / typo3 / sysext / extbase / Classes / Persistence / Generic / PersistenceManager.php
1 <?php
2 namespace TYPO3\CMS\Extbase\Persistence\Generic;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
18 use TYPO3\CMS\Extbase\Persistence\QueryInterface;
19
20 /**
21 * The Extbase Persistence Manager
22 *
23 * @api
24 */
25 class PersistenceManager implements \TYPO3\CMS\Extbase\Persistence\PersistenceManagerInterface, \TYPO3\CMS\Core\SingletonInterface
26 {
27 /**
28 * @var array
29 */
30 protected $newObjects = [];
31
32 /**
33 * @var ObjectStorage
34 */
35 protected $changedObjects;
36
37 /**
38 * @var ObjectStorage
39 */
40 protected $addedObjects;
41
42 /**
43 * @var ObjectStorage
44 */
45 protected $removedObjects;
46
47 /**
48 * @var \TYPO3\CMS\Extbase\Persistence\Generic\QueryFactoryInterface
49 */
50 protected $queryFactory;
51
52 /**
53 * @var \TYPO3\CMS\Extbase\Persistence\Generic\BackendInterface
54 */
55 protected $backend;
56
57 /**
58 * @var \TYPO3\CMS\Extbase\Persistence\Generic\Session
59 */
60 protected $persistenceSession;
61
62 /**
63 * @param \TYPO3\CMS\Extbase\Persistence\Generic\QueryFactoryInterface $queryFactory
64 */
65 public function injectQueryFactory(\TYPO3\CMS\Extbase\Persistence\Generic\QueryFactoryInterface $queryFactory)
66 {
67 $this->queryFactory = $queryFactory;
68 }
69
70 /**
71 * @param \TYPO3\CMS\Extbase\Persistence\Generic\BackendInterface $backend
72 */
73 public function injectBackend(\TYPO3\CMS\Extbase\Persistence\Generic\BackendInterface $backend)
74 {
75 $this->backend = $backend;
76 }
77
78 /**
79 * @param \TYPO3\CMS\Extbase\Persistence\Generic\Session $persistenceSession
80 */
81 public function injectPersistenceSession(\TYPO3\CMS\Extbase\Persistence\Generic\Session $persistenceSession)
82 {
83 $this->persistenceSession = $persistenceSession;
84 }
85
86 /**
87 * Create new instance
88 */
89 public function __construct()
90 {
91 $this->addedObjects = new ObjectStorage();
92 $this->removedObjects = new ObjectStorage();
93 $this->changedObjects = new ObjectStorage();
94 }
95
96 /**
97 * Registers a repository
98 *
99 * @param string $className The class name of the repository to be registered
100 */
101 public function registerRepositoryClassName($className)
102 {
103 }
104
105 /**
106 * Returns the number of records matching the query.
107 *
108 * @param QueryInterface $query
109 * @return int
110 * @api
111 */
112 public function getObjectCountByQuery(QueryInterface $query)
113 {
114 return $this->backend->getObjectCountByQuery($query);
115 }
116
117 /**
118 * Returns the object data matching the $query.
119 *
120 * @param QueryInterface $query
121 * @return array
122 * @api
123 */
124 public function getObjectDataByQuery(QueryInterface $query)
125 {
126 return $this->backend->getObjectDataByQuery($query);
127 }
128
129 /**
130 * Returns the (internal) identifier for the object, if it is known to the
131 * backend. Otherwise NULL is returned.
132 *
133 * Note: this returns an identifier even if the object has not been
134 * persisted in case of AOP-managed entities. Use isNewObject() if you need
135 * to distinguish those cases.
136 *
137 * @param object $object
138 * @return mixed The identifier for the object if it is known, or NULL
139 * @api
140 */
141 public function getIdentifierByObject($object)
142 {
143 return $this->backend->getIdentifierByObject($object);
144 }
145
146 /**
147 * Returns the object with the (internal) identifier, if it is known to the
148 * backend. Otherwise NULL is returned.
149 *
150 * @param mixed $identifier
151 * @param string $objectType
152 * @param bool $useLazyLoading Set to TRUE if you want to use lazy loading for this object
153 * @return object The object for the identifier if it is known, or NULL
154 * @api
155 */
156 public function getObjectByIdentifier($identifier, $objectType = null, $useLazyLoading = false)
157 {
158 if (isset($this->newObjects[$identifier])) {
159 return $this->newObjects[$identifier];
160 }
161 if ($this->persistenceSession->hasIdentifier($identifier, $objectType)) {
162 return $this->persistenceSession->getObjectByIdentifier($identifier, $objectType);
163 } else {
164 return $this->backend->getObjectByIdentifier($identifier, $objectType);
165 }
166 }
167
168 /**
169 * Commits new objects and changes to objects in the current persistence
170 * session into the backend
171 *
172 * @api
173 */
174 public function persistAll()
175 {
176 // hand in only aggregate roots, leaving handling of subobjects to
177 // the underlying storage layer
178 // reconstituted entities must be fetched from the session and checked
179 // for changes by the underlying backend as well!
180 $this->backend->setAggregateRootObjects($this->addedObjects);
181 $this->backend->setChangedEntities($this->changedObjects);
182 $this->backend->setDeletedEntities($this->removedObjects);
183 $this->backend->commit();
184
185 $this->addedObjects = new ObjectStorage();
186 $this->removedObjects = new ObjectStorage();
187 $this->changedObjects = new ObjectStorage();
188 }
189
190 /**
191 * Return a query object for the given type.
192 *
193 * @param string $type
194 * @return QueryInterface
195 */
196 public function createQueryForType($type)
197 {
198 return $this->queryFactory->create($type);
199 }
200
201 /**
202 * Adds an object to the persistence.
203 *
204 * @param object $object The object to add
205 * @api
206 */
207 public function add($object)
208 {
209 $this->addedObjects->attach($object);
210 $this->removedObjects->detach($object);
211 }
212
213 /**
214 * Removes an object to the persistence.
215 *
216 * @param object $object The object to remove
217 * @api
218 */
219 public function remove($object)
220 {
221 if ($this->addedObjects->contains($object)) {
222 $this->addedObjects->detach($object);
223 } else {
224 $this->removedObjects->attach($object);
225 }
226 }
227
228 /**
229 * Update an object in the persistence.
230 *
231 * @param object $object The modified object
232 * @throws \TYPO3\CMS\Extbase\Persistence\Exception\UnknownObjectException
233 * @api
234 */
235 public function update($object)
236 {
237 if ($this->isNewObject($object)) {
238 throw new \TYPO3\CMS\Extbase\Persistence\Exception\UnknownObjectException('The object of type "' . get_class($object) . '" given to update must be persisted already, but is new.', 1249479819);
239 }
240 $this->changedObjects->attach($object);
241 }
242
243 /**
244 * Injects the Extbase settings, called by Extbase.
245 *
246 * @param array $settings
247 * @throws \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException
248 * @api
249 */
250 public function injectSettings(array $settings)
251 {
252 throw new \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException(__METHOD__, 1476108078);
253 }
254
255 /**
256 * Initializes the persistence manager, called by Extbase.
257 */
258 public function initializeObject()
259 {
260 $this->backend->setPersistenceManager($this);
261 }
262
263 /**
264 * Clears the in-memory state of the persistence.
265 *
266 * Managed instances become detached, any fetches will
267 * return data directly from the persistence "backend".
268 *
269 * @throws \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException
270 */
271 public function clearState()
272 {
273 $this->newObjects = [];
274 $this->addedObjects = new ObjectStorage();
275 $this->removedObjects = new ObjectStorage();
276 $this->changedObjects = new ObjectStorage();
277 $this->persistenceSession->destroy();
278 }
279
280 /**
281 * Checks if the given object has ever been persisted.
282 *
283 * @param object $object The object to check
284 * @return bool TRUE if the object is new, FALSE if the object exists in the persistence session
285 * @api
286 */
287 public function isNewObject($object)
288 {
289 return $this->persistenceSession->hasObject($object) === false;
290 }
291
292 /**
293 * Registers an object which has been created or cloned during this request.
294 *
295 * A "new" object does not necessarily
296 * have to be known by any repository or be persisted in the end.
297 *
298 * Objects registered with this method must be known to the getObjectByIdentifier()
299 * method.
300 *
301 * @param object $object The new object to register
302 */
303 public function registerNewObject($object)
304 {
305 $identifier = $this->getIdentifierByObject($object);
306 $this->newObjects[$identifier] = $object;
307 }
308
309 /**
310 * Converts the given object into an array containing the identity of the domain object.
311 *
312 * @throws \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException
313 * @param object $object The object to be converted
314 * @return array
315 * @api
316 */
317 public function convertObjectToIdentityArray($object)
318 {
319 throw new \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException(__METHOD__, 1476108103);
320 }
321
322 /**
323 * Recursively iterates through the given array and turns objects
324 * into arrays containing the identity of the domain object.
325 *
326 * @throws \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException
327 * @param array $array The array to be iterated over
328 * @return array
329 * @api
330 * @see convertObjectToIdentityArray()
331 */
332 public function convertObjectsToIdentityArrays(array $array)
333 {
334 throw new \TYPO3\CMS\Extbase\Persistence\Generic\Exception\NotImplementedException(__METHOD__, 1476108111);
335 }
336
337 /**
338 * Tear down the persistence
339 *
340 * This method is called in functional tests to reset the storage between tests.
341 * The implementation is optional and depends on the underlying persistence backend.
342 */
343 public function tearDown()
344 {
345 if (method_exists($this->backend, 'tearDown')) {
346 $this->backend->tearDown();
347 }
348 }
349 }