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 /***
22 * A class that can be managed by a binary-compatible JDO implementation
23 * must implement this interface.
24 *
25 * <P>This interface defines methods that allow the implementation to manage
26 * the instances. It also defines methods that allow a JDO aware
27 * application to examine the runtime state of instances. For example,
28 * an application can discover whether the instance is persistent, transactional,
29 * dirty, new, deleted, or detached; and to get its associated
30 * PersistenceManager, object identity, and version if it has one.
31 *
32 * <P>In the Reference Implementation, the JDO Enhancer modifies the class
33 * to implement PersistenceCapable prior to loading the class into the runtime
34 * environment. The Reference Enhancer also adds code to implement the
35 * methods defined by PersistenceCapable.
36 *
37 *<P>The extra methods in the PersistenceCapable interface might be generated
38 * by pre-processing a .java file, or might be generated from a tool directly.
39 * The exact technique for generating the extra methods is not specified by
40 * JDO.
41 *
42 * <P>The PersistenceCapable interface is designed to avoid name conflicts
43 * in the scope of user-defined classes. All of its declared method
44 * names are prefixed with 'jdo'.
45 * @version 2.0
46 */
47 public interface PersistenceCapable {
48 /*** If jdoFlags is set to READ_WRITE_OK, then the fields in the default fetch group
49 * can be accessed for read or write without notifying the StateManager.
50 */
51 static final byte READ_WRITE_OK = 0;
52
53 /*** If jdoFlags is set to LOAD_REQUIRED, then the fields in the default fetch group
54 * cannot be accessed for read or write without notifying the StateManager.
55 */
56 static final byte LOAD_REQUIRED = 1;
57
58 /*** If jdoFlags is set to READ_OK, then the fields in the default fetch group
59 * can be accessed for read without notifying the StateManager.
60 */
61 static final byte READ_OK = -1;
62
63 /*** If jdoFieldFlags for a field includes CHECK_READ, then
64 * the field has been enhanced to call the jdoStateManager on read
65 * if the jdoFlags setting is not READ_OK or READ_WRITE_OK.
66 */
67 static final byte CHECK_READ = 1;
68
69 /*** If jdoFieldFlags for a field includes MEDIATE_READ, then
70 * the field has been enhanced to always call the jdoStateManager
71 * on all reads.
72 */
73 static final byte MEDIATE_READ = 2;
74
75 /*** If jdoFieldFlags for a field includes CHECK_WRITE,
76 * then the field has been enhanced to call the
77 * jdoStateManager on write if the jdoFlags setting is not
78 * READ_WRITE_OK;.
79 */
80 static final byte CHECK_WRITE = 4;
81
82 /*** If jdoFieldFlags for a field includes MEDIATE_WRITE, then
83 * the field has been enhanced to always call the jdoStateManager
84 * on all writes.
85 */
86 static final byte MEDIATE_WRITE = 8;
87
88 /*** If jdoFieldFlags for a field includes SERIALIZABLE,
89 * then the field is not declared as TRANSIENT.
90 */
91 static final byte SERIALIZABLE = 16;
92
93 /*** Return the associated PersistenceManager if there is one.
94 * Transactional and persistent instances return the associated
95 * PersistenceManager.
96 *
97 * <P>Transient non-transactional instances return null.
98 * <P>This method always delegates to the StateManager if it is non-null.
99 * @return the PersistenceManager associated with this instance.
100 */
101 PersistenceManager jdoGetPersistenceManager();
102
103 /*** This method sets the StateManager instance that manages the state
104 * of this instance. This method is normally used by the StateManager
105 * during the process of making an instance persistent, transient,
106 * or transactional.
107 *
108 * The caller of this method must have JDOPermission for the instance,
109 * if the instance is not already owned by a StateManager.
110 * If the parameter is null, and the StateManager approves the change,
111 * then the jdoFlags field will be reset to READ_WRITE_OK.
112 * If the parameter is not null, and the security manager approves
113 * the change, then the jdoFlags field will be reset to LOAD_REQUIRED.
114 * @param sm The StateManager which will own this instance, or null
115 * to reset the instance to transient state
116 * @throws SecurityException if the caller does not have JDOPermission
117 * @see JDOPermission
118 */
119 void jdoReplaceStateManager(StateManager sm)
120 throws SecurityException;
121
122 /*** The owning StateManager uses this method to ask the instance to
123 * provide the value of the single field identified by fieldNumber.
124 * @param fieldNumber the field whose value is to be provided by
125 * a callback to the StateManager's
126 * providedXXXField method
127 */
128 void jdoProvideField(int fieldNumber);
129
130 /*** The owning StateManager uses this method to ask the instance to
131 * provide the values of the multiple fields identified by fieldNumbers.
132 * @param fieldNumbers the fields whose values are to be provided by
133 * multiple callbacks to the StateManager's
134 * providedXXXField method
135 */
136 void jdoProvideFields(int[] fieldNumbers);
137
138 /*** The owning StateManager uses this method to ask the instance to
139 * replace the value of the single field identified by number.
140 * @param fieldNumber the field whose value is to be replaced by
141 * a callback to the StateManager's
142 * replacingXXXField method
143 */
144 void jdoReplaceField(int fieldNumber);
145
146 /*** The owning StateManager uses this method to ask the instance to
147 * replace the values of the multiple fields identified by number.
148 * @param fieldNumbers the fields whose values are to be replaced by
149 * multiple callbacks to the StateManager's
150 * replacingXXXField method
151 */
152 void jdoReplaceFields(int[] fieldNumbers);
153
154 /*** The owning StateManager uses this method to ask the instance to
155 * replace the value of the flags by calling back the StateManager
156 * replacingFlags method.
157 */
158 void jdoReplaceFlags();
159
160 /*** Copy field values from another instance of the same class
161 * to this instance.
162 *<P>This method will throw an exception if the other instance is
163 * not managed by the same StateManager as this instance.
164 * @param other the PC instance from which field values are to be copied
165 * @param fieldNumbers the field numbers to be copied into this instance
166 */
167 void jdoCopyFields(Object other, int[] fieldNumbers);
168
169 /*** Explicitly mark this instance and this field dirty.
170 * Normally, PersistenceCapable classes are able to detect changes made
171 * to their fields. However, if a reference to an array is given to a
172 * method outside the class, and the array is modified, then the
173 * persistent instance is not aware of the change. This API allows the
174 * application to notify the instance that a change was made to a field.
175 *
176 *<P>The field name should be the fully qualified name, including package
177 * name and class name of the class declaring the field. This allows
178 * unambiguous identification of the field to be marked dirty.
179 * If multiple classes declare the same field, and
180 * if the package and class name are not provided by the parameter in
181 * this API, then the field marked
182 * dirty is the field declared by the most derived class.
183 * <P>Transient instances ignore this method.
184 *<P>
185 * @param fieldName the name of the field to be marked dirty.
186 */
187 void jdoMakeDirty(String fieldName);
188
189 /*** Return a copy of the JDO identity associated with this instance.
190 *
191 * <P>Persistent instances of PersistenceCapable classes have a JDO identity
192 * managed by the PersistenceManager. This method returns a copy of the
193 * ObjectId that represents the JDO identity.
194 *
195 * <P>Transient instances return null.
196 *
197 * <P>The ObjectId may be serialized
198 * and later restored, and used with a PersistenceManager from the same JDO
199 * implementation to locate a persistent instance with the same data store
200 * identity.
201 *
202 * <P>If the JDO identity is managed by the application, then the ObjectId may
203 * be used with a PersistenceManager from any JDO implementation that supports
204 * the PersistenceCapable class.
205 *
206 * <P>If the JDO identity is not managed by the application or the data store,
207 * then the ObjectId returned is only valid within the current transaction.
208 * <P>If the JDO identity is being changed in the transaction, this method
209 * returns the object id as of the beginning of the current transaction.
210 *
211 * @see PersistenceManager#getObjectId(Object pc)
212 * @see PersistenceManager#getObjectById(Object oid, boolean validate)
213 * @return a copy of the ObjectId of this instance as of the beginning of the transaction.
214 */
215 Object jdoGetObjectId();
216
217 /*** Return a copy of the JDO identity associated with this instance.
218 * This method is the same as jdoGetObjectId if the identity of the
219 * instance has not changed in the current transaction.
220 * <P>If the JDO identity is being changed in the transaction, this method
221 * returns the current object id as modified in the current transaction.
222 *
223 * @see #jdoGetObjectId()
224 * @see PersistenceManager#getObjectId(Object pc)
225 * @see PersistenceManager#getObjectById(Object oid, boolean validate)
226 * @return a copy of the ObjectId of this instance as modified in the transaction.
227 */
228 Object jdoGetTransactionalObjectId();
229
230 /*** Return the version of this instance.
231 * @return the version
232 * @since 2.0
233 */
234 Object jdoGetVersion();
235
236 /*** Tests whether this object is dirty.
237 *
238 * Instances that have been modified, deleted, or newly
239 * made persistent in the current transaction return true.
240 *
241 *<P>Transient instances return false.
242 *<P>
243 * @see javax.jdo.JDOHelper#isDirty(Object pc)
244 * @see javax.jdo.JDOHelper#makeDirty(Object pc, String fieldName)
245 * @see #jdoMakeDirty(String fieldName)
246 * @return true if this instance has been modified in the current transaction.
247 */
248 boolean jdoIsDirty();
249
250 /*** Tests whether this object is transactional.
251 *
252 * Instances whose state is associated with the current transaction
253 * return true.
254 *
255 *<P>Transient instances return false.
256 *<P>
257 * @see javax.jdo.JDOHelper#isTransactional(Object pc)
258 * @see PersistenceManager#makeTransactional(Object pc)
259 * @return true if this instance is transactional.
260 */
261 boolean jdoIsTransactional();
262
263 /*** Tests whether this object is persistent.
264 * Instances that represent persistent objects in the data store
265 * return true.
266 * @see javax.jdo.JDOHelper#isPersistent(Object pc)
267 * @see PersistenceManager#makePersistent(Object pc)
268 * @return true if this instance is persistent.
269 */
270 boolean jdoIsPersistent();
271
272 /*** Tests whether this object has been newly made persistent.
273 *
274 * Instances that have been made persistent in the current transaction
275 * return true.
276 *
277 *<P>Transient instances return false.
278 *<P>
279 * @see javax.jdo.JDOHelper#isNew(Object pc)
280 * @see PersistenceManager#makePersistent(Object pc)
281 * @return true if this instance was made persistent
282 * in the current transaction.
283 */
284 boolean jdoIsNew();
285
286 /*** Tests whether this object has been deleted.
287 *
288 * Instances that have been deleted in the current transaction return true.
289 *
290 *<P>Transient instances return false.
291 *<P>
292 * @see javax.jdo.JDOHelper#isDeleted(Object pc)
293 * @see PersistenceManager#deletePersistent(Object pc)
294 * @return true if this instance was deleted
295 * in the current transaction.
296 */
297 boolean jdoIsDeleted();
298
299 /*** Tests whether this object has been detached.
300 *
301 * Instances that have been detached return true.
302 *
303 *<P>Transient instances return false.
304 *<P>
305 * @see javax.jdo.JDOHelper#isDetached(Object pc)
306 * @return true if this instance is detached.
307 * @since 2.0
308 */
309 boolean jdoIsDetached();
310
311 /*** Return a new instance of this class, with the jdoStateManager set to the
312 * parameter, and jdoFlags set to LOAD_REQUIRED.
313 * <P>This method is used as a performance optimization as an alternative to
314 * using reflection to construct a new instance. It is used by the
315 * JDOImplHelper class method newInstance.
316 * @return a new instance of this class.
317 * @see JDOImplHelper#newInstance(Class pcClass, StateManager sm)
318 * @param sm the StateManager that will own the new instance.
319 */
320 PersistenceCapable jdoNewInstance(StateManager sm);
321
322 /*** Return a new instance of this class, with the jdoStateManager set to the
323 * parameter, key fields initialized to the values in the oid, and jdoFlags
324 * set to LOAD_REQUIRED.
325 * <P>This method is used as a performance optimization as an alternative to
326 * using reflection to construct a new instance of a class that uses
327 * application identity. It is used by the
328 * JDOImplHelper class method newInstance.
329 * @return a new instance of this class.
330 * @see JDOImplHelper#newInstance(Class pcClass, StateManager sm)
331 * @param sm the StateManager that will own the new instance.
332 * @param oid an instance of the object id class (application identity).
333 */
334 PersistenceCapable jdoNewInstance(StateManager sm, Object oid);
335
336 /*** Create a new instance of the
337 * ObjectId class for this PersistenceCapable class and initialize
338 * the key fields from the instance on which this method is called.
339 * This method creates a new instance of the class used for JDO identity.
340 * It is intended only for application identity. If the class has been
341 * enhanced for datastore identity, or if the class is abstract,
342 * null is returned.
343 * <P>For classes using single field identity, this method must be called
344 * on an instance of a persistence-capable class with its primary key
345 * field initialized (not null), or a
346 * <code>JDONullIdentityException</code> is thrown.
347 * <P>The instance returned is initialized with the value(s) of the
348 * primary key field(s) of the instance on which the method is called.
349 * @return the new instance created.
350 */
351 Object jdoNewObjectIdInstance();
352
353 /*** Create a new instance of the class used for JDO identity, using the
354 * key constructor of the object id class. It is intended for single
355 * field identity. The identity
356 * instance returned has no relationship with the values of the primary key
357 * fields of the persistence-capable instance on which the method is called.
358 * If the key is the wrong class for the object id class, null is returned.
359 * <P>For classes that use single field identity, if the parameter is
360 * of one of the following types, the behavior must be as specified:
361 * <ul><li><code>Number</code> or <code>Character</code>: the
362 * parameter must be the single field
363 * type or the wrapper class of the primitive field type; the parameter
364 * is passed to the single field identity constructor
365 * </li><li><code>ObjectIdFieldSupplier</code>: the field value
366 * is fetched from the <code>ObjectIdFieldSupplier</code> and passed to the
367 * single field identity constructor
368 * </li><li><code>String</code>: the String is passed to the
369 * single field identity constructor
370 * </li></ul>
371 * @return the new instance created.
372 * @param o the object identity constructor parameter
373 * @since 2.0
374 */
375 Object jdoNewObjectIdInstance(Object o);
376
377 /*** Copy fields from this PersistenceCapable instance to the Object Id
378 * instance. For classes using single field identity, this method always
379 * throws <code>JDOUserException</code>.
380 * @param oid the ObjectId target of the key fields
381 */
382 void jdoCopyKeyFieldsToObjectId(Object oid);
383
384 /*** Copy fields from an outside source to the key fields in the ObjectId.
385 * This method is generated in the <code>PersistenceCapable</code>
386 * class to generate
387 * a call to the field manager for each key field in the ObjectId. For
388 * example, an ObjectId class that has three key fields <code>(int id,
389 * String name, and Float salary)</code> would have the method generated:
390 * <code>
391 * <P>void jdoCopyKeyFieldsToObjectId
392 * <P>(ObjectIdFieldSupplier fm, Object objectId) {
393 * <P>EmployeeKey oid = (EmployeeKey)objectId;
394 * <P>oid.id = fm.fetchIntField (0);
395 * <P>oid.name = fm.fetchStringField (1);
396 * <P>oid.salary = fm.fetchObjectField (2);
397 * <P>}
398 * </code>
399 * <P>The implementation is responsible for implementing the
400 * <code>ObjectIdFieldSupplier</code> to produce the values
401 * for the key fields.
402 * <P>For classes using single field identity, this method always
403 * throws <code>JDOUserException</code>.
404 * @param oid the ObjectId target of the copy.
405 * @param fm the field supplier that supplies the field values.
406 */
407 void jdoCopyKeyFieldsToObjectId(ObjectIdFieldSupplier fm, Object oid);
408
409 /*** Copy fields to an outside consumer from the key fields in the ObjectId.
410 * This method is generated in the <code>PersistenceCapable</code>
411 * class to generate
412 * a call to the field manager for each key field in the ObjectId. For
413 * example, an ObjectId class that has three key fields <code>(int id,
414 * String name, and Float salary)</code> would have the method generated:
415 * <code>
416 * <P>void copyKeyFieldsFromObjectId
417 * <P> (ObjectIdFieldConsumer fm, Object objectId) {
418 * <P> EmployeeKey oid = (EmployeeKey)objectId;
419 * <P> fm.storeIntField (0, oid.id);
420 * <P> fm.storeStringField (1, oid.name);
421 * <P> fm.storeObjectField (2, oid.salary);
422 * <P>}
423 * </code>
424 * <P>The implementation is responsible for implementing the
425 * <code>ObjectIdFieldConsumer</code> to store the values for the
426 * key fields.
427 * @param oid the ObjectId source of the copy.
428 * @param fm the field manager that receives the field values.
429 */
430 void jdoCopyKeyFieldsFromObjectId(ObjectIdFieldConsumer fm, Object oid);
431
432 /*** This interface is a convenience interface that allows an instance to
433 * implement both <code>ObjectIdFieldSupplier</code> and
434 * <code>ObjectIdFieldConsumer</code>.
435 */
436 static interface ObjectIdFieldManager extends ObjectIdFieldConsumer, ObjectIdFieldSupplier {}
437
438 /*** This interface is used to provide fields to the Object id instance. It is used
439 * by the method copyKeyFieldsToObjectId. When the method is called, the
440 * generated code calls the instance of ObjectIdFieldManager for each field in
441 * the object id.
442 */
443 static interface ObjectIdFieldSupplier {
444
445 /*** Fetch one field from the field manager. This field will be stored in the
446 * proper field of the ObjectId.
447 * @param fieldNumber the field number of the key field.
448 * @return the value of the field to be stored into the ObjectId.
449 */
450 boolean fetchBooleanField(int fieldNumber);
451
452 /*** Fetch one field from the field manager. This field will be stored in the
453 * proper field of the ObjectId.
454 * @param fieldNumber the field number of the key field.
455 * @return the value of the field to be stored into the ObjectId.
456 */
457 char fetchCharField(int fieldNumber);
458
459 /*** Fetch one field from the field manager. This field will be stored in the
460 * proper field of the ObjectId.
461 * @param fieldNumber the field number of the key field.
462 * @return the value of the field to be stored into the ObjectId.
463 */
464 byte fetchByteField(int fieldNumber);
465
466 /*** Fetch one field from the field manager. This field will be stored in the
467 * proper field of the ObjectId.
468 * @param fieldNumber the field number of the key field.
469 * @return the value of the field to be stored into the ObjectId.
470 */
471 short fetchShortField(int fieldNumber);
472
473 /*** Fetch one field from the field manager. This field will be stored in the
474 * proper field of the ObjectId.
475 * @param fieldNumber the field number of the key field.
476 * @return the value of the field to be stored into the ObjectId.
477 */
478 int fetchIntField(int fieldNumber);
479
480 /*** Fetch one field from the field manager. This field will be stored in the
481 * proper field of the ObjectId.
482 * @param fieldNumber the field number of the key field.
483 * @return the value of the field to be stored into the ObjectId.
484 */
485 long fetchLongField(int fieldNumber);
486
487 /*** Fetch one field from the field manager. This field will be stored in the
488 * proper field of the ObjectId.
489 * @param fieldNumber the field number of the key field.
490 * @return the value of the field to be stored into the ObjectId.
491 */
492 float fetchFloatField(int fieldNumber);
493
494 /*** Fetch one field from the field manager. This field will be stored in the
495 * proper field of the ObjectId.
496 * @param fieldNumber the field number of the key field.
497 * @return the value of the field to be stored into the ObjectId.
498 */
499 double fetchDoubleField(int fieldNumber);
500
501 /*** Fetch one field from the field manager. This field will be stored in the
502 * proper field of the ObjectId.
503 * @param fieldNumber the field number of the key field.
504 * @return the value of the field to be stored into the ObjectId.
505 */
506 String fetchStringField(int fieldNumber);
507
508 /*** Fetch one field from the field manager. This field will be stored in the
509 * proper field of the ObjectId.
510 * @param fieldNumber the field number of the key field.
511 * @return the value of the field to be stored into the ObjectId.
512 */
513 Object fetchObjectField(int fieldNumber);
514 }
515
516 /*** This interface is used to store fields from the Object id instance. It is used
517 * by the method copyKeyFieldsFromObjectId. When the method is called, the
518 * generated code calls the instance of ObjectIdFieldManager for each field in
519 * the object id.
520 */
521 static interface ObjectIdFieldConsumer {
522
523 /*** Store one field into the field manager. This field was retrieved from
524 * the field of the ObjectId.
525 * @param fieldNumber the field number of the key field.
526 * @param value the value of the field from the ObjectId.
527 */
528 void storeBooleanField(int fieldNumber, boolean value);
529
530 /*** Store one field into the field manager. This field was retrieved from
531 * the field of the ObjectId.
532 * @param fieldNumber the field number of the key field.
533 * @param value the value of the field from the ObjectId.
534 */
535 void storeCharField(int fieldNumber, char value);
536
537 /*** Store one field into the field manager. This field was retrieved from
538 * the field of the ObjectId.
539 * @param fieldNumber the field number of the key field.
540 * @param value the value of the field from the ObjectId.
541 */
542 void storeByteField(int fieldNumber, byte value);
543
544 /*** Store one field into the field manager. This field was retrieved from
545 * the field of the ObjectId.
546 * @param fieldNumber the field number of the key field.
547 * @param value the value of the field from the ObjectId.
548 */
549 void storeShortField(int fieldNumber, short value);
550
551 /*** Store one field into the field manager. This field was retrieved from
552 * the field of the ObjectId.
553 * @param fieldNumber the field number of the key field.
554 * @param value the value of the field from the ObjectId.
555 */
556 void storeIntField(int fieldNumber, int value);
557
558 /*** Store one field into the field manager. This field was retrieved from
559 * the field of the ObjectId.
560 * @param fieldNumber the field number of the key field.
561 * @param value the value of the field from the ObjectId.
562 */
563 void storeLongField(int fieldNumber, long value);
564
565 /*** Store one field into the field manager. This field was retrieved from
566 * the field of the ObjectId.
567 * @param fieldNumber the field number of the key field.
568 * @param value the value of the field from the ObjectId.
569 */
570 void storeFloatField(int fieldNumber, float value);
571
572 /*** Store one field into the field manager. This field was retrieved from
573 * the field of the ObjectId.
574 * @param fieldNumber the field number of the key field.
575 * @param value the value of the field from the ObjectId.
576 */
577 void storeDoubleField(int fieldNumber, double value);
578
579 /*** Store one field into the field manager. This field was retrieved from
580 * the field of the ObjectId.
581 * @param fieldNumber the field number of the key field.
582 * @param value the value of the field from the ObjectId.
583 */
584 void storeStringField(int fieldNumber, String value);
585
586 /*** Store one field into the field manager. This field was retrieved from
587 * the field of the ObjectId.
588 * @param fieldNumber the field number of the key field.
589 * @param value the value of the field from the ObjectId.
590 */
591 void storeObjectField(int fieldNumber, Object value);
592 }
593 }