KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jdo > spi > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc jdoGetTransactionalObjectId();
243     
244     /** Return the version of this instance.
245      * @return the version
246      * @since 2.0
247      */

248     Object JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc jdoNewObjectIdInstance(Object JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc value);
570     }
571 }
572
Popular Tags