View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at 
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software 
11   * distributed under the License is distributed on an "AS IS" BASIS, 
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License.
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 }