PersistenceMapper.php
1 <?php
2 /**
3  * wCMF - wemove Content Management Framework
4  * Copyright (C) 2005-2020 wemove digital solutions GmbH
5  *
6  * Licensed under the terms of the MIT License.
7  *
8  * See the LICENSE file distributed with this work for
9  * additional information.
10  */
11 namespace wcmf\lib\persistence;
12 
13 use wcmf\lib\i18n\Message;
14 use wcmf\lib\persistence\BuildDepth;
15 use wcmf\lib\persistence\ObjectId;
16 use wcmf\lib\persistence\PagingInfo;
17 use wcmf\lib\persistence\PersistenceFacade;
18 use wcmf\lib\persistence\PersistenceOperation;
19 use wcmf\lib\persistence\PersistentObject;
20 
21  /**
22  * PersistenceMapper defines the interface for all mapper classes.
23  *
24  * @author ingo herwig <ingo@wemove.com>
25  */
26 interface PersistenceMapper {
27 
28  /**
29  * Get the entity type that this mapper handles.
30  * @return String
31  */
32  public function getType();
33 
34  /**
35  * Get the display name of the type.
36  * @param $message Message instance used for translation
37  */
38  public function getTypeDisplayName(Message $message);
39 
40  /**
41  * Get the description of the type.
42  * @param $message Message instance used for translation
43  */
44  public function getTypeDescription(Message $message);
45 
46  /**
47  * Get the names of the primary key values.
48  * @return Array with the value names.
49  */
50  public function getPkNames();
51 
52  /**
53  * Get the relations for this type
54  * @param $hierarchyType The hierarchy type that the other type has in relation to this type
55  * 'parent', 'child', 'undefined' or 'all' to get all relations (default: 'all')
56  * @return Array of RelationDescription instances
57  */
58  public function getRelations($hierarchyType='all');
59 
60  /**
61  * Check if a named relation is defined.
62  * @param $roleName The role name of the relation
63  * @return Boolean
64  */
65  public function hasRelation($roleName);
66 
67  /**
68  * Get the definition for a relation
69  * @param $roleName The role name of the relation
70  * @return RelationDescription or null if the relation does not exist
71  */
72  public function getRelation($roleName);
73 
74  /**
75  * Get the definitions for relations to a given type
76  * @param $type The type name
77  * @return Array of RelationDescription instances
78  */
79  public function getRelationsByType($type);
80 
81  /**
82  * PersistentObject values may be tagged with application specific tags.
83  * This method gets the attributes belonging to the given tags.
84  * @param $tags An array of tags that the attribute should match. Empty array means all attributes independent of the given matchMode (default: empty array)
85  * @param $matchMode One of 'all', 'none', 'any', defines how the attribute's tags should match the given tags (default: 'all')
86  * @return Array of AttributeDescription instances
87  */
88  public function getAttributes(array $tags=[], $matchMode='all');
89 
90  /**
91  * Check if a named attribute is defined.
92  * @param $name The attribute name
93  * @return Boolean
94  */
95  public function hasAttribute($name);
96 
97  /**
98  * Get the definition for an attribute.
99  * @param $name The attribute name
100  * @return AttributeDescription or null if the attribute does not exist
101  */
102  public function getAttribute($name);
103 
104  /**
105  * Get the display name of the type.
106  * @param $name The attribute name
107  * @param $message Message instance used for translation
108  */
109  public function getAttributeDisplayName($name, Message $message);
110 
111  /**
112  * Get the description of the attribute.
113  * @param $name The attribute name
114  * @param $message Message instance used for translation
115  */
116  public function getAttributeDescription($name, Message $message);
117 
118  /**
119  * Get the references to other entities
120  * @return Array of ReferenceDescription instances
121  */
122  public function getReferences();
123 
124  /**
125  * Get meta information on the mapped class.
126  * @return Associative array of key value pairs
127  */
128  public function getProperties();
129 
130  /**
131  * Check if this type may be explicitly sorted by the user using a persistent
132  * attribute which stores the order. The roleName parameter allows to ask
133  * for the order with respect to a specific role.
134  * @param $roleName The role name of the relation (optional, default: _null_)
135  * @return Boolean
136  */
137  public function isSortable($roleName=null);
138 
139  /**
140  * Get the persistent attribute that is used to store the order of the type
141  * as explicitly defined by the user. The roleName parameter allows to ask
142  * for the order with respect to a specific role.
143  * @param $roleName The role name of the relation (optional, default: _null_)
144  * @return Assciative array with the keys sortType, sortFieldName, sortDirection
145  * (ASC or DESC) and isSortkey (Boolean) or null, if the type is not sortable
146  */
147  public function getSortkey($roleName=null);
148 
149  /**
150  * Get the names of the type and attributes to order by default and the sort directions
151  * (ASC or DESC). If the order may be established explicitly by the user, the
152  * isSortkey value is true. The roleName parameter allows to ask
153  * for the order with respect to a specific role.
154  * In a many to many relation the attributes may not be contained in the mapped type,
155  * so sortType may be different from the mapper type.
156  * @param $roleName The role name of the relation (optional, default: _null_)
157  * @return An array of assciative arrays with the keys sortType, sortFieldName, sortDirection
158  * (ASC or DESC) and isSortkey (Boolean)
159  */
160  public function getDefaultOrder($roleName=null);
161 
162  /**
163  * Load a PersistentObject instance from the storage.
164  * @note PersistentMapper implementations must call the PersistentObject::afterLoad()
165  * lifecycle callcack on each loaded object and attach it to the current transaction using
166  * the Transaction::attach() method.
167  * @param $oid The object id of the object to construct
168  * @param $buildDepth One of the BUILDDEPTH constants or a number describing the number of generations to build
169  * (except BuildDepth::REQUIRED, BuildDepth::PROXIES_ONLY) (default: _BuildDepth::SINGLE_)
170  * @return PersistentObject, null if oid does not exist or a given condition prevents loading.
171  */
172  public function load(ObjectId $oid, $buildDepth=BuildDepth::SINGLE);
173 
174  /**
175  * Construct a PersistentObject instance of a given type.
176  * @note PersistentMapper implementations must call the PersistentObject::afterCreate()
177  * lifecycle callcack on each created object.
178  * @param $type The type of object to build
179  * @param $buildDepth One of the BUILDDEPTH constants or a number describing the number of generations to build
180  * (except BuildDepth::INFINITE, BuildDepth::PROXIES_ONLY) (default: _BuildDepth::SINGLE_)
181  * @return PersistentObject
182  */
183  public function create($type, $buildDepth=BuildDepth::SINGLE);
184 
185  /**
186  * Save a PersistentObject instance.
187  * @note PersistentMapper implementations must call the PersistentObject::beforeUpdate()/
188  * PersistentObject::afterUpdate() or PersistentObject::beforeInsert()/
189  * PersistentObject::afterInsert() lifecycle callcacks on each object depending
190  * on it's state.
191  * @param $object PersistentObject
192  */
193  public function save(PersistentObject $object);
194 
195  /**
196  * Delete a PersistentObject instance.
197  * @note PersistentMapper implementations must call the PersistentObject::beforeDelete()/
198  * PersistentObject::afterDelete() lifecycle callcacks on each object.
199  * @param $object PersistentObject
200  */
201  public function delete(PersistentObject $object);
202 
203  /**
204  * @see PersistenceFacade::getOIDs()
205  */
206  public function getOIDs($type, $criteria=null, $orderby=null, PagingInfo $pagingInfo=null);
207 
208  /**
209  * @see PersistenceFacade::loadObjects()
210  */
211  public function loadObjects($type, $buildDepth=BuildDepth::SINGLE, $criteria=null, $orderby=null,
212  PagingInfo $pagingInfo=null);
213 
214  /**
215  * Load the objects for the specified role. The implementation must check the navigability of
216  * the relation and return null, if the requested direction is not navigable. The result
217  * depends on the multiplicity of the relation (singlevalued or multivalued).
218  * @param $objects Array of PersistentObject or PersstentObjectProxy instances for which the related objects are loaded
219  * @param $role The role of the objects in relation to the given objects
220  * @param $buildDepth One of the BUILDDEPTH constants or a number describing the number of generations to build
221  * (except BuildDepth::REQUIRED, BuildDepth::PROXIES_ONLY) (default: BuildDepth::SINGLE)
222  * @param $criteria An array of Criteria instances that define conditions on the object's attributes (optional, default: _null_)
223  * @param $orderby An array holding names of attributes to order by, maybe appended with 'ASC', 'DESC' (optional, default: _null_)
224  * @param $pagingInfo A reference PagingInfo instance (optional, default: _null_)
225  * @return Associative array with the object ids of the origin objects as keys and arrays of related
226  * PersistentObject instances as values or null, if not navigable
227  */
228  public function loadRelation(array $objects, $role, $buildDepth=BuildDepth::SINGLE, $criteria=null, $orderby=null,
229  PagingInfo $pagingInfo=null);
230 
231  /**
232  * Execute a PersistenceOperation. PersistenceOperation.type must be the type that
233  * is mapped by this mapper.
234  * @param $operation The operation
235  * @return int The number of affected rows.
236  */
237  public function executeOperation(PersistenceOperation $operation);
238 
239  /**
240  * Start a transaction on the transactional resource (e.g. database) of
241  * this mapper. Nested transactions are not supported, so the implementation should
242  * ignore consecutive calls, if a transaction is already started.
243  */
244  public function beginTransaction();
245 
246  /**
247  * Commit the transaction on the transactional resource (e.g. database) of
248  * this mapper. The implementation should ignore calls, if no transaction
249  * is started yet.
250  */
251  public function commitTransaction();
252 
253  /**
254  * Rollback the transaction on the transactional resource (e.g. database) of
255  * this mapper. The implementation should ignore calls, if no transaction
256  * is started yet.
257  */
258  public function rollbackTransaction();
259 
260  /**
261  * Get a list of all insert/update/delete statements that where executed in the last transaction.
262  * @note Different mapper implementations may return different representations
263  * @return Array of statements
264  */
265  public function getStatements();
266 }
267 ?>