PersistentObject.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\persistence\ObjectId;
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  * Reset all values to their original values
98  */
99  public function reset();
100 
101  /**
102  * <!--
103  * Persistence hook methods.
104  * -->
105  */
106 
107  /**
108  * This method is called once after creation of this object. At this time it
109  * is not known in the store.
110  */
111  public function afterCreate();
112 
113  /**
114  * This method is called once before inserting the newly created object into the store.
115  */
116  public function beforeInsert();
117 
118  /**
119  * This method is called once after inserting the newly created object into the store.
120  */
121  public function afterInsert();
122 
123  /**
124  * This method is called always after loading the object from the store.
125  */
126  public function afterLoad();
127 
128  /**
129  * This method is called always before updating the modified object in the store.
130  */
131  public function beforeUpdate();
132 
133  /**
134  * This method is called always after updating the modified object in the store.
135  */
136  public function afterUpdate();
137 
138  /**
139  * This method is called once before deleting the object from the store.
140  */
141  public function beforeDelete();
142 
143  /**
144  * This method is called once after deleting the object from the store.
145  */
146  public function afterDelete();
147 
148  /**
149  * <!--
150  * Values and Properties
151  * -->
152  */
153 
154  /**
155  * Get the value of an attribute.
156  * @param $name The name of the attribute.
157  * @return The value of the attribute / null if it doesn't exist.
158  */
159  public function getValue($name);
160 
161  /**
162  * Set the value of an attribute if it exists.
163  * @param $name The name of the attribute to set.
164  * @param $value The value of the attribute.
165  * @param $forceSet Boolean whether to set the value even if it is already set
166  * and to bypass validation (used to notify listeners) (default: _false_)
167  * @param $trackChange Boolean whether to track the change (change state, notify listeners) or not (default: _true_)
168  * Only set this false, if you know, what you are doing
169  * @return Boolean whether the operation succeeds or not
170  */
171  public function setValue($name, $value, $forceSet=false, $trackChange=true);
172 
173  /**
174  * Check if the object has a given attribute.
175  * @param $name The name of the attribute.
176  * @return Boolean whether the attribute exists or not.
177  */
178  public function hasValue($name);
179 
180  /**
181  * Remove an attribute.
182  * @param $name The name of the attribute to remove.
183  */
184  public function removeValue($name);
185 
186  /**
187  * Get the names of all attributes.
188  * @param $excludeTransient Boolean whether to exclude transient values (default: _false_)
189  * @return An array of attribute names.
190  */
191  public function getValueNames($excludeTransient=false);
192 
193  /**
194  * Validate all values by calling PersistentObject::validateValue()
195  * Throws a ValidationException in case of invalid data.
196  */
197  public function validateValues();
198 
199  /**
200  * Check if data may be set. The method is also called, when setting a value.
201  * Controller may call this method before setting data and saving the object.
202  * Throws a ValidationException in case of invalid data.
203  * @param $name The name of the attribute to set.
204  * @param $value The value of the attribute.
205  * The default implementation calls PersistentObject::validateValueAgainstValidateType().
206  */
207  public function validateValue($name, $value);
208 
209  /**
210  * Get the list of changed attributes since creation, loading.
211  * @return Array of value names
212  */
213  public function getChangedValues();
214 
215  /**
216  * Get the original of an attribute provided to the initialize method.
217  * @param $name The name of the attribute.
218  * @return The value of the attribute / null if it doesn't exist.
219  */
220  public function getOriginalValue($name);
221 
222  /**
223  * Get the list of objects that must exist in the store, before
224  * this object may be persisted. Implementing classes may use this method to
225  * manage dependencies.
226  * @return Array of PersistentObject instances
227  */
228  public function getIndispensableObjects();
229 
230  /**
231  * Get the value of a named property in the object.
232  * @param $name The name of the property.
233  * @return The value of the property / null if it doesn't exist.
234  */
235  public function getProperty($name);
236 
237  /**
238  * Set the value of a named property in the object.
239  * @param $name The name of the property to set.
240  * @param $value The value of the property to set.
241  */
242  public function setProperty($name, $value);
243 
244  /**
245  * Get the names of all properties in the object. Properties are
246  * either defined by using the PersistentObject::setProperty() method
247  * or by the PersistentMapper.
248  * @return An array consisting of the names.
249  */
250  public function getPropertyNames();
251 
252  /**
253  * Get the value of one property of an attribute.
254  * @param $name The name of the attribute to get its properties.
255  * @param $property The name of the property to get.
256  * @return The value property/null if not found.
257  */
258  public function getValueProperty($name, $property);
259 
260  /**
261  * Set the value of one property of an attribute.
262  * @param $name The name of the attribute to set its properties.
263  * @param $property The name of the property to set.
264  * @param $value The value to set on the property.
265  */
266  public function setValueProperty($name, $property, $value);
267 
268  /**
269  * Get the names of all properties of a value in the object.
270  * @return An array consisting of the names.
271  */
272  public function getValuePropertyNames($name);
273 
274  /**
275  * <!--
276  * Output
277  * -->
278  */
279 
280  /**
281  * Get the value of the object used for display.
282  * @return The value.
283  */
284  public function getDisplayValue();
285 
286  /**
287  * Get a string representation of the values of the PersistentObject.
288  * @return String
289  */
290  public function dump();
291 }
292 ?>