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