PersistenceManager


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  /*
25   * PersistenceManager.java
26   *
27   * Create on March 3, 2000
28   */
29  
30  package com.sun.jdo.spi.persistence.support.sqlstore;
31  
32  import com.sun.jdo.spi.persistence.support.sqlstore.impl.PersistenceManagerWrapper;
33  
34  /**
35   */
36  public interface PersistenceManager
37          extends com.sun.jdo.api.persistence.support.PersistenceManager
38  {
39          public PersistenceManagerWrapper getCurrentWrapper();
40  
41          public Object   newInstance(StateManager sm);
42  
43          public void setStateManager(Object   pc, StateManager sm);
44  
45          public void setFlags(Object   pc, byte flags);
46  
47          public byte getFlags(Object   pc);
48  
49          public StateManager getStateManager(Object   pc);
50  
51          public void setField(Object   pc, int fieldNumber, Object   value);
52  
53          public Object   getField(Object   pc, int fieldNumber);
54  
55          public void clearFields(Object   pc);
56  
57          /**
58           * Executes the given retrieve descriptor. The result
59           * is a collection unless an aggregate query was specified.
60           * In most cases the query result is a collection of
61           * persistent objects. In case of a projection
62           * on a local field the collection holds objects of that
63           * type. For aggregate queries the result is a
64           * single object, which type was defined by the caller.
65           *
66           * @param action The retrieve descriptor.
67           * @param parameters The input parameters for the query.
68           * @return A collection of (persistent) objects unless
69           * an aggregate query was specified.
70           */
71          public Object   retrieve(RetrieveDesc action, ValueFetcher parameters);
72  
73          /**
74           * Executes the given retrieve descriptor. The result
75           * is a collection unless an aggregate query was specified.
76           * In most cases the query result is a collection of
77           * persistent objects. In case of a projection
78           * on a local field the collection holds objects of that
79           * type. For aggregate queries the result is a
80           * single object, which type was defined by the caller.
81           *
82           * @param action The retrieve descriptor.
83           * @return A collection of (persistent) objects unless
84           * an aggregate query was specified.
85           */
86          public Object   retrieve(RetrieveDesc action);
87  
88          /**
89           * Return a RetrieveDesc given a Class object.
90           */
91          public RetrieveDesc getRetrieveDesc(Class   classType);
92  
93          /**
94           * Return a RetrieveDesc for a foreign field (relationship) given the
95           * Class object for the parent class.
96           */
97          public RetrieveDesc getRetrieveDesc(String   fieldName, Class   classType);
98  
99          /**
100          * Called by Transaction commit() or rollback()
101          * cleans up transactional cache
102          * @param       status      javax.transaction.Status
103          */
104         public void afterCompletion(int status);
105 
106         /**
107          * Called by Transaction commit()
108          * Loops through transactional cache and calls PersistentStore.updatePersistent()
109          * on each instance
110          */
111         public void beforeCompletion();
112 
113         /**
114          * Called by Query in pessimistic transaction
115          * to flush changes to the database
116          */
117         public void internalFlush();
118 
119         /**
120          * Called by StateManager to register new instance. This method will throw
121          * an JDOUserException if throwDuplicateException is true and the object being
122          * registered already exists in the pm cache.
123          */
124         public void registerInstance(StateManager sm, Object   oid,
125              boolean throwDuplicateException, boolean forceRegister);
126 
127         /**
128          * Called by StateManager to register persistent instance at the rollback if
129          * it was removed from the global (weak) cache as the result of the replace
130          * operation.
131          */
132         public void registerInstance(StateManager sm, Object   oid);
133 
134         /**
135          * Deregister an instance.
136          */
137         public void deregisterInstance(Object   oid);
138 
139         /**
140          * Deregister an instance with this object Id, only if it holds the same instance.
141          */
142         public void deregisterInstance(Object   oid, StateManager sm);
143 
144         /**
145          * For Transaction to notify PersistenceManager that
146          * status is changed
147          */
148         public void notifyStatusChange(boolean isActive);
149 
150         /**
151          * For Transaction to notify PersistenceManager that
152          * optimistic flag is changed
153          */
154         public void notifyOptimistic(boolean optimistic);
155 
156         /**
157          * Returns true if associated transaction is optimistic
158          */
159         public boolean isOptimisticTransaction();
160 
161         /**
162          * For Transaction to notify PersistenceManager that
163          * optimistic flag is changed
164          */
165         public void notifyNontransactionalRead(boolean nontransactionalRead);
166 
167         /**
168          * Returns true if nontransactionalRead flag is set to true.
169          */
170         public boolean isNontransactionalRead();
171 
172         /**
173          * Returns true if associated transaction is active
174          */
175         public boolean isActiveTransaction();
176 
177         /**
178          * Called by newSCOInstance from the public interface or internally
179          * by the runtime
180          * Will not result in marking field as dirty
181          *
182          * Returns a new Second Class Object instance of the type specified,
183          * @param type Class of the new SCO instance
184          * @param owner the owner to notify upon changes
185          * @param fieldName the field to notify upon changes
186          * @return the object of the class type
187          */
188         public Object   newSCOInstanceInternal (Class   type, Object   owner, String   fieldName);
189 
190         /**
191          * Called by newCollectionInstance from the public interface
192          * or internally by the runtime
193          * Will not result in marking field as dirty
194          *
195          * @param type Class of the new SCO instance
196          * @param owner the owner to notify upon changes
197          * @param fieldName the field to notify upon changes
198          * @param elementType the element types allowed
199          * @param allowNulls true if allowed
200          * @param initialSize initial size of the Collection
201          * @return the object of the class type
202          */
203     Object   newCollectionInstanceInternal (Class   type, Object   owner, String   fieldName,
204                 Class   elementType, boolean allowNulls, int initialSize);
205 
206         /**
207          * Serialize field updates
208          */
209         public void acquireFieldUpdateLock();
210 
211         /**
212          * Allow other threads to update fields
213          */
214         public void releaseFieldUpdateLock();
215 
216         /**
217      * Acquires a share lock from the persistence manager. This method will
218      * put the calling thread to sleep if another thread is holding the exclusive lock.
219          */
220         public void acquireShareLock();
221 
222         /**
223      * Releases the share lock and notify any thread waiting to get an exclusive lock.
224          * Note that every releaseShareLock() call needs to be preceeded by an acquireShareLock() call.
225          */
226         public void releaseShareLock();
227 
228         /**
229      * Acquires an exclusive lock from the persistence manager. By acquiring an
230          * exclusive lock, a thread is guaranteed to have exclusive right to the persistence
231      * runtime meaning no other threads can perform any operation in the runtime.
232          */
233         public void acquireExclusiveLock();
234 
235         /**
236      * Release the exclusive lock and notify any thread waiting to get an exclusive or
237          * share lock. Note that every releaseShareLock() call needs to be preceeded by
238          * an acquireExclusiveLock() call.
239          */
240         public void releaseExclusiveLock();
241 
242     /**
243      * Force to close the persistence manager. Called by
244      * TransactionImpl.afterCompletion in case of the CMT transaction
245      * and the status value passed to the method cannot be resolved.
246      */
247     public void forceClose();
248 
249     /**
250      * Returns StateManager instance for this Object Id.
251      * @param oid the ObjectId to look up.
252      * @param pcClass the expected Class type of the new PC instance.
253      */
254     public StateManager findOrCreateStateManager(Object   oid, Class   pcClass);
255 
256     /**
257      * Lock cache for getObjectById and result processing synchronization.
258      */
259     public void acquireCacheLock();
260 
261     /** Release cache lock.
262      */
263     public void releaseCacheLock();
264 
265     /**
266      * Looks up the given instance in the Version Consistency cache and
267      * if found, populates it from the cached values.
268      * @param sm Instance to be looked up in the version consistency cache.
269      * If found, it is populated with values from the cache.
270      * @return true if the <code>sm</code> was found and populated, false
271      * otherwise.
272      */
273     public boolean initializeFromVersionConsistencyCache(StateManager sm);
274 
275 }
276
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags