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