StateManager


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package com.sun.jdo.spi.persistence.support.sqlstore;
25  
26  /**
27   * An object that manages the state transitions and the contents of the
28   * fields of a JDO Instance.
29   *
30   * If a JDO Instance is persistent or transactional, it contains a
31   * non-null reference to a JDO <code>StateManager</code> instance which is
32   * responsible for managing the JDO Instance state changes and for
33   * interfacing with the JDO PersistenceManager.
34   *
35   * Additionally, Persistent JDO Instances refers to an instance of the
36   * JDO <code>StateManager</code> instance responsible for the state
37   * transitions of the instance as well as managing the contents of the
38   * fields of the instance.
39   *
40   * The JDO <code>StateManager</code> interface is the primary interface used
41   * by the JDO Instance to mediate life cycle changes.  Non-transient JDO
42   * Instances always contain a non-null reference to an associated JDO
43   * <code>StateManager</code> instance.
44   *
45   * When a First Class Object is instantiated in the JVM, the JDO
46   * implementation assigns to fields with a Tracked Second Class Object
47   * type a new instance that tracks changes made to itself, and
48   * notifies the <code>StateManager</code> of the owning First Class Object
49   * of the change.
50   */
51  public interface StateManager
52  {
53      static final byte LOAD_REQUIRED  = (byte)1;
54  
55      static final byte READ_OK        = (byte)-1;
56  
57      static final byte READ_WRITE_OK  = (byte)0;
58  
59  
60      /**
61       * The <code>PersistenceManager</code> needs to call this method
62       * in order to make an instance persistent.
63       */
64      void makePersistent(PersistenceManager pm, Object   pc);
65  
66      /**
67       * ...
68       *
69       * The <code>PersistenceManager</code> calls this method to delete
70       * a persistent instance.
71       */
72      void deletePersistent();
73  
74      /**
75       * ...
76       *
77       * The <code>PersistenceManager</code> calls this method to flush
78       * changes made to the <code>StateManager</code> to the database.
79       * The specified StateManager argument is used to determine whether the
80       * actual instance should be flushed immediately or whether batch update
81       * is possible.
82       */
83      void updatePersistent(StateManager next);
84  
85      /**
86       * ...
87       *
88       * The <code>PersistenceManager</code> calls this method to refresh
89       * the state of the <code>StateManager</code> from the database.
90       */
91      void refreshPersistent();
92  
93      /**
94       *  ...
95       *
96       * The <code>PersistenceManager</code> calls this method to inform
97       * the <code>StateManager</code> that the transaction has been committed.
98       */
99      void commit(boolean retainValues);
100 
101 
102     /**
103      *  ...
104      *
105      * The <code>PersistenceManager</code> calls this method to inform
106      * the <code>StateManager</code> that the transaction has been rolled back.
107      */
108     void rollback(boolean retainValues);
109 
110     /**
111      *  ...
112      *
113      * The <code>PersistenceManager</code> calls this method to inform
114      * the <code>StateManager</code> that the flush processing is completed.
115      */
116     void flushed();
117 
118     /**
119      * ...
120      * The <code>PersistenceManager</code> calls this method to verify
121      * that corresponding object has been flushed to the database
122      */
123     boolean isProcessed();
124 
125     /**
126      * ...
127      */
128     void setPersistenceManager(com.sun.jdo.api.persistence.support.PersistenceManager pm);
129 
130     /**
131      * ...
132      */
133     com.sun.jdo.api.persistence.support.PersistenceManager getPersistenceManager();
134 
135     /**
136      * ...
137      */
138     com.sun.jdo.api.persistence.support.PersistenceManager getPersistenceManagerInternal();
139 
140     /**
141      * set actualImage associated with this <code>StateManager</code>
142      */
143     void setPersistent(Object   obj);
144 
145     /**
146      * get actualImage associated with this <code>StateManager</code>
147      */
148     Object   getPersistent();
149 
150     /**
151      * ...
152      */
153     void setObjectId(Object   objectId);
154 
155     /**
156      * ...
157      */
158     Object   getObjectId();
159 
160     /**
161      * ...
162      */
163     PersistenceConfig getPersistenceConfig();
164 
165     /**
166      * State initialization
167      * @param persistentInDB  true if object is persistent in DB
168      */
169     void initialize(boolean persistentInDB);
170 
171     /**
172      * ...
173      */
174     void makePresent(String   fieldName, Object   value);
175 
176     /**
177      * ...
178      */
179     void makeDirty(String   fieldName);
180 
181     /**
182      * ...
183      */
184     void applyUpdates(String   fieldName, SCOCollection c);
185 
186     /**
187      * ...
188      */
189     void replaceObjectField(String   fieldName, Object   o);
190 
191     /* The <code>PersistenceManager</code> calls this method to prepare
192      * a persistent object for update. This is required for
193      * foreign fields only as they could reference "regular" jdk
194      * Collections vs. SCO Collections. Such process has the side-effect of
195      * causing more objects to be registered with the transaction cache.
196      */
197     void prepareToUpdatePhaseI();
198 
199     /**
200      * This is the second phase of the commit processing. It populates phase3sms with all
201      * the autopersistence instances that are no longer reachable from a persistent instance.
202      */
203     void prepareToUpdatePhaseII(java.util.HashSet   phase3sms);
204 
205     /**
206      * This is the third phase of commit processing. It sets up the delete dependencies among
207      * all the autopersistent instances that have been flushed to the database.
208      */
209     void prepareToUpdatePhaseIII();
210 
211     /**
212      * ...
213      */
214     //@olsen: changed to return byte instead of void (->PC.jdoSetFlags())
215     byte setFlags(byte flags);
216 
217     /**
218      * ...
219      */
220     void loadForRead();
221 
222     /**
223      * ...
224      */
225     void loadForUpdate();
226 
227     //
228     // Status interrogation methods
229     //
230     // For each one of these methods, there is a corresponding version
231     // of it prefixed with jdo on the PersistenceCapable class. These
232     // methods are used to query the state o an instance. For example,
233     // when jdoIsReadReady is called on the PersistenceCapable
234     // instance, the generated <code>jdoIsReadReady</code> will delegate the
235     // status interrogation to the <code>StateManager</code> by call
236     // <code>isReadReady()</code>.
237     //
238 
239     /*
240      * ...
241      */
242     boolean isDirty();
243 
244     /**
245      * ...
246      */
247     boolean isTransactional();
248 
249     /**
250      * ...
251      */
252     boolean isNew();
253 
254     /**
255      * ...
256      */
257     boolean isDeleted();
258 
259     /**
260      * ...
261      */
262     boolean isPersistent();
263 
264     /**
265      * @return True, if this instance is persistent, transactional, not new,
266      * not dirty, and not deleted; false otherwise.
267      */
268     boolean needsRegisterWithVersionConsistencyCache();
269 
270     /**
271      * @return True, if this instance should be synchronized with
272      * the version consistency cache; false otherwise.
273      */
274     boolean needsUpdateInVersionConsistencyCache();
275 
276     //
277     // Getter and setter methods
278     //
279     // These are methods for accessing the persistent field values
280     // from the <code>StateManager</code>. The getter method can also serve
281     // as the hook for triggering dynamic navigation for fields that have not
282     // been fetched. The setter methods can also serve as the hook for
283     // keeping track of changes made to the <code>StateManager</code>.
284     //
285 
286     //@olsen: changed to use 'int' instead of 'short' as field number type
287     //@olsen: changed setter methods to return value instead of void
288     //@olsen: added method prepareGetField()
289 
290     void prepareGetField(int fieldID);
291 
292     boolean setBooleanField(int fieldNumber, boolean value);
293 
294     boolean[] setBooleanArrayField(int fieldNumber, boolean[] value);
295 
296     byte setByteField(int fieldNumber, byte value);
297 
298     byte[] setByteArrayField(int fieldNumber, byte[] value);
299 
300     short setShortField(int fieldNumber, short value);
301 
302     short[] setShortArrayField(int fieldNumber, short[] value);
303 
304     int setIntField(int fieldNumber, int value);
305 
306     int[] setIntArrayField(int fieldNumber, int[] value);
307 
308     long setLongField(int fieldNumber, long value);
309 
310     long[] setLongArrayField(int fieldNumber, long[] value);
311 
312     char setCharField(int fieldNumber, char value);
313 
314     char setCharArrayField(int fieldNumber, char value);
315 
316     float setFloatField(int fieldNumber, float value);
317 
318     float[] setFloatArrayField(int fieldNumber, float[] value);
319 
320     double setDoubleField(int fieldNumber, double value);
321 
322     double[] setDoubleArrayField(int fieldNumber, double[] value);
323 
324     String   setStringField(int fieldNumber, String   value);
325 
326     String  [] setStringArrayField(int fieldNumber, String  [] value);
327 
328     Object   setObjectField(int fieldNumber, Object   value);
329 
330     Object  [] setObjectArrayField(int fieldNumber, Object  [] value);
331 
332     /**
333      * Lock this instance. This method must be called the same
334      * number of times as #releaseLock().
335      */
336     void getLock();
337 
338     /**
339      * Release this instance. This method must be called the same
340      * number of times as #getLock().
341      */
342     void releaseLock();
343 
344     /**
345      * Returns value for a hidden field. This method expects index
346      * to be negative for hidden fields.
347      * @param index  - the hidden field index.
348      */
349     Object   getHiddenValue(int index);
350 
351     /**
352      * Sets value for a hidden field. This method expects index
353      * to be negative for hidden fields.
354      * @param index  - the hidden field index.
355      * @param value - new value.
356      */
357     void setHiddenValue(int index, Object   value);
358 
359     /**
360      * Marks field with this index as present.
361      * @param index - the field number.
362      */
363      void setPresenceMaskBit(int index) ;
364 
365     /**
366      * Returns true if field with this index is present in the instance.
367      */
368     boolean getPresenceMaskBit(int index);
369 
370     /**
371      * Notifies the StateManager that this instance needs to be registered
372      * with the global (weak) cache at rollback if it transitions to persistent
373      * state.
374      * Used for replacing a deleted instance with the newly persistent with
375      * the same object id.
376      */
377     void markNotRegistered();
378 
379     /**
380      * Notifies the StateManager that this instance needs to be verified at
381      * the time it is removed from the global (weak) cache at rollback if it
382      * transitions to transient state.
383      */
384     void markVerifyAtDeregister();
385 
386     /**
387      * Adds another StateManager to this StateManager dependencies list.
388      * @param sm the StateManager to add.
389      */
390     void addDependency(StateManager sm);
391 
392     /**
393      * Tries to resolve the dependencies for all instances waiting for the
394      * current state manager to be flushed to the store.
395      */
396     void resolveDependencies();
397 
398     /**
399      * Notifies the StateManager that this instance is a replacement for a
400      * deleted instance with the same ObjectId.
401      */
402     void markReplacement();
403 
404     /**
405      * Release references in the StateManager to the persistent instance,
406      * ObjectId, and PersistenceManager.
407      */
408     void release();
409 
410     /** Returns true if this StateManager is valid for use.
411      * The <code>valid</code> flag is initially set to false and changed to true
412      * when the first operation (e.g. makePersistent(), loadForRead(), or
413      * PersistenceManager.getObjectById()) succeeds.
414      */
415     boolean isValid();
416 
417     /** Mark this StateManager as valid. Called before returning from
418      * getObjectById. Flag is set to true internally in the StateManager
419      * at makePersistent(), or initialize(true) (to be used for storing
420      * query or navigation results.
421      */
422     void setValid();
423 
424     /** Reload the instance associated with this StateManager. Called by
425      * {@link PersistenceManager#getObjectById(Object, boolean)
426      * PersistenceManager.getObjectById(Object, boolean)} with validate
427      * flag set to <code>true</code>
428      */
429     void reload();
430 
431     /**
432      * Returns true, if the managed instance has Version Consistency.
433      * @return  True, if the managed object has Version Consistency.
434      */
435     boolean hasVersionConsistency();
436 
437     /**
438      * Copies field values from <code>source</code> to this
439      * StateManager's fields.
440      * @param source StateManager from which field values are
441      * copied into this instance.
442      */
443     void copyFields(StateManager source);
444 
445     /**
446      * Verify that an instance set up with Version consistency is not modified
447      * in a parallel transaction.
448      * @return false if the instance is persistent clean and modified by a
449      * parallel transaction, true otherwise.
450      */
451     boolean verifyPersistent();
452 
453     /**
454      * Marks that this state manager has failed version consistency
455      * validation.
456      */
457     void setVerificationFailed();
458 
459     /**
460      * Returns, if this state manager has failed version consistency
461      * validation.
462      *
463      * @return True, if this state manager is marked as failed.
464      */
465     boolean isVerificationFailed();
466 }
467
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags