1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 package org.caleigo.core;
20
21 import org.caleigo.core.event.*;
22
23 /*** IEntity defines a basic interface for data objects representing a single
24 * instance of a data row/record from a persistent data storage. An entity
25 * contains several fields of data accessible using the setData() and getData()
26 * methods. Note that the contained fields are not defined as ordered by this
27 * interface and are instead adressed using their IFieldDescriptor.
28 *
29 * @author Dennis Zikovic
30 * @version 1.00
31 *
32 *//*
33 *
34 * WHEN WHO WHY & WHAT
35 * -----------------------------------------------------------------------------
36 * 2001-07-04 Dennis Zikovic Creation
37 */
38 public interface IEntity extends IDataProvider, IDataConsumer, Comparable, java.io.Serializable, org.caleigo.toolkit.tunnel.IDistributable
39 {
40
41
42 /*** Status flag that sinifies that an entity has unsaved changes since
43 * creation or last syncronization with the persistent storage.
44 */
45 public static final int DIRTY = 0x1;
46
47 /*** Status flag that used for newly creted object that that has had no
48 * changes from the default data set at the moment of creation.
49 */
50 public static final int EMPTY = 0x2;
51
52 /*** Status flag that is used to signify that the entity reflects data that
53 * exists in in a related persistent storage. This means that newly created
54 * and deleted entities will have this flag set to false.
55 */
56 public static final int PERSISTENT = 0x4;
57
58
59
60 /*** This method will store any unsaved changes in the entity to it's
61 * realated persistent storage. This will reset the DIRTY flag and set
62 * the PERSISTENT flag.
63 */
64 public void store();
65
66 /*** This method will delete the entity from it's related persistent storage.
67 * This will set the DIRTY flag and reset the PERSISTENT flag. Note that
68 * that the actual java object will not be deleted or changed in any other
69 * way besides its status changes makeing possible to recreate the object
70 * by simply calling the store() method.
71 */
72 public void delete();
73
74 /*** This method will refresh the entity with current data from the related
75 * persistent storage. All contained data with any existing changes will
76 * be replaced from the storage. This will reset the DIRTY flag and can
77 * possibly reset the PERSISTENT flag if the entity can no longer be found
78 * in the related database/storage.
79 */
80 public void refresh();
81
82 /*** Copies and replaces the, in the entity, contained data by reading each
83 * individual data field as a property from the provided property source.
84 * Note that since IEntity extends the IDataProvider interface it is
85 * thereby possible to copy other entities with this method. Even if the
86 * etities are not of the same type all fields with the same name will be
87 * copied into the entity. Identical data will not be copied and if any
88 * changes were made the DIRTY flag will be set.
89 */
90 public void copyData(IDataProvider entitySource);
91
92
93
94 /*** Returns true if the data in all the entities IDENTIY fields are
95 * considered equal according to their DataType class.
96 */
97 public boolean equals(Object entity);
98
99 /*** Compares all data values between the objects if they are of the
100 * same type. True is returned only if all contained data exactly matches
101 * the compareded entity's data according to their DataType class.
102 */
103 public boolean equalsExactly(Object entity);
104
105
106
107 /*** Returns true if the addressed entity field is contains a NULL value.
108 */
109 public boolean isDataNull(IFieldDescriptor fieldDescriptor);
110
111 /*** Returns the data value of the addressed data field. Can return NULL if
112 * the field excepts and contains a NULL value.
113 * @exception org.caleigo.core.exception.InvalidFieldException
114 */
115 public Object getData(IFieldDescriptor fieldDescriptor);
116
117 /*** Sets the value of the addressed data field. Sets the DIRTY flag and
118 * clears the EMPTY flag but only if the new value differs from the old.
119 * If the value is actually changed then one or more EntityChangeExceptions
120 * will be fired.
121 * @exception org.caleigo.core.exception.InvalidFieldException
122 * @exception org.caleigo.core.exception.ReadOnlyViolationException
123 */
124 public void setData(IFieldDescriptor fieldDescriptor, Object data);
125
126 /*** Clear resets all data in the entity to their defalt values and sets
127 * the flags to reflect an empty unchanged data entity.
128 */
129 public void clear();
130
131 /*** Help method that validates the data contained in the called data
132 * object and returns a ValidationResult object. Call isValid on the
133 * returned object to verify data validity. May never return null.
134 */
135 public ValidationResult validateData();
136
137 /*** Return the entity objects IEntityDescriptor that defines it's type and
138 * structure. Enables extended means of reflection for the entity.
139 */
140 public IEntityDescriptor getEntityDescriptor();
141
142 /*** Returns true if the addressed entity field has been changed since
143 * creation or the last syncronization with the persistent storage.
144 */
145 public boolean isFieldDirty(IFieldDescriptor fieldDescriptor);
146
147 /*** Returns true if any entity field in the entity has been changed since
148 * creation or the last syncronization with the persistent storage.
149 */
150 public boolean isDirty();
151
152 /*** Returns true for newly creted object that that has had no
153 * changes from the default data set at the moment of creation.
154 */
155 public boolean isEmpty();
156
157 /*** Returns true if the the entity reflects data that exists in a related
158 * persistent storage. This means that newly created and deleted entities
159 * will have this flag set to false.
160 */
161 public boolean isPersistent();
162
163 /*** Returns the data source that the entity object belongs to.
164 * Newly created will normally return the default data source defined
165 * by the IDataSourceDescriptor that the entity is linked to trough it's
166 * IEntityDescriptor. Entities loaded from a persistent storage will return
167 * the data source that identifies that storage/database.
168 */
169 public IDataSource getDataSource();
170
171 /*** Returns a identity qualifier that uniquely qualifies the entity in a
172 * persistent storage. If the entity is PERSISTENt and any of the data in
173 * the identity fields have changed since the storage syncronization the
174 * returned Qualifier will identify the stored persistent version of the
175 * entity and NOT& the updated local one.
176 */
177 public Qualifier getOriginQualifier();
178
179 /*** Should not normally be used by standard API users. Would have been
180 * protected if the Java language spec allowed it.
181 */
182 public void setStatusFlag(int flags);
183
184 /*** Should not normally be used by standard API users. Would have been
185 * protected if the Java language spec allowed it.
186 */
187 public void clearStatusFlag(int flags);
188
189 /*** Adds IEntityListener to receive notifications of performed
190 * data operations on the entity object.
191 */
192 public void addEntityListener(IEntityListener listener);
193
194 /*** Removes the specified IEntityListener from the entity object.
195 */
196 public void removeEntityListener(IEntityListener listener);
197
198 /*** Adds IEntityChangeListener to receive notifications of changes in the
199 * entity's status and data content. Note that changes can in specific
200 * situations like during end-user editation be very frequent.
201 */
202 public void addEntityChangeListener(IEntityChangeListener listener);
203
204 /*** Removes the specified IEntityListener from the entity object.
205 */
206 public void removeEntityChangeListener(IEntityChangeListener listener);
207 }