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 
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 ?>
loadObjects($type, $buildDepth=BuildDepth::SINGLE, $criteria=null, $orderby=null, PagingInfo $pagingInfo=null)
getRelations($hierarchyType='all')
Get the relations for this type.
A PersistenceOperation instance holds data necessary to accomplish an operation on the persistent sto...
getRelation($roleName)
Get the definition for a relation.
rollbackTransaction()
Rollback the transaction on the transactional resource (e.g.
hasRelation($roleName)
Check if a named relation is defined.
getType()
Get the entity type that this mapper handles.
getTypeDisplayName(Message $message)
Get the display name of the type.
Persistence layer related interfaces and classes.
Definition: namespaces.php:42
hasAttribute($name)
Check if a named attribute is defined.
getOIDs($type, $criteria=null, $orderby=null, PagingInfo $pagingInfo=null)
getPkNames()
Get the names of the primary key values.
getDefaultOrder($roleName=null)
Get the names of the type and attributes to order by default and the sort directions (ASC or DESC).
PersistenceMapper defines the interface for all mapper classes.
getRelationsByType($type)
Get the definitions for relations to a given type.
getProperties()
Get meta information on the mapped class.
executeOperation(PersistenceOperation $operation)
Execute a PersistenceOperation.
getTypeDescription(Message $message)
Get the description of the type.
ObjectId is the unique identifier of an object.
Definition: ObjectId.php:28
commitTransaction()
Commit the transaction on the transactional resource (e.g.
BuildDepth values are used to define the depth when loading object trees.
Definition: BuildDepth.php:19
beginTransaction()
Start a transaction on the transactional resource (e.g.
PersistenceFacade defines the interface for PersistenceFacade implementations.
getReferences()
Get the references to other entities.
getAttributes(array $tags=[], $matchMode='all')
PersistentObject values may be tagged with application specific tags.
getAttributeDescription($name, Message $message)
Get the description of the attribute.
getAttribute($name)
Get the definition for an attribute.
PagingInfo contains information about a paged list.
Definition: PagingInfo.php:18
PersistentObject defines the interface of all persistent objects.
getStatements()
Get a list of all insert/update/delete statements that where executed in the last transaction.
save(PersistentObject $object)
Save a PersistentObject instance.
loadRelation(array $objects, $role, $buildDepth=BuildDepth::SINGLE, $criteria=null, $orderby=null, PagingInfo $pagingInfo=null)
Load the objects for the specified role.
load(ObjectId $oid, $buildDepth=BuildDepth::SINGLE)
Load a PersistentObject instance from the storage.
create($type, $buildDepth=BuildDepth::SINGLE)
Construct a PersistentObject instance of a given type.
getAttributeDisplayName($name, Message $message)
Get the display name of the type.
getSortkey($roleName=null)
Get the persistent attribute that is used to store the order of the type as explicitly defined by the...
Message is used to get localized messages to be used in the user interface.
Definition: Message.php:23
isSortable($roleName=null)
Check if this type may be explicitly sorted by the user using a persistent attribute which stores the...