View Javadoc

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