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