PersistentObject.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 
14 
15 /**
16  * PersistentObject defines the interface of all persistent objects.
17  * It mainly requires an unique identifier for each instance (ObjectId),
18  * tracking of the persistent state, methods for setting and getting values
19  * as well as callback methods for lifecycle events.
20  *
21  * @author ingo herwig <ingo@wemove.com>
22  */
23 interface PersistentObject {
24 
25  const STATE_CLEAN = 0;
26  const STATE_DIRTY = 1;
27  const STATE_NEW = 2;
28  const STATE_DELETED = 3;
29 
30  /**
31  * Get the type of the object.
32  * @return The objects type.
33  */
34  public function getType();
35 
36  /**
37  * Get the PersistenceMapper of the object.
38  * @return PersistenceMapper
39  */
40  public function getMapper();
41 
42  /**
43  * Get the object id of the PersistentObject.
44  * @return ObjectId
45  */
46  public function getOID();
47 
48  /**
49  * Set the object id of the PersistentObject.
50  * @param $oid The PersistentObject's oid.
51  */
52  public function setOID(ObjectId $oid);
53 
54  /**
55  * Get the object's state:
56  * @return One of the STATE constant values:
57  */
58  public function getState();
59 
60  /**
61  * Set the state of the object to one of the STATE constants.
62  */
63  public function setState($state);
64 
65  /**
66  * Delete the object
67  */
68  public function delete();
69 
70  /**
71  * Get a copy of the object (ChangeListeners and Lock are not copied)
72  * @return PersistentObject
73  */
74  public function __clone();
75 
76  /**
77  * Copy all non-empty values to a given instance (ChangeListeners are triggered)
78  * @param $object PersistentObject instance to copy the values to.
79  * @param $copyPkValues Boolean whether primary key values should be copied
80  */
81  public function copyValues(PersistentObject $object, $copyPkValues=true);
82 
83  /**
84  * Copy all values, that don't exist yet from a given instance
85  * (ChangeListeners are not triggered)
86  * @param $object PersistentObject instance to copy the values from.
87  */
88  public function mergeValues(PersistentObject $object);
89 
90  /**
91  * Clear all values. Set each value to null except
92  * for the primary key values
93  */
94  public function clearValues();
95 
96  /**
97  * <!--
98  * Persistence hook methods.
99  * -->
100  */
101 
102  /**
103  * This method is called once after creation of this object. At this time it
104  * is not known in the store.
105  */
106  public function afterCreate();
107 
108  /**
109  * This method is called once before inserting the newly created object into the store.
110  */
111  public function beforeInsert();
112 
113  /**
114  * This method is called once after inserting the newly created object into the store.
115  */
116  public function afterInsert();
117 
118  /**
119  * This method is called always after loading the object from the store.
120  */
121  public function afterLoad();
122 
123  /**
124  * This method is called always before updating the modified object in the store.
125  */
126  public function beforeUpdate();
127 
128  /**
129  * This method is called always after updating the modified object in the store.
130  */
131  public function afterUpdate();
132 
133  /**
134  * This method is called once before deleting the object from the store.
135  */
136  public function beforeDelete();
137 
138  /**
139  * This method is called once after deleting the object from the store.
140  */
141  public function afterDelete();
142 
143  /**
144  * <!--
145  * Values and Properties
146  * -->
147  */
148 
149  /**
150  * Get the value of an attribute.
151  * @param $name The name of the attribute to query.
152  * @return The value of the attribute / null if it doesn't exits.
153  */
154  public function getValue($name);
155 
156  /**
157  * Set the value of an attribute if it exists.
158  * @param $name The name of the attribute to set.
159  * @param $value The value of the attribute.
160  * @param $forceSet Boolean whether to set the value even if it is already set
161  * and to bypass validation (used to notify listeners) (default: _false_)
162  * @param $trackChange Boolean whether to track the change (change state, notify listeners) or not (default: _true_)
163  * Only set this false, if you know, what you are doing
164  * @return Boolean whether the operation succeeds or not
165  */
166  public function setValue($name, $value, $forceSet=false, $trackChange=true);
167 
168  /**
169  * Check if the object has a given attribute.
170  * @param $name The name of the attribute to query.
171  * @return Boolean whether the attribute exists or not.
172  */
173  public function hasValue($name);
174 
175  /**
176  * Remove an attribute.
177  * @param $name The name of the attribute to remove.
178  */
179  public function removeValue($name);
180 
181  /**
182  * Get the names of all attributes.
183  * @param $excludeTransient Boolean whether to exclude transient values (default: _false_)
184  * @return An array of attribute names.
185  */
186  public function getValueNames($excludeTransient=false);
187 
188  /**
189  * Validate all values by calling PersistentObject::validateValue()
190  * Throws a ValidationException in case of invalid data.
191  */
192  public function validateValues();
193 
194  /**
195  * Check if data may be set. The method is also called, when setting a value.
196  * Controller may call this method before setting data and saving the object.
197  * Throws a ValidationException in case of invalid data.
198  * @param $name The name of the attribute to set.
199  * @param $value The value of the attribute.
200  * The default implementation calls PersistentObject::validateValueAgainstValidateType().
201  */
202  public function validateValue($name, $value);
203 
204  /**
205  * Get the list of changed attributes since creation, loading.
206  * @return Array of value names
207  */
208  public function getChangedValues();
209 
210  /**
211  * Get the original data provided to the initialize method.
212  * @return Associative array with value names as keys and values as values
213  */
214  public function getOriginalValues();
215 
216  /**
217  * Get the list of objects that must exist in the store, before
218  * this object may be persisted. Implementing classes may use this method to
219  * manage dependencies.
220  * @return Array of PersistentObject instances
221  */
222  public function getIndispensableObjects();
223 
224  /**
225  * Get the value of a named property in the object.
226  * @param $name The name of the property to query.
227  * @return The value of the property / null if it doesn't exits.
228  */
229  public function getProperty($name);
230 
231  /**
232  * Set the value of a named property in the object.
233  * @param $name The name of the property to set.
234  * @param $value The value of the property to set.
235  */
236  public function setProperty($name, $value);
237 
238  /**
239  * Get the names of all properties in the object. Properties are
240  * either defined by using the PersistentObject::setProperty() method
241  * or by the PersistentMapper.
242  * @return An array consisting of the names.
243  */
244  public function getPropertyNames();
245 
246  /**
247  * Get the value of one property of an attribute.
248  * @param $name The name of the attribute to get its properties.
249  * @param $property The name of the property to get.
250  * @return The value property/null if not found.
251  */
252  public function getValueProperty($name, $property);
253 
254  /**
255  * Set the value of one property of an attribute.
256  * @param $name The name of the attribute to set its properties.
257  * @param $property The name of the property to set.
258  * @param $value The value to set on the property.
259  */
260  public function setValueProperty($name, $property, $value);
261 
262  /**
263  * Get the names of all properties of a value in the object.
264  * @return An array consisting of the names.
265  */
266  public function getValuePropertyNames($name);
267 
268  /**
269  * <!--
270  * Output
271  * -->
272  */
273 
274  /**
275  * Get the value of the object used for display.
276  * @return The value.
277  */
278  public function getDisplayValue();
279 
280  /**
281  * Get a string representation of the values of the PersistentObject.
282  * @return String
283  */
284  public function dump();
285 }
286 ?>
setProperty($name, $value)
Set the value of a named property in the object.
getType()
Get the type of the object.
setState($state)
Set the state of the object to one of the STATE constants.
getOID()
Get the object id of the PersistentObject.
getDisplayValue()
Get the value of the object used for display.
beforeUpdate()
This method is called always before updating the modified object in the store.
getOriginalValues()
Get the original data provided to the initialize method.
afterDelete()
This method is called once after deleting the object from the store.
getMapper()
Get the PersistenceMapper of the object.
getValueNames($excludeTransient=false)
Get the names of all attributes.
getProperty($name)
Get the value of a named property in the object.
afterUpdate()
This method is called always after updating the modified object in the store.
Persistence layer related interfaces and classes.
Definition: namespaces.php:42
ObjectId is the unique identifier of an object.
Definition: ObjectId.php:27
validateValues()
Validate all values by calling PersistentObject::validateValue() Throws a ValidationException in case...
getPropertyNames()
Get the names of all properties in the object.
__clone()
Get a copy of the object (ChangeListeners and Lock are not copied)
afterCreate()
This method is called once after creation of this object.
getValuePropertyNames($name)
Get the names of all properties of a value in the object.
getValue($name)
Get the value of an attribute.
setOID(ObjectId $oid)
Set the object id of the PersistentObject.
hasValue($name)
Check if the object has a given attribute.
validateValue($name, $value)
Check if data may be set.
dump()
Get a string representation of the values of the PersistentObject.
removeValue($name)
Remove an attribute.
setValue($name, $value, $forceSet=false, $trackChange=true)
Set the value of an attribute if it exists.
copyValues(PersistentObject $object, $copyPkValues=true)
Copy all non-empty values to a given instance (ChangeListeners are triggered)
getIndispensableObjects()
Get the list of objects that must exist in the store, before this object may be persisted.
afterInsert()
This method is called once after inserting the newly created object into the store.
afterLoad()
This method is called always after loading the object from the store.
beforeDelete()
This method is called once before deleting the object from the store.
getValueProperty($name, $property)
Get the value of one property of an attribute.
mergeValues(PersistentObject $object)
Copy all values, that don't exist yet from a given instance (ChangeListeners are not triggered) ...
beforeInsert()
This method is called once before inserting the newly created object into the store.
getState()
Get the object's state:
getChangedValues()
Get the list of changed attributes since creation, loading.
setValueProperty($name, $property, $value)
Set the value of one property of an attribute.
PersistentObject defines the interface of all persistent objects.