StateManager


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