PersistenceCapable


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