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  /*** This interface is the point of contact between managed instances of
22   * <code>PersistenceCapable</code> classes and the JDO implementation.  It 
23   * contains the methods used by <code>PersistenceCapable</code> instances to 
24   * delegate behavior to the JDO implementation.
25   *<P>Each managed <code>PersistenceCapable</code> instance contains a reference 
26   * to a <code>StateManager</code>.  A <code>StateManager</code> might manage one 
27   * or multiple instances of <code>PersistenceCapable</code> instances, at the 
28   * choice of the implementation.
29   *
30   * @version 2.0
31   *
32   */
33  public interface StateManager {
34      
35      /*** The owning <code>StateManager</code> uses this method to supply the 
36       * value of the flags to the <code>PersistenceCapable</code> instance.
37       * @param pc the calling <code>PersistenceCapable</code> instance
38       * @return the value of <code>jdoFlags</code> to be stored in the 
39       * <code>PersistenceCapable</code> instance
40       */
41      byte replacingFlags(PersistenceCapable pc);
42  
43      /*** Replace the current value of <code>jdoStateManager</code>.
44       * <P>
45       * This method is called by the <code>PersistenceCapable</code> whenever
46       * <code>jdoReplaceStateManager</code> is called and there is already
47       * an owning <code>StateManager</code>.  This is a security precaution
48       * to ensure that the owning <code>StateManager</code> is the only
49       * source of any change to its reference in the 
50       * <code>PersistenceCapable</code>.
51       * @return the new value for the <code>jdoStateManager</code>
52       * @param pc the calling <code>PersistenceCapable</code> instance
53       * @param sm the proposed new value for the <code>jdoStateManager</code>
54       */ 
55      StateManager replacingStateManager (PersistenceCapable pc, StateManager sm);
56      
57      /*** Tests whether this object is dirty.
58       *
59       * Instances that have been modified, deleted, or newly 
60       * made persistent in the current transaction return <code>true</code>.
61       *
62       *<P>Transient nontransactional instances return <code>false</code>.
63       *<P>
64       * @see PersistenceCapable#jdoMakeDirty(String fieldName)
65       * @param pc the calling <code>PersistenceCapable</code> instance
66       * @return <code>true</code> if this instance has been modified in the 
67       * current transaction.
68       */
69      boolean isDirty(PersistenceCapable pc);
70  
71      /*** Tests whether this object is transactional.
72       *
73       * Instances that respect transaction boundaries return <code>true</code>.  
74       * These instances include transient instances made transactional as a 
75       * result of being the target of a <code>makeTransactional</code> method 
76       * call; newly made persistent or deleted persistent instances; persistent 
77       * instances read in data store transactions; and persistent instances 
78       * modified in optimistic transactions.
79       *
80       *<P>Transient nontransactional instances return <code>false</code>.
81       *<P>
82       * @param pc the calling <code>PersistenceCapable</code> instance
83       * @return <code>true</code> if this instance is transactional.
84       */
85      boolean isTransactional(PersistenceCapable pc);
86  
87      /*** Tests whether this object is persistent.
88       *
89       * Instances whose state is stored in the data store return 
90       * <code>true</code>.
91       *
92       *<P>Transient instances return <code>false</code>.
93       *<P>
94       * @see PersistenceManager#makePersistent(Object pc)
95       * @param pc the calling <code>PersistenceCapable</code> instance
96       * @return <code>true</code> if this instance is persistent.
97       */
98      boolean isPersistent(PersistenceCapable pc);
99  
100     /*** Tests whether this object has been newly made persistent.
101      *
102      * Instances that have been made persistent in the current transaction 
103      * return <code>true</code>.
104      *
105      * <P>Transient instances return <code>false</code>.
106      * <P>
107      * @see PersistenceManager#makePersistent(Object pc)
108      * @param pc the calling <code>PersistenceCapable</code> instance
109      * @return <code>true</code> if this instance was made persistent
110      * in the current transaction.
111      */
112     boolean isNew(PersistenceCapable pc);
113 
114     /*** Tests whether this object has been deleted.
115      *
116      * Instances that have been deleted in the current transaction return 
117      * <code>true</code>.
118      *
119      *<P>Transient instances return <code>false</code>.
120      *<P>
121      * @see PersistenceManager#deletePersistent(Object pc)
122      * @param pc the calling <code>PersistenceCapable</code> instance
123      * @return <code>true</code> if this instance was deleted
124      * in the current transaction.
125      */
126     boolean isDeleted(PersistenceCapable pc);
127     
128     /*** Return the <code>PersistenceManager</code> that owns this instance.
129      * @param pc the calling <code>PersistenceCapable</code> instance
130      * @return the <code>PersistenceManager</code> that owns this instance
131      */
132     PersistenceManager getPersistenceManager (PersistenceCapable pc);
133     
134     /*** Mark the associated <code>PersistenceCapable</code> field dirty.
135      * <P>The <code>StateManager</code> will make a copy of the field
136      * so it can be restored if needed later, and then mark
137      * the field as modified in the current transaction.
138      * @param pc the calling <code>PersistenceCapable</code> instance
139      * @param fieldName the name of the field
140      */    
141     void makeDirty (PersistenceCapable pc, String fieldName);
142     
143     /*** Return the object representing the JDO identity 
144      * of the calling instance.  If the JDO identity is being changed in
145      * the current transaction, this method returns the identity as of
146      * the beginning of the transaction.
147      * @param pc the calling <code>PersistenceCapable</code> instance
148      * @return the object representing the JDO identity of the calling instance
149      */    
150     Object getObjectId (PersistenceCapable pc);
151 
152     /*** Return the object representing the JDO identity 
153      * of the calling instance.  If the JDO identity is being changed in
154      * the current transaction, this method returns the current identity as
155      * changed in the transaction.
156      * @param pc the calling <code>PersistenceCapable</code> instance
157      * @return the object representing the JDO identity of the calling instance
158      */    
159     Object getTransactionalObjectId (PersistenceCapable pc);
160 
161     /*** Return the object representing the version 
162      * of the calling instance.
163      * @param pc the calling <code>PersistenceCapable</code> instance
164      * @return the object representing the version of the calling instance
165      * @since 2.0
166      */    
167     Object getVersion (PersistenceCapable pc);
168 
169     /*** Return <code>true</code> if the field is cached in the calling
170      * instance.
171      * @param pc the calling <code>PersistenceCapable</code> instance
172      * @param field the field number
173      * @return whether the field is cached in the calling instance
174      */    
175     boolean isLoaded (PersistenceCapable pc, int field);
176     
177     /*** Guarantee that the serializable transactional and persistent fields
178      * are loaded into the instance.  This method is called by the generated
179      * <code>jdoPreSerialize</code> method prior to serialization of the
180      * instance.
181      * @param pc the calling <code>PersistenceCapable</code> instance
182      */    
183     void preSerialize (PersistenceCapable pc);
184     
185     /*** Return the value for the field.
186      * @param pc the calling <code>PersistenceCapable</code> instance
187      * @param field the field number 
188      * @param currentValue the current value of the field
189      * @return the new value for the field
190      */    
191     boolean getBooleanField (
192             PersistenceCapable pc, int field, boolean currentValue);
193     
194     /*** Return the value for the field.
195      * @param pc the calling <code>PersistenceCapable</code> instance
196      * @param field the field number 
197      * @param currentValue the current value of the field
198      * @return the new value for the field
199      */    
200     char getCharField (PersistenceCapable pc, int field, char currentValue);
201     
202     /*** Return the value for the field.
203      * @param pc the calling <code>PersistenceCapable</code> instance
204      * @param field the field number 
205      * @param currentValue the current value of the field
206      * @return the new value for the field
207      */    
208     byte getByteField (PersistenceCapable pc, int field, byte currentValue);
209     
210     /*** Return the value for the field.
211      * @param pc the calling <code>PersistenceCapable</code> instance
212      * @param field the field number 
213      * @param currentValue the current value of the field
214      * @return the new value for the field
215      */    
216     short getShortField (PersistenceCapable pc, int field, short currentValue);
217     
218     /*** Return the value for the field.
219      * @param pc the calling <code>PersistenceCapable</code> instance
220      * @param field the field number 
221      * @param currentValue the current value of the field
222      * @return the new value for the field
223      */    
224     int getIntField (PersistenceCapable pc, int field, int currentValue);
225     
226     /*** Return the value for the field.
227      * @param pc the calling <code>PersistenceCapable</code> instance
228      * @param field the field number 
229      * @param currentValue the current value of the field
230      * @return the new value for the field
231      */    
232     long getLongField (PersistenceCapable pc, int field, long currentValue);
233     
234     /*** Return the value for the field.
235      * @param pc the calling <code>PersistenceCapable</code> instance
236      * @param field the field number 
237      * @param currentValue the current value of the field
238      * @return the new value for the field
239      */    
240     float getFloatField (PersistenceCapable pc, int field, float currentValue);
241     
242     /*** Return the value for the field.
243      * @param pc the calling <code>PersistenceCapable</code> instance
244      * @param field the field number 
245      * @param currentValue the current value of the field
246      * @return the new value for the field
247      */    
248     double getDoubleField (PersistenceCapable pc, int field, 
249                            double currentValue);
250     
251     /*** Return the value for the field.
252      * @param pc the calling <code>PersistenceCapable</code> instance
253      * @param field the field number 
254      * @param currentValue the current value of the field
255      * @return the new value for the field
256      */    
257     String getStringField (PersistenceCapable pc, int field, 
258                            String currentValue);
259     
260     /*** Return the value for the field.
261      * @param pc the calling <code>PersistenceCapable</code> instance
262      * @param field the field number 
263      * @param currentValue the current value of the field
264      * @return the new value for the field
265      */    
266     Object getObjectField (PersistenceCapable pc, int field, 
267                            Object currentValue);
268 
269     /*** Mark the field as modified by the user.
270      * @param pc the calling <code>PersistenceCapable</code> instance
271      * @param field the field number
272      * @param currentValue the current value of the field
273      * @param newValue the proposed new value of the field */    
274     void setBooleanField (PersistenceCapable pc, int field, 
275                           boolean currentValue, boolean newValue);
276 
277     /*** Mark the field as modified by the user.
278      * @param pc the calling <code>PersistenceCapable</code> instance
279      * @param field the field number
280      * @param currentValue the current value of the field
281      * @param newValue the proposed new value of the field */    
282     void setCharField (PersistenceCapable pc, int field, 
283                        char currentValue, char newValue);
284 
285     /*** Mark the field as modified by the user.
286      * @param pc the calling <code>PersistenceCapable</code> instance
287      * @param field the field number
288      * @param currentValue the current value of the field
289      * @param newValue the proposed new value of the field */    
290     void setByteField (PersistenceCapable pc, int field, 
291                        byte currentValue, byte newValue);
292 
293     /*** Mark the field as modified by the user.
294      * @param pc the calling <code>PersistenceCapable</code> instance
295      * @param field the field number
296      * @param currentValue the current value of the field
297      * @param newValue the proposed new value of the field */    
298     void setShortField (PersistenceCapable pc, int field, 
299                         short currentValue, short newValue);
300 
301     /*** Mark the field as modified by the user.
302      * @param pc the calling <code>PersistenceCapable</code> instance
303      * @param field the field number
304      * @param currentValue the current value of the field
305      * @param newValue the proposed new value of the field */    
306     void setIntField (PersistenceCapable pc, int field, 
307                       int currentValue, int newValue);
308 
309     /*** Mark the field as modified by the user.
310      * @param pc the calling <code>PersistenceCapable</code> instance
311      * @param field the field number
312      * @param currentValue the current value of the field
313      * @param newValue the proposed new value of the field */    
314     void setLongField (PersistenceCapable pc, int field, 
315                        long currentValue, long newValue);
316 
317     /*** Mark the field as modified by the user.
318      * @param pc the calling <code>PersistenceCapable</code> instance
319      * @param field the field number
320      * @param currentValue the current value of the field
321      * @param newValue the proposed new value of the field */    
322     void setFloatField (PersistenceCapable pc, int field, 
323                         float currentValue, float newValue);
324 
325     /*** Mark the field as modified by the user.
326      * @param pc the calling <code>PersistenceCapable</code> instance
327      * @param field the field number
328      * @param currentValue the current value of the field
329      * @param newValue the proposed new value of the field */    
330     void setDoubleField (PersistenceCapable pc, int field, 
331                          double currentValue, double newValue);
332 
333     /*** Mark the field as modified by the user.
334      * @param pc the calling <code>PersistenceCapable</code> instance
335      * @param field the field number
336      * @param currentValue the current value of the field
337      * @param newValue the proposed new value of the field */    
338     void setStringField (PersistenceCapable pc, int field, 
339                          String currentValue, String newValue);
340 
341     /*** Mark the field as modified by the user.
342      * @param pc the calling <code>PersistenceCapable</code> instance
343      * @param field the field number
344      * @param currentValue the current value of the field
345      * @param newValue the proposed new value of the field */    
346     void setObjectField (PersistenceCapable pc, int field, 
347                          Object currentValue, Object newValue);
348 
349     /*** The value of the field requested to be provided to the 
350      * <code>StateManager</code>.
351      * @param pc the calling <code>PersistenceCapable</code> instance
352      * @param field the field number 
353      * @param currentValue the current value of the field
354      */    
355     void providedBooleanField (PersistenceCapable pc, int field, 
356                                boolean currentValue);
357 
358     /*** The value of the field requested to be provided to the 
359      * <code>StateManager</code>.
360      * @param pc the calling <code>PersistenceCapable</code> instance
361      * @param field the field number 
362      * @param currentValue the current value of the field
363      */    
364     void providedCharField (PersistenceCapable pc, int field, 
365                             char currentValue);
366 
367     /*** The value of the field requested to be provided to the 
368      * <code>StateManager</code>.
369      * @param pc the calling <code>PersistenceCapable</code> instance
370      * @param field the field number 
371      * @param currentValue the current value of the field
372      */    
373     void providedByteField (PersistenceCapable pc, int field, 
374                             byte currentValue);
375 
376     /*** The value of the field requested to be provided to the 
377      * <code>StateManager</code>.
378      * @param pc the calling <code>PersistenceCapable</code> instance
379      * @param field the field number 
380      * @param currentValue the current value of the field
381      */    
382     void providedShortField (PersistenceCapable pc, int field, 
383                              short currentValue);
384 
385     /*** The value of the field requested to be provided to the 
386      * <code>StateManager</code>.
387      * @param pc the calling <code>PersistenceCapable</code> instance
388      * @param field the field number 
389      * @param currentValue the current value of the field
390      */    
391     void providedIntField (PersistenceCapable pc, int field, int currentValue);
392 
393     /*** The value of the field requested to be provided to the 
394      * <code>StateManager</code>.
395      * @param pc the calling <code>PersistenceCapable</code> instance
396      * @param field the field number 
397      * @param currentValue the current value of the field
398      */    
399     void providedLongField (PersistenceCapable pc, int field, 
400                             long currentValue);
401 
402     /*** The value of the field requested to be provided to the 
403      * <code>StateManager</code>.
404      * @param pc the calling <code>PersistenceCapable</code> instance
405      * @param field the field number 
406      * @param currentValue the current value of the field
407      */    
408     void providedFloatField (PersistenceCapable pc, int field, 
409                              float currentValue);
410 
411     /*** The value of the field requested to be provided to the 
412      * <code>StateManager</code>.
413      * @param pc the calling <code>PersistenceCapable</code> instance
414      * @param field the field number 
415      * @param currentValue the current value of the field
416      */    
417     void providedDoubleField (PersistenceCapable pc, int field, 
418                               double currentValue);
419 
420     /*** The value of the field requested to be provided to the 
421      * <code>StateManager</code>.
422      * @param pc the calling <code>PersistenceCapable</code> instance
423      * @param field the field number 
424      * @param currentValue the current value of the field
425      */    
426     void providedStringField (PersistenceCapable pc, int field, 
427                               String currentValue);
428 
429     /*** The value of the field requested to be provided to the 
430      * <code>StateManager</code>.
431      * @param pc the calling <code>PersistenceCapable</code> instance
432      * @param field the field number 
433      * @param currentValue the current value of the field
434      */    
435     void providedObjectField (PersistenceCapable pc, int field, 
436                               Object currentValue);
437 
438     /*** The replacement value of the field in the calling instance.
439      * @param pc the calling <code>PersistenceCapable</code> instance
440      * @param field the field number
441      * @return the new value for the field
442      */    
443     boolean replacingBooleanField (PersistenceCapable pc, int field);
444 
445     /*** The replacement value of the field in the calling instance.
446      * @param pc the calling <code>PersistenceCapable</code> instance
447      * @param field the field number 
448      * @return the new value for the field
449      */    
450     char replacingCharField (PersistenceCapable pc, int field);
451 
452     /*** The replacement value of the field in the calling instance.
453      * @param pc the calling <code>PersistenceCapable</code> instance
454      * @param field the field number 
455      * @return the new value for the field
456      */    
457     byte replacingByteField (PersistenceCapable pc, int field);
458 
459     /*** The replacement value of the field in the calling instance.
460      * @param pc the calling <code>PersistenceCapable</code> instance
461      * @param field the field number 
462      * @return the new value for the field
463      */    
464     short replacingShortField (PersistenceCapable pc, int field);
465 
466     /*** The replacement value of the field in the calling instance.
467      * @param pc the calling <code>PersistenceCapable</code> instance
468      * @param field the field number 
469      * @return the new value for the field
470      */    
471     int replacingIntField (PersistenceCapable pc, int field);
472 
473     /*** The replacement value of the field in the calling instance.
474      * @param pc the calling <code>PersistenceCapable</code> instance
475      * @param field the field number 
476      * @return the new value for the field
477      */    
478     long replacingLongField (PersistenceCapable pc, int field);
479 
480     /*** The replacement value of the field in the calling instance.
481      * @param pc the calling <code>PersistenceCapable</code> instance
482      * @param field the field number 
483      * @return the new value for the field
484      */    
485     float replacingFloatField (PersistenceCapable pc, int field);
486 
487     /*** The replacement value of the field in the calling instance.
488      * @param pc the calling <code>PersistenceCapable</code> instance
489      * @param field the field number 
490      * @return the new value for the field
491      */    
492     double replacingDoubleField (PersistenceCapable pc, int field);
493 
494     /*** The replacement value of the field in the calling instance.
495      * @param pc the calling <code>PersistenceCapable</code> instance
496      * @param field the field number 
497      * @return the new value for the field
498      */    
499     String replacingStringField (PersistenceCapable pc, int field);
500 
501     /*** The replacement value of the field in the calling instance.
502      * @param pc the calling <code>PersistenceCapable</code> instance
503      * @param field the field number 
504      * @return the new value for the field
505      */    
506     Object replacingObjectField (PersistenceCapable pc, int field);
507     
508     /*** The replacement value of the detached state in the calling instance.
509      * @param pc the calling <code>Detachable</code> instance
510      * @param state the current value of the detached state
511      * @return the replacement value for the detached state
512      * @since 2.0
513      */
514     Object[] replacingDetachedState (Detachable pc, Object[] state);
515 }