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