1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package javax.jdo.spi;
18
19 import java.util.BitSet;
20
21 import javax.jdo.PersistenceManager;
22
23 /*** This interface is the point of contact between managed instances of
24 * <code>PersistenceCapable</code> classes and the JDO implementation. It contains
25 * the methods used by <code>PersistenceCapable</code> instances to delegate behavior to
26 * the JDO implementation.
27 *<P>Each managed <code>PersistenceCapable</code> instance contains a reference to a
28 * <code>StateManager</code>. A <code>StateManager</code> might manage one or multiple instances of
29 * <code>PersistenceCapable</code> instances, at the choice of the implementation.
30 *
31 * @version 2.0
32 *
33 */
34 public interface StateManager {
35
36 /*** The owning <code>StateManager</code> uses this method to supply the
37 * value of the flags to the <code>PersistenceCapable</code> instance.
38 * @param pc the calling <code>PersistenceCapable</code> instance
39 * @return the value of <code>jdoFlags</code> to be stored in the <code>PersistenceCapable</code> instance
40 */
41 byte replacingFlags(PersistenceCapable pc);
42
43 /*** Replace the current value of <code>jdoStateManager</code>.
44 * <P>
45 * This method is called by the <code>PersistenceCapable</code> whenever
46 * <code>jdoReplaceStateManager</code> is called and there is already
47 * an owning <code>StateManager</code>. This is a security precaution
48 * to ensure that the owning <code>StateManager</code> is the only
49 * source of any change to its reference in the <code>PersistenceCapable</code>.
50 * @return the new value for the <code>jdoStateManager</code>
51 * @param pc the calling <code>PersistenceCapable</code> instance
52 * @param sm the proposed new value for the <code>jdoStateManager</code>
53 */
54 StateManager replacingStateManager (PersistenceCapable pc, StateManager sm);
55
56 /*** Tests whether this object is dirty.
57 *
58 * Instances that have been modified, deleted, or newly
59 * made persistent in the current transaction return <code>true</code>.
60 *
61 *<P>Transient nontransactional instances return <code>false</code>.
62 *<P>
63 * @see PersistenceCapable#jdoMakeDirty(String fieldName)
64 * @param pc the calling <code>PersistenceCapable</code> instance
65 * @return <code>true</code> if this instance has been modified in the current transaction.
66 */
67 boolean isDirty(PersistenceCapable pc);
68
69 /*** Tests whether this object is transactional.
70 *
71 * Instances that respect transaction boundaries return <code>true</code>. These instances
72 * include transient instances made transactional as a result of being the
73 * target of a <code>makeTransactional</code> method call; newly made persistent or deleted
74 * persistent instances; persistent instances read in data store
75 * transactions; and persistent instances modified in optimistic transactions.
76 *
77 *<P>Transient nontransactional instances return <code>false</code>.
78 *<P>
79 * @param pc the calling <code>PersistenceCapable</code> instance
80 * @return <code>true</code> if this instance is transactional.
81 */
82 boolean isTransactional(PersistenceCapable pc);
83
84 /*** Tests whether this object is persistent.
85 *
86 * Instances whose state is stored in the data store return <code>true</code>.
87 *
88 *<P>Transient instances return <code>false</code>.
89 *<P>
90 * @see PersistenceManager#makePersistent(Object pc)
91 * @param pc the calling <code>PersistenceCapable</code> instance
92 * @return <code>true</code> if this instance is persistent.
93 */
94 boolean isPersistent(PersistenceCapable pc);
95
96 /*** Tests whether this object has been newly made persistent.
97 *
98 * Instances that have been made persistent in the current transaction
99 * return <code>true</code>.
100 *
101 *<P>Transient instances return <code>false</code>.
102 *<P>
103 * @see PersistenceManager#makePersistent(Object pc)
104 * @param pc the calling <code>PersistenceCapable</code> instance
105 * @return <code>true</code> if this instance was made persistent
106 * in the current transaction.
107 */
108 boolean isNew(PersistenceCapable pc);
109
110 /*** Tests whether this object has been deleted.
111 *
112 * Instances that have been deleted in the current transaction return <code>true</code>.
113 *
114 *<P>Transient instances return <code>false</code>.
115 *<P>
116 * @see PersistenceManager#deletePersistent(Object pc)
117 * @param pc the calling <code>PersistenceCapable</code> instance
118 * @return <code>true</code> if this instance was deleted
119 * in the current transaction.
120 */
121 boolean isDeleted(PersistenceCapable pc);
122
123 /*** Return the <code>PersistenceManager</code> that owns this instance.
124 * @param pc the calling <code>PersistenceCapable</code> instance
125 * @return the <code>PersistenceManager</code> that owns this instance
126 */
127 PersistenceManager getPersistenceManager (PersistenceCapable pc);
128
129 /*** Mark the associated <code>PersistenceCapable</code> field dirty.
130 * <P>The <code>StateManager</code> will make a copy of the field
131 * so it can be restored if needed later, and then mark
132 * the field as modified in the current transaction.
133 * @param pc the calling <code>PersistenceCapable</code> instance
134 * @param fieldName the name of the field
135 */
136 void makeDirty (PersistenceCapable pc, String fieldName);
137
138 /*** Return the object representing the JDO identity
139 * of the calling instance. If the JDO identity is being changed in
140 * the current transaction, this method returns the identity as of
141 * the beginning of the transaction.
142 * @param pc the calling <code>PersistenceCapable</code> instance
143 * @return the object representing the JDO identity of the calling instance
144 */
145 Object getObjectId (PersistenceCapable pc);
146
147 /*** Return the object representing the JDO identity
148 * of the calling instance. If the JDO identity is being changed in
149 * the current transaction, this method returns the current identity as
150 * changed in the transaction.
151 * @param pc the calling <code>PersistenceCapable</code> instance
152 * @return the object representing the JDO identity of the calling instance
153 */
154 Object getTransactionalObjectId (PersistenceCapable pc);
155
156 /*** Return the object representing the version
157 * of the calling instance.
158 * @param pc the calling <code>PersistenceCapable</code> instance
159 * @return the object representing the version of the calling instance
160 * @since 2.0
161 */
162 Object getVersion (PersistenceCapable pc);
163
164 /*** Return <code>true</code> if the field is cached in the calling
165 * instance.
166 * @param pc the calling <code>PersistenceCapable</code> instance
167 * @param field the field number
168 * @return whether the field is cached in the calling instance
169 */
170 boolean isLoaded (PersistenceCapable pc, int field);
171
172 /*** Guarantee that the serializable transactional and persistent fields
173 * are loaded into the instance. This method is called by the generated
174 * <code>jdoPreSerialize</code> method prior to serialization of the
175 * instance.
176 * @param pc the calling <code>PersistenceCapable</code> instance
177 */
178 void preSerialize (PersistenceCapable pc);
179
180 /*** Return the value for the field.
181 * @param pc the calling <code>PersistenceCapable</code> instance
182 * @param field the field number
183 * @param currentValue the current value of the field
184 * @return the new value for the field
185 */
186 boolean getBooleanField (PersistenceCapable pc, int field, boolean currentValue);
187
188 /*** Return the value for the field.
189 * @param pc the calling <code>PersistenceCapable</code> instance
190 * @param field the field number
191 * @param currentValue the current value of the field
192 * @return the new value for the field
193 */
194 char getCharField (PersistenceCapable pc, int field, char currentValue);
195
196 /*** Return the value for the field.
197 * @param pc the calling <code>PersistenceCapable</code> instance
198 * @param field the field number
199 * @param currentValue the current value of the field
200 * @return the new value for the field
201 */
202 byte getByteField (PersistenceCapable pc, int field, byte currentValue);
203
204 /*** Return the value for the field.
205 * @param pc the calling <code>PersistenceCapable</code> instance
206 * @param field the field number
207 * @param currentValue the current value of the field
208 * @return the new value for the field
209 */
210 short getShortField (PersistenceCapable pc, int field, short currentValue);
211
212 /*** Return the value for the field.
213 * @param pc the calling <code>PersistenceCapable</code> instance
214 * @param field the field number
215 * @param currentValue the current value of the field
216 * @return the new value for the field
217 */
218 int getIntField (PersistenceCapable pc, int field, int currentValue);
219
220 /*** Return the value for the field.
221 * @param pc the calling <code>PersistenceCapable</code> instance
222 * @param field the field number
223 * @param currentValue the current value of the field
224 * @return the new value for the field
225 */
226 long getLongField (PersistenceCapable pc, int field, long currentValue);
227
228 /*** Return the value for the field.
229 * @param pc the calling <code>PersistenceCapable</code> instance
230 * @param field the field number
231 * @param currentValue the current value of the field
232 * @return the new value for the field
233 */
234 float getFloatField (PersistenceCapable pc, int field, float currentValue);
235
236 /*** Return the value for the field.
237 * @param pc the calling <code>PersistenceCapable</code> instance
238 * @param field the field number
239 * @param currentValue the current value of the field
240 * @return the new value for the field
241 */
242 double getDoubleField (PersistenceCapable pc, int field, double currentValue);
243
244 /*** Return the value for the field.
245 * @param pc the calling <code>PersistenceCapable</code> instance
246 * @param field the field number
247 * @param currentValue the current value of the field
248 * @return the new value for the field
249 */
250 String getStringField (PersistenceCapable pc, int field, String currentValue);
251
252 /*** Return the value for the field.
253 * @param pc the calling <code>PersistenceCapable</code> instance
254 * @param field the field number
255 * @param currentValue the current value of the field
256 * @return the new value for the field
257 */
258 Object getObjectField (PersistenceCapable pc, int field, Object currentValue);
259
260 /*** Mark the field as modified by the user.
261 * @param pc the calling <code>PersistenceCapable</code> instance
262 * @param field the field number
263 * @param currentValue the current value of the field
264 * @param newValue the proposed new value of the field */
265 void setBooleanField (PersistenceCapable pc, int field, boolean currentValue, boolean newValue);
266
267 /*** Mark the field as modified by the user.
268 * @param pc the calling <code>PersistenceCapable</code> instance
269 * @param field the field number
270 * @param currentValue the current value of the field
271 * @param newValue the proposed new value of the field */
272 void setCharField (PersistenceCapable pc, int field, char currentValue, char newValue);
273
274 /*** Mark the field as modified by the user.
275 * @param pc the calling <code>PersistenceCapable</code> instance
276 * @param field the field number
277 * @param currentValue the current value of the field
278 * @param newValue the proposed new value of the field */
279 void setByteField (PersistenceCapable pc, int field, byte currentValue, byte newValue);
280
281 /*** Mark the field as modified by the user.
282 * @param pc the calling <code>PersistenceCapable</code> instance
283 * @param field the field number
284 * @param currentValue the current value of the field
285 * @param newValue the proposed new value of the field */
286 void setShortField (PersistenceCapable pc, int field, short currentValue, short newValue);
287
288 /*** Mark the field as modified by the user.
289 * @param pc the calling <code>PersistenceCapable</code> instance
290 * @param field the field number
291 * @param currentValue the current value of the field
292 * @param newValue the proposed new value of the field */
293 void setIntField (PersistenceCapable pc, int field, int currentValue, int newValue);
294
295 /*** Mark the field as modified by the user.
296 * @param pc the calling <code>PersistenceCapable</code> instance
297 * @param field the field number
298 * @param currentValue the current value of the field
299 * @param newValue the proposed new value of the field */
300 void setLongField (PersistenceCapable pc, int field, long currentValue, long newValue);
301
302 /*** Mark the field as modified by the user.
303 * @param pc the calling <code>PersistenceCapable</code> instance
304 * @param field the field number
305 * @param currentValue the current value of the field
306 * @param newValue the proposed new value of the field */
307 void setFloatField (PersistenceCapable pc, int field, float currentValue, float newValue);
308
309 /*** Mark the field as modified by the user.
310 * @param pc the calling <code>PersistenceCapable</code> instance
311 * @param field the field number
312 * @param currentValue the current value of the field
313 * @param newValue the proposed new value of the field */
314 void setDoubleField (PersistenceCapable pc, int field, double currentValue, double newValue);
315
316 /*** Mark the field as modified by the user.
317 * @param pc the calling <code>PersistenceCapable</code> instance
318 * @param field the field number
319 * @param currentValue the current value of the field
320 * @param newValue the proposed new value of the field */
321 void setStringField (PersistenceCapable pc, int field, String currentValue, String newValue);
322
323 /*** Mark the field as modified by the user.
324 * @param pc the calling <code>PersistenceCapable</code> instance
325 * @param field the field number
326 * @param currentValue the current value of the field
327 * @param newValue the proposed new value of the field */
328 void setObjectField (PersistenceCapable pc, int field, Object currentValue, Object newValue);
329
330 /*** The value of the field requested to be provided to the <code>StateManager</code>
331 * @param pc the calling <code>PersistenceCapable</code> instance
332 * @param field the field number
333 * @param currentValue the current value of the field
334 */
335 void providedBooleanField (PersistenceCapable pc, int field, boolean currentValue);
336
337 /*** The value of the field requested to be provided to the <code>StateManager</code>
338 * @param pc the calling <code>PersistenceCapable</code> instance
339 * @param field the field number
340 * @param currentValue the current value of the field
341 */
342 void providedCharField (PersistenceCapable pc, int field, char currentValue);
343
344 /*** The value of the field requested to be provided to the <code>StateManager</code>
345 * @param pc the calling <code>PersistenceCapable</code> instance
346 * @param field the field number
347 * @param currentValue the current value of the field
348 */
349 void providedByteField (PersistenceCapable pc, int field, byte currentValue);
350
351 /*** The value of the field requested to be provided to the <code>StateManager</code>
352 * @param pc the calling <code>PersistenceCapable</code> instance
353 * @param field the field number
354 * @param currentValue the current value of the field
355 */
356 void providedShortField (PersistenceCapable pc, int field, short currentValue);
357
358 /*** The value of the field requested to be provided to the <code>StateManager</code>
359 * @param pc the calling <code>PersistenceCapable</code> instance
360 * @param field the field number
361 * @param currentValue the current value of the field
362 */
363 void providedIntField (PersistenceCapable pc, int field, int currentValue);
364
365 /*** The value of the field requested to be provided to the <code>StateManager</code>
366 * @param pc the calling <code>PersistenceCapable</code> instance
367 * @param field the field number
368 * @param currentValue the current value of the field
369 */
370 void providedLongField (PersistenceCapable pc, int field, long currentValue);
371
372 /*** The value of the field requested to be provided to the <code>StateManager</code>
373 * @param pc the calling <code>PersistenceCapable</code> instance
374 * @param field the field number
375 * @param currentValue the current value of the field
376 */
377 void providedFloatField (PersistenceCapable pc, int field, float currentValue);
378
379 /*** The value of the field requested to be provided to the <code>StateManager</code>
380 * @param pc the calling <code>PersistenceCapable</code> instance
381 * @param field the field number
382 * @param currentValue the current value of the field
383 */
384 void providedDoubleField (PersistenceCapable pc, int field, double currentValue);
385
386 /*** The value of the field requested to be provided to the <code>StateManager</code>
387 * @param pc the calling <code>PersistenceCapable</code> instance
388 * @param field the field number
389 * @param currentValue the current value of the field
390 */
391 void providedStringField (PersistenceCapable pc, int field, String currentValue);
392
393 /*** The value of the field requested to be provided to the <code>StateManager</code>
394 * @param pc the calling <code>PersistenceCapable</code> instance
395 * @param field the field number
396 * @param currentValue the current value of the field
397 */
398 void providedObjectField (PersistenceCapable pc, int field, Object currentValue);
399
400 /*** The replacement value of the field in the calling instance.
401 * @param pc the calling <code>PersistenceCapable</code> instance
402 * @param field the field number
403 * @return the new value for the field
404 */
405 boolean replacingBooleanField (PersistenceCapable pc, int field);
406
407 /*** The replacement value of the field in the calling instance.
408 * @param pc the calling <code>PersistenceCapable</code> instance
409 * @param field the field number
410 * @return the new value for the field
411 */
412 char replacingCharField (PersistenceCapable pc, int field);
413
414 /*** The replacement value of the field in the calling instance.
415 * @param pc the calling <code>PersistenceCapable</code> instance
416 * @param field the field number
417 * @return the new value for the field
418 */
419 byte replacingByteField (PersistenceCapable pc, int field);
420
421 /*** The replacement value of the field in the calling instance.
422 * @param pc the calling <code>PersistenceCapable</code> instance
423 * @param field the field number
424 * @return the new value for the field
425 */
426 short replacingShortField (PersistenceCapable pc, int field);
427
428 /*** The replacement value of the field in the calling instance.
429 * @param pc the calling <code>PersistenceCapable</code> instance
430 * @param field the field number
431 * @return the new value for the field
432 */
433 int replacingIntField (PersistenceCapable pc, int field);
434
435 /*** The replacement value of the field in the calling instance.
436 * @param pc the calling <code>PersistenceCapable</code> instance
437 * @param field the field number
438 * @return the new value for the field
439 */
440 long replacingLongField (PersistenceCapable pc, int field);
441
442 /*** The replacement value of the field in the calling instance.
443 * @param pc the calling <code>PersistenceCapable</code> instance
444 * @param field the field number
445 * @return the new value for the field
446 */
447 float replacingFloatField (PersistenceCapable pc, int field);
448
449 /*** The replacement value of the field in the calling instance.
450 * @param pc the calling <code>PersistenceCapable</code> instance
451 * @param field the field number
452 * @return the new value for the field
453 */
454 double replacingDoubleField (PersistenceCapable pc, int field);
455
456 /*** The replacement value of the field in the calling instance.
457 * @param pc the calling <code>PersistenceCapable</code> instance
458 * @param field the field number
459 * @return the new value for the field
460 */
461 String replacingStringField (PersistenceCapable pc, int field);
462
463 /*** The replacement value of the field in the calling instance.
464 * @param pc the calling <code>PersistenceCapable</code> instance
465 * @param field the field number
466 * @return the new value for the field
467 */
468 Object replacingObjectField (PersistenceCapable pc, int field);
469
470 /*** The replacement value of the detached state in the calling instance.
471 * @param pc the calling <code>Detachable</code> instance
472 * @param state the current value of the detached state
473 * @return the replacement value for the detached state
474 * @since 2.0
475 */
476 Object[] replacingDetachedState (Detachable pc, Object[] state);
477 }
478