PersistentObject.php
1 <?php
2 /**
3  * wCMF - wemove Content Management Framework
4  * Copyright (C) 2005-2018 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.
152  * @return The value of the attribute / null if it doesn't exist.
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.
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 of an attribute provided to the initialize method.
212  * @param $name The name of the attribute.
213  * @return The value of the attribute / null if it doesn't exist.
214  */
215  public function getOriginalValue($name);
216 
217  /**
218  * Get the list of objects that must exist in the store, before
219  * this object may be persisted. Implementing classes may use this method to
220  * manage dependencies.
221  * @return Array of PersistentObject instances
222  */
223  public function getIndispensableObjects();
224 
225  /**
226  * Get the value of a named property in the object.
227  * @param $name The name of the property.
228  * @return The value of the property / null if it doesn't exist.
229  */
230  public function getProperty($name);
231 
232  /**
233  * Set the value of a named property in the object.
234  * @param $name The name of the property to set.
235  * @param $value The value of the property to set.
236  */
237  public function setProperty($name, $value);
238 
239  /**
240  * Get the names of all properties in the object. Properties are
241  * either defined by using the PersistentObject::setProperty() method
242  * or by the PersistentMapper.
243  * @return An array consisting of the names.
244  */
245  public function getPropertyNames();
246 
247  /**
248  * Get the value of one property of an attribute.
249  * @param $name The name of the attribute to get its properties.
250  * @param $property The name of the property to get.
251  * @return The value property/null if not found.
252  */
253  public function getValueProperty($name, $property);
254 
255  /**
256  * Set the value of one property of an attribute.
257  * @param $name The name of the attribute to set its properties.
258  * @param $property The name of the property to set.
259  * @param $value The value to set on the property.
260  */
261  public function setValueProperty($name, $property, $value);
262 
263  /**
264  * Get the names of all properties of a value in the object.
265  * @return An array consisting of the names.
266  */
267  public function getValuePropertyNames($name);
268 
269  /**
270  * <!--
271  * Output
272  * -->
273  */
274 
275  /**
276  * Get the value of the object used for display.
277  * @return The value.
278  */
279  public function getDisplayValue();
280 
281  /**
282  * Get a string representation of the values of the PersistentObject.
283  * @return String
284  */
285  public function dump();
286 }
287 ?>
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.
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.
getOriginalValue($name)
Get the original of an attribute provided to the initialize method.
__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.