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   * Created on February 25, 2000
28   */
29   
30  package com.sun.jdo.api.persistence.support;
31  import java.util.Collection  ;
32  import java.util.Properties  ;
33  import java.lang.Class  ;
34  
35  /** PersistenceManager is the primary interface for JDO-aware application
36   * components.  It is the factory for Query and Transaction instances,
37   * and contains methods to manage the life cycle of PersistenceCapable
38   * instances.
39   *
40   * <P>A PersistenceManager is obtained from the
41   * {@link PersistenceManagerFactory}
42   * (recommended) or by construction.
43   * @author Craig Russell
44   * @version 0.1
45   */
46  
47  public interface PersistenceManager 
48  {
49      /** A PersistenceManager instance can be used until it is closed.
50     * @return if this PersistenceManager has been closed
51     * @see #close()
52     */
53    boolean isClosed();
54      /** A PersistenceManager instance can be used until it is closed.
55       *
56       * <P>This method closes the PersistenceManager, which if pooled, releases it
57       * to the pool of available PersistenceManagers.
58       */
59      void close();
60  
61      /** There is exactly one Transaction associated with a PersistenceManager.
62       * @return the Transaction associated with this
63       * PersistenceManager.
64       */
65      Transaction currentTransaction();
66  
67      /** Create a new Query with no elements.
68       * @return a new Query instance with no elements.
69       */
70      Query newQuery();
71      /** Create a new Query using elements from another Query.  The other Query
72       * must have been created by the same JDO implementation.  It might be active
73       * in a different PersistenceManager or might have been serialized and
74       * restored.
75       * @return the new Query
76       * @param compiled another Query from the same JDO implementation
77       */
78      Query newQuery(Object   compiled);
79      
80      /** Create a new Query specifying the Class of the candidate instances.
81       * @param cls the Class of the candidate instances
82       * @return the new Query
83       */
84      Query newQuery(Class   cls);
85      
86      /** Create a new Query with the Class of the candidate instances and candidate Collection.
87       * specified.
88       * @param cls the Class of the candidate instances
89       * @param cln the Collection of candidate instances
90       * @return the new Query
91       */
92      Query newQuery(Class   cls,Collection   cln);
93      
94      /** Create a new Query with the Class of the candidate instances and Filter.
95       * specified.
96       * @param cls the Class of the candidate instances
97       * @param filter the Filter for candidate instances
98       * @return the new Query
99       */
100     Query newQuery (Class   cls, String   filter);
101     
102     /** Create a new Query with the Class of the candidate instances, candidate Collection,
103      * and Filter.
104      * @param cls the Class of the candidate instances
105      * @param cln the Collection of candidate instances
106      * @param filter the Filter for candidate instances
107      * @return the new Query
108      */
109     Query newQuery (Class   cls, Collection   cln, String   filter);
110     
111     /** The PersistenceManager may manage a collection of instances in the data
112      * store based on the class of the instances.  This method returns a
113      * Collection of instances in the data store that might be iterated or
114      * given to a Query as the Collection of candidate instances.
115      * @param persistenceCapableClass Class of instances
116      * @param subclasses whether to include instances of subclasses
117      * @return a Collection of instances
118      * @see Query
119      */
120     Collection   getExtent(Class   persistenceCapableClass,boolean subclasses);
121 
122     /** This method locates a persistent instance in the cache of instances
123      * managed by this PersistenceManager.  If an instance with the same ObjectId
124      * is found it is returned.  Otherwise, a new instance is created and
125      * associated with the ObjectId.
126      *
127      * <P>If the instance does not exist in the data store, then this method will
128      * not fail.  However, a request to access fields of the instance will
129      * throw an exception.
130      * @param oid an ObjectId
131      * @return the PersistenceCapable instance with the specified
132      * ObjectId
133      */
134     Object   getObjectById(Object   oid);
135     
136     /** The ObjectId returned by this method represents the JDO identity of
137      * the instance.  The ObjectId is a copy (clone) of the internal state
138      * of the instance, and changing it does not affect the JDO identity of
139      * the instance.
140      * @param pc the PersistenceCapable instance
141      * @return the ObjectId of the instance
142      */
143     Object   getObjectId(Object   pc);
144     
145     /** This method is used to get a PersistenceCapable instance
146      * representing the same data store object as the parameter, that is valid
147      * for this PersistenceManager.
148      * @param pc a PersistenceCapable instance
149      * @return the PersistenceCapable instance representing the
150      * same data store object
151      */
152     Object   getTransactionalInstance(Object   pc);
153     
154     /** Make the transient instance persistent in this PersistenceManager.
155      * This method must be called in an active transaction.
156      * The PersistenceManager assigns an ObjectId to the instance and
157      * transitions it to persistent-new.
158      * The instance will be managed in the Extent associated with its Class.
159      * The instance will be put into the data store at commit.
160      * @param pc a transient instance of a Class that implements
161      * PersistenceCapable
162      */
163     void makePersistent(Object   pc);
164     
165     /** Make an array of instances persistent.
166      * @param pcs an array of transient instances
167      * @see #makePersistent(Object pc)
168      */
169     void makePersistent(Object  [] pcs);
170     
171     /** Make a Collection of instances persistent.
172      * @param pcs a Collection of transient instances
173      * @see #makePersistent(Object pc)
174      */
175     void makePersistent (Collection   pcs);
176     
177     /** Delete the persistent instance from the data store.
178      * This method must be called in an active transaction.
179      * The data store object will be removed at commit.
180      * Unlike makePersistent, which makes the closure of the instance persistent,
181      * the closure of the instance is not deleted from the data store.
182      * This method has no effect if the instance is already deleted in the
183      * current transaction.
184      * This method throws an exception if the instance is transient or is managed by another
185      * PersistenceManager.
186      *
187      * @param pc a persistent instance
188      */
189     void deletePersistent(Object   pc);
190     
191     /** Delete an array of instances from the data store.
192      * @param pcs a Collection of persistent instances
193      * @see #deletePersistent(Object pc)
194      */
195     void deletePersistent (Object  [] pcs);
196     
197     /** Delete a Collection of instances from the data store.
198      * @param pcs a Collection of persistent instances
199      * @see #deletePersistent(Object pc)
200      */
201     void deletePersistent (Collection   pcs);
202     
203     /** This method returns the PersistenceManagerFactory used to create
204      * this PersistenceManager.  It returns null if this instance was
205      * created via a constructor.
206      * @return the PersistenceManagerFactory that created
207      * this PersistenceManager
208      */
209     PersistenceManagerFactory getPersistenceManagerFactory();
210     
211     /** The application can manage the PersistenceManager instances
212      * more easily by having an application object associated with each
213      * PersistenceManager instance.
214      * @param o the user instance to be remembered by the PersistenceManager
215      * @see #getUserObject
216      */
217     void setUserObject(Object   o);
218     
219     /** The application can manage the PersistenceManager instances
220      * more easily by having an application object associated with each
221      * PersistenceManager instance.
222      * @return the user object associated with this PersistenceManager
223      * @see #setUserObject
224      */
225     Object   getUserObject();
226     
227     /** The JDO vendor might store certain non-operational properties and
228      * make those properties available to applications (for troubleshooting).
229      *
230      * <P>Standard properties include:
231      * <li>VendorName</li>
232      * <li>VersionNumber</li>
233      * @return the Properties of this PersistenceManager
234      */
235     Properties   getProperties();
236     
237     /** In order for the application to construct instance of the ObjectId class
238      * it needs to know the class being used by the JDO implementation.
239      * @param cls the PersistenceCapable Class
240      * @return the Class of the ObjectId of the parameter
241      */
242     Class   getObjectIdClass(Class   cls);
243 
244 
245     /**
246      * Returns a new Second Class Object instance of the type specified, 
247      * with the owner and field name to notify upon changes to the value 
248      * of any of its fields. If a collection class is created, then the 
249      * class does not restrict the element types, and allows nulls to be added as elements.
250      *
251      * @param type Class of the new SCO instance
252      * @param owner the owner to notify upon changes
253      * @param fieldName the field to notify upon changes 
254      * @return the object of the class type
255      */
256     Object   newSCOInstance (Class   type, Object   owner, String   fieldName);
257 
258 
259     /**  
260      * Returns a new Collection instance of the type specified, with the 
261      * owner and field name to notify upon changes to the value of any of its fields. 
262      * The collection class restricts the element types allowed to the elementType or 
263      * instances assignable to the elementType, and allows nulls to be added as 
264      * elements based on the setting of allowNulls. The Collection has an initial size 
265      * as specified by the initialSize parameter.
266      *
267      * @param type Class of the new SCO instance 
268      * @param owner the owner to notify upon changes 
269      * @param fieldName the field to notify upon changes  
270      * @param elementType the element types allowed
271      * @param allowNulls true if allowed
272      * @param initialSize initial size of the Collection
273      * @return the object of the class type 
274      */  
275     Object   newCollectionInstance (Class   type, Object   owner, String   fieldName, 
276         Class   elementType, boolean allowNulls, int initialSize);
277 
278 
279     /** This method locates a persistent instance in the cache of instances
280      * managed by this <code>PersistenceManager</code>.
281      * The <code>getObjectById</code> method attempts
282      * to find an instance in the cache with the specified JDO identity.
283      * The <code>oid</code> parameter object might have been returned by an earlier call
284      * to <code>getObjectId</code> or might have been constructed by the application.
285      * <P>If the <code>PersistenceManager</code> is unable to resolve the <code>oid</code> parameter
286      * to an ObjectId instance, then it throws a <code>JDOUserException</code>.
287      * <P>If the <code>validate</code> flag is <code>false</code>, and there is already an instance in the
288      * cache with the same JDO identity as the <code>oid</code> parameter, then this method
289      * returns it. There is no change made to the state of the returned
290      * instance.
291      * <P>If there is not an instance already in the cache with the same JDO
292      * identity as the <code>oid</code> parameter, then this method creates an instance
293      * with the specified JDO identity and returns it. If there is no
294      * transaction in progress, the returned instance will be hollow or
295      * persistent-nontransactional, at the choice of the implementation.
296      * <P>If there is a transaction in progress, the returned instance will
297      * be hollow, persistent-nontransactional, or persistent-clean, at the
298      * choice of the implementation.
299      * <P>It is an implementation decision whether to access the data store,
300      * if required to determine the exact class. This will be the case of
301      * inheritance, where multiple <code>PersistenceCapable</code> classes share the
302      * same ObjectId class.
303      * <P>If the validate flag is <code>false</code>, and the instance does not exist in
304      * the data store, then this method might not fail. It is an
305      * implementation choice whether to fail immediately with a
306      * <code>JDODataStoreException</code>. But a subsequent access of the fields of the
307      * instance will throw a <code>JDODataStoreException</code> if the instance does not
308      * exist at that time. Further, if a relationship is established to this
309      * instance, then the transaction in which the association was made will
310      * fail.
311      * <P>If the <code>validate</code> flag is <code>true</code>, and there is already a transactional
312      * instance in the cache with the same JDO identity as the <code>oid</code> parameter,
313      * then this method returns it. There is no change made to the state of
314      * the returned instance.
315      * <P>If there is an instance already in the cache with the same JDO
316      * identity as the <code>oid</code> parameter, but the instance is not transactional,
317      * then it must be verified in the data store. If the instance does not
318      * exist in the datastore, then a <code>JDODataStoreException</code> is thrown.
319      * <P>If there is not an instance already in the cache with the same JDO
320      * identity as the <code>oid</code> parameter, then this method creates an instance
321      * with the specified JDO identity, verifies that it exists in the data
322      * store, and returns it. If there is no transaction in progress, the
323      * returned instance will be hollow or persistent-nontransactional,
324      * at the choice of the implementation.
325      * <P>If there is a data store transaction in progress, the returned
326      * instance will be persistent-clean.
327      * If there is an optimistic transaction in progress, the returned
328      * instance will be persistent-nontransactional.
329      * @see #getObjectId(Object pc)
330      * @see #getObjectById(Object oid)
331      * @return the <code>PersistenceCapable</code> instance with the specified ObjectId
332      * @param oid an ObjectId
333      * @param validate if the existence of the instance is to be validated
334      */
335     Object   getObjectById (Object   oid, boolean validate);
336 
337     /**
338      * Returns the boolean value of the supersedeDeletedInstance flag
339      * for this PersistenceManager. If set to true, deleted instances are
340      * allowed to be replaced with persistent-new instances with the equal
341      * Object Id.
342      * @return      boolean supersedeDeletedInstance flag
343      */
344     boolean getSupersedeDeletedInstance ();
345   
346   
347     /**
348      * Sets the supersedeDeletedInstance flag for this PersistenceManager.
349      * @param flag          boolean supersedeDeletedInstance flag
350      */
351     void setSupersedeDeletedInstance (boolean flag);
352 
353     /**
354      * Returns the boolean value of the requireCopyObjectId flag
355      * for this PersistenceManager. If set to false, the PersistenceManager
356      * does not create a copy of an ObjectId for <code>PersistenceManager.getObjectId(Object pc)</code>
357      * and <code>PersistenceManager.getObjectById(Object oid)</code> requests.
358      *
359      * @see #getObjectId(Object pc)
360      * @see #getObjectById(Object oid)
361      * @return      boolean requireCopyObjectId flag
362      */
363     boolean getRequireCopyObjectId();
364 
365 
366     /**
367      * Sets the requireCopyObjectId flag for this PersistenceManager.
368      * If set to false, the PersistenceManager will not create a copy of
369      * an ObjectId for <code>PersistenceManager.getObjectId(Object pc)</code>
370      * and <code>PersistenceManager.getObjectById(Object oid)</code> requests.
371      *
372      * @see #getObjectId(Object pc)
373      * @see #getObjectById(Object oid)
374      * @param flag          boolean requireCopyObjectId flag
375      */
376     void setRequireCopyObjectId (boolean flag);
377 
378     /**
379      * Returns the boolean value of the requireTrackedSCO flag
380      * for this PersistenceManager. If set to false, the PersistenceManager
381      * will not create tracked SCO instances for new persistent instances at 
382      * commit with retainValues set to true and while retrieving data from a datastore. 
383      *    
384      * @return      boolean requireTrackedSCO flag
385      */  
386     boolean getRequireTrackedSCO();
387 
388     /**
389      * Sets the requireTrackedSCO flag for this PersistenceManager.
390      * If set to false, the PersistenceManager will not create tracked
391      * SCO instances for new persistent instances at commit with retainValues 
392      * set to true and while retrieving data from a datastore.
393      *   
394      * @param flag          boolean requireTrackedSCO flag
395      */  
396     void setRequireTrackedSCO (boolean flag);
397 
398     }
399
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags