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