VersantPersistenceManager


1   
2   /*
3    * Copyright (c) 1998 - 2005 Versant Corporation
4    * All rights reserved. This program and the accompanying materials
5    * are made available under the terms of the Eclipse Public License v1.0
6    * which accompanies this distribution, and is available at
7    * http://www.eclipse.org/legal/epl-v10.html
8    *
9    * Contributors:
10   * Versant Corporation - initial API and implementation
11   */
12  package com.versant.core.jdo;
13  
14  import javax.jdo.PersistenceManager;
15  import javax.jdo.Query;
16  import java.sql.Connection  ;
17  import java.util.Collection  ;
18  import java.util.List  ;
19  
20  /**
21   * JDO Genie extension of the standard JDO PersistenceManager interface.
22   */
23  public interface VersantPersistenceManager extends PersistenceManager {
24  
25      /**
26       * Do not lock any objects in datastore tx.
27       */
28      public static final int LOCKING_NONE = 1;
29      /**
30       * Lock only the first object navigated or fetched in datastore tx.
31       */
32      public static final int LOCKING_FIRST = 2;
33      /**
34       * Lock all objects in datastore tx (not fully supported on all db's).
35       */
36      public static final int LOCKING_ALL = 3;
37  
38      public static final int EVENT_ERRORS = VersantPersistenceManagerFactory.EVENT_ERRORS;
39      public static final int EVENT_NORMAL = VersantPersistenceManagerFactory.EVENT_NORMAL;
40      public static final int EVENT_VERBOSE = VersantPersistenceManagerFactory.EVENT_VERBOSE;
41      public static final int EVENT_ALL = VersantPersistenceManagerFactory.EVENT_ALL;
42  
43      /**
44       * Use strong references to instances in the local PM cache. *
45       */
46      public final static int PM_CACHE_REF_TYPE_STRONG = 1;
47      /**
48       * Use soft references to instances in the local PM cache. *
49       */
50      public final static int PM_CACHE_REF_TYPE_SOFT = 2;
51      /**
52       * Use weak references to instances in the local PM cache. *
53       */
54      public final static int PM_CACHE_REF_TYPE_WEAK = 3;
55  
56      /**
57       * If this flag is true then access to default fetch group fields loaded
58       * into an instance is intercepted. See the "Cache Management" chapter of
59       * the manual for more information on this flag.
60       */
61      public boolean isInterceptDfgFieldAccess();
62  
63      /**
64       * Control the interception of access to default fetch group fields loaded
65       * into an instance. See the "Cache Management" chapter of the manual
66       * for more information on this flag.
67       */
68      public void setInterceptDfgFieldAccess(boolean interceptDfgFieldAccess);
69  
70      /**
71       * This will cancel the last exectuted query.
72       */
73      public void cancelQueryExecution();
74  
75      /**
76       * Does the current transaction contain any dirty instances?
77       */
78      public boolean isDirty();
79  
80      /**
81       * Utility method to return an datastore identity instance by the String
82       * value that was returned from the id of the instance. This avoids having
83       * to obtain the identity class for an Object and then via reflection
84       * creating an instance of the id and asking the pm for the pc instance
85       * by the id instance.
86       */
87      public Object   getObjectByIDString(String   value, boolean toValidate);
88  
89      /**
90       * <p>This method returns an OID instance for the given class and String.
91       * If the String is for a datastore identity class then the pcClass
92       * parameter may be null. Calling this method with resolved true is
93       * equivalent to calling {@link #newObjectIdInstance(Class, String) }.</p>
94       * <p/>
95       * <p>If resolved is false then the String may be for a superclass of the
96       * actual class. For datastore identity classes this is only possible if
97       * you have constructed the String yourself from the class ID of the base
98       * class and the primary key of the instance.</p>
99       *
100      * @see #getObjectByIDString(String, boolean)
101      */
102     public Object   newObjectIdInstance(Class   pcClass, String   str,
103             boolean resolved);
104 
105     /**
106      * <p>This method returns an instance of any datastore identity class
107      * from the toString of its OID. Calling this method with resolved true is
108      * equivalent to calling {@link #getObjectByIDString(String, boolean) }.</p>
109      * <p/>
110      * <p>If resolved is false then the String may be for a superclass of the
111      * actual class. This is only possible if you have constructed the String
112      * yourself from the class ID of the base class and the primary key of the
113      * instance.</p>
114      *
115      * @see #newObjectIdInstance(Class, String, boolean)
116      */
117     public Object   getObjectByIDString(String   value, boolean toValidate,
118             boolean resolved);
119 
120     /**
121      * Loads the fetch group fields for the already managed instance.
122      *
123      * @param pc   The PersistenceCapable instance for which to load the fields
124      * @param name The name of the fetch group
125      */
126     public void loadFetchGroup(Object   pc, String   name);
127 
128     /**
129      * This is typically used in operations where there is not enough memory
130      * available on the client to managed the transaction's dirty instances.
131      * <p/>
132      * Flush all dirty and new instances to the database and evict all
133      * instances from the local cache. This allows unreferenced instances to
134      * be garbage collected making it easier to write loops that update
135      * millions of instances in a single transaction.<p>
136      *
137      * @see #flush(boolean)
138      * @see #evictAll()
139      */
140     public void flush();
141 
142     /**
143      * Flush all dirty and new instances to the database.<p>
144      * <p/>
145      * If retainValues is false then refer to {@link #flush()}.
146      * <p/>
147      * If the PM is not currently associated with any JDBC connection
148      * (i.e. it is using optimistic transactions) then the connection used
149      * to do the flush is pinned to the PM and used for all subsequent
150      * operations. This is very similar to a PM using datastore transactions.<p>
151      * <p/>
152      * This is used typically when you want to see the changes made in the pm when
153      * direct sql is used.
154      *
155      * @see #getJdbcConnection(java.lang.String)
156      * @see #flush()
157      */
158     public void flush(boolean retainValues);
159 
160     /**
161      * Obtain the JDBC connection associated with the PM for the datastore. If
162      * the datastore name is null then the connection for the default datastore
163      * is returned. If the PM is not currently associated with any connection
164      * (i.e. it is using optimistic transactions) then the connection returned
165      * is pinned to the PM and used for all subsequent operations. This is very
166      * similar to a PM using datastore transactions.<p>
167      * <p/>
168      * An exception is thrown if any transaction related methods are called on
169      * the connection (commit, rollback, setAutoCommit). The JDO API must be
170      * used for transaction control (pm.currentTransation().commit() etc.).
171      * The returned connection has autoCommit set to false and is a proxy
172      * for the real connection. This method may only be called inside a JDO
173      * transaction.<p>
174      * <p/>
175      * The connection is pinned to the PM until commit or rollback of the
176      * current JDO transaction. Once commit or rollback has been done it will
177      * be returned to the pool and the proxy is automatically closed. You
178      * can call close on the proxy but this does not close the underlying
179      * JDBC connection and it remains pinned to the PM.<p>
180      * <p/>
181      * If JDBC event logging is on then operations on the connection will be
182      * logged. This method is not available to remote clients and a
183      * JDOUserException is thrown if it is called by a remote client or if
184      * the datastore does not exist.<p>
185      *
186      * @see VersantPersistenceManagerFactory#getJdbcConnection
187      */
188     public Connection   getJdbcConnection(String   datastore);
189 
190     /**
191      * Obtain the URL for the datastore. If the datastore name is null then
192      * the URL for the default datastore is returned.
193      */
194     public String   getConnectionURL(String   dataStore);
195 
196     /**
197      * Obtain the driver name for the datastore. If the datastore name is null
198      * then the driver name for the default datastore is returned.
199      */
200     public String   getConnectionDriverName(String   dataStore);
201 
202     /**
203      * This will recursively make all pc fields that is loaded transient.
204      */
205     public void makeTransientRecursive(Object   pc);
206 
207     /**
208      * This will return all the dirty instances in the current transaction. If
209      * there are no dirty instance then an empty list is returned.
210      */
211     public List   versantAllDirtyInstances();
212 
213     /**
214      * Set the locking mode for datastore transactions. You can set the
215      * default value for this property using the Workbench or edit your
216      * properties file directly (versant.datastoreTxLocking property). This
217      * method may be called at any time. If called inside a transaction it
218      * changes the mode for future SQL. The default setting is LOCKING_FIRST.
219      *
220      * @see #LOCKING_NONE
221      * @see #LOCKING_FIRST
222      * @see #LOCKING_ALL
223      */
224     public void setDatastoreTxLocking(int mode);
225 
226     /**
227      * Get the locking mode for datastore transactions.
228      */
229     public int getDatastoreTxLocking();
230 
231     /**
232      * Return the instance for oid if it is present in the local PM cache
233      * otherwise return null. Note that the instance might still be hollow
234      * and touching its fields will cause a fetch from the level 2 cache
235      * or database.
236      *
237      * @see #isHollow(Object)
238      */
239     public Object   getObjectByIdFromCache(Object   oid);
240 
241     /**
242      * Is the instance hollow? Hollow instances are managed but their fields
243      * have not been loaded from the level 2 cache or database.
244      *
245      * @see #getObjectByIdFromCache(Object)
246      */
247     public boolean isHollow(Object   pc);
248 
249     /**
250      * Does the instance have an identity? New instances are only assigned
251      * an identity on commit or flush or when the application executes an
252      * operation that requires the identity.
253      */
254     public boolean hasIdentity(Object   pc);
255 
256     /**
257      * Log a user defined event. If the event logging level does not match
258      * the level parameter then the event is ignored. For remote PMs this
259      * check is done on the server so a network call is required even if the
260      * event is not logged.
261      *
262      * @see #EVENT_ERRORS
263      * @see #EVENT_NORMAL
264      * @see #EVENT_VERBOSE
265      * @see #EVENT_ALL
266      */
267     public void logEvent(int level, String   description, int ms);
268 
269     /**
270      * This util method is used by collection types to preload their pc
271      * entries. It tests to determine if the states refered to by the oids is
272      * in the managed cache. If not they must be bulk loaded from server.
273      * The scenario in which this is likely to happen is when the collection
274      * is not in the default fetch group and the state is in cache with the
275      * collection filled in. If this collection field is read then the
276      * pcstateman will determine that the stateField is filled and hence not
277      * ask the server for it.
278      */
279     public int getObjectsById(Object  [] oids, int length, Object  [] data,
280             int stateFieldNo, int classMetaDataIndex);
281 
282     /**
283      * Construct a new query instance with the given candidate class from a
284      * named query. The query name given must be the name of a query defined
285      * in metadata. The metadata is searched for the specified name.
286      * This is a JDO 2 preview feature.
287      */
288     public Query versantNewNamedQuery(Class   cls, String   queryName);
289 
290     /**
291      * This method makes detached copies of the parameter instances and returns
292      * the copies as the result of the method. The order of instances in the
293      * parameter Collection's iteration corresponds to the order of corresponding
294      * instances in the returned Collection's iteration.
295      * <p/>
296      * The Collection of instances is first made persistent, and the reachability
297      * algorithm is run on the instances. This ensures that the closure of all
298      * of the instances in the the parameter Collection is persistent.
299      * <p/>
300      * For each instance in the parameter Collection, a corresponding detached
301      * copy is created. Each field in the persistent instance is handled based on
302      * its type and whether the field is contained in the fetch group for the
303      * persistence-capable class. If there are duplicates in the parameter
304      * Collection, the corresponding detached copy is used for each such duplicate.
305      */
306     public Collection   versantDetachCopy(Collection   pcs, String   fetchGroup);
307 
308     /**
309      * Are instances in the local PM cache checked for consistency on commit?
310      * The default is false.
311      *
312      * @see #checkModelConsistency()
313      * @see #setCheckModelConsistencyOnCommit(boolean)
314      * @see VersantPersistenceManagerFactory#isCheckModelConsistencyOnCommit()
315      */
316     public boolean isCheckModelConsistencyOnCommit();
317 
318     /**
319      * Enable or disable commit time consistency checking. When this flag is
320      * enabled all instances in the local PM cache checked for consistency on
321      * commit. This check is expensive and should only be enabled during
322      * development.
323      *
324      * @see #checkModelConsistency()
325      * @see VersantPersistenceManagerFactory#setCheckModelConsistencyOnCommit(boolean)
326      */
327     public void setCheckModelConsistencyOnCommit(boolean on);
328 
329     /**
330      * Check the consistency of all instances in the local cache. Currently
331      * this makes sure that all birectional relationships have been completed
332      * properly (both sides in sync) but other checks may will be added in
333      * future. This method is very slow and should only be used for debugging
334      * during development.
335      *
336      * @see #setCheckModelConsistencyOnCommit(boolean)
337      */
338     public void checkModelConsistency();
339 
340     /**
341      * This method applies the changes contained in the collection of detached
342      * instances to the corresponding persistent instances in the cache and
343      * returns a collection of persistent instances that exactly corresponds to
344      * the parameter instances. The order of instances in the parameter
345      * Collection's iteration corresponds to the order of corresponding
346      * instances in the returned Collection's iteration.
347      * <p/>
348      * Changes made to instances while detached are applied to the corresponding
349      * persistent instances in the cache. New instances associated with the
350      * detached instances are added to the persistent instances in the
351      * corresponding place.
352      */
353     public Collection   versantAttachCopy(Collection   detached,
354             boolean makeTransactional);
355 
356     /**
357      * This method applies the changes contained in the collection of detached
358      * instances to the corresponding persistent instances in the cache and
359      * returns a collection of persistent instances that exactly corresponds to
360      * the parameter instances. The order of instances in the parameter
361      * Collection's iteration corresponds to the order of corresponding
362      * instances in the returned Collection's iteration.
363      * <p/>
364      * Changes made to instances while detached are applied to the corresponding
365      * persistent instances in the cache. New instances associated with the
366      * detached instances are added to the persistent instances in the
367      * corresponding place.
368      *
369      * @param detached VersantDetachable objects to attach in the current
370      *                 transaction
371      * @param shallow  attach only the objects in 'detached' Collection and not
372      *                 reachable objects if true.
373      */
374     public Collection   versantAttachCopy(Collection   detached,
375             boolean makeTransactional, boolean shallow);
376 
377     /**
378      * Change the type of reference to an instance in the local PM cache
379      * i.e. an instance managed by this PM.
380      *
381      * @see #PM_CACHE_REF_TYPE_WEAK
382      * @see #PM_CACHE_REF_TYPE_SOFT
383      * @see #PM_CACHE_REF_TYPE_STRONG
384      */
385     public void setPmCacheRefType(Object   pc, int type);
386 
387     /**
388      * Change the type of reference to an array of instances in the local PM
389      * cache i.e. an array of instances managed by this PM.
390      *
391      * @see #PM_CACHE_REF_TYPE_WEAK
392      * @see #PM_CACHE_REF_TYPE_SOFT
393      * @see #PM_CACHE_REF_TYPE_STRONG
394      */
395     public void setPmCacheRefType(Object  [] pcs, int type);
396 
397     /**
398      * Change the type of reference to a collection of instances in the local
399      * PM cache i.e. an array of instances managed by this PM.
400      *
401      * @see #PM_CACHE_REF_TYPE_WEAK
402      * @see #PM_CACHE_REF_TYPE_SOFT
403      * @see #PM_CACHE_REF_TYPE_STRONG
404      */
405     public void setPmCacheRefType(Collection   col, int type);
406 
407     /**
408      * Set the type of reference used to reference new instances added to
409      * the local PM cache.
410      *
411      * @see #PM_CACHE_REF_TYPE_WEAK
412      * @see #PM_CACHE_REF_TYPE_SOFT
413      * @see #PM_CACHE_REF_TYPE_STRONG
414      */
415     public void setPmCacheRefType(int type);
416 
417     /**
418      * Get the type of reference used to reference new instances added to
419      * the local PM cache.
420      *
421      * @see #PM_CACHE_REF_TYPE_WEAK
422      * @see #PM_CACHE_REF_TYPE_SOFT
423      * @see #PM_CACHE_REF_TYPE_STRONG
424      */
425     public int getPmCacheRefType();
426 
427     /**
428      * If this is true then the datastore connection is retained throughout
429      * an optimistic tx even for JDBC databases. Note that the datastore
430      * may ignore this flag (e.g. Versant which always retains the
431      * connection). 
432      */
433     public void setRetainConnectionInOptTx(boolean on);
434 
435     /**
436      * Evict all information for an OID or persistent instance from the
437      * level 2 cache if the current transaction commits. If there is no
438      * active transaction the oid will be evicted after the next transaction
439      * that commits changes to the database. This is a NOP
440      * if there is no information in the cache for the OID or object or
441      * if the object is transient.
442      *
443      * @see VersantPersistenceManagerFactory#evict(java.lang.Object)
444      */
445     public void evictFromL2CacheAfterCommit(Object   o);
446 
447     /**
448      * Do {@link #evictFromL2CacheAfterCommit(java.lang.Object)} for each
449      * entry in the array.
450      *
451      * @see VersantPersistenceManagerFactory#evictAll(java.lang.Object[])
452      */
453     public void evictAllFromL2CacheAfterCommit(Object  [] a);
454 
455     /**
456      * Do {@link #evictFromL2CacheAfterCommit(java.lang.Object)} for each
457      * entry in the collection.
458      *
459      * @see VersantPersistenceManagerFactory#evictAll(java.util.Collection)
460      */
461     public void evictAllFromL2CacheAfterCommit(Collection   c);
462 
463     /**
464      * Evict all information for all instances of a Class from the level
465      * 2 cache if the current transaction commits. If there is no
466      * active transaction the class(es) will be evicted after the next
467      * transaction that commits changes to the database.
468      *
469      * @param cls Class to be evicted
470      * @param includeSubclasses If true then instances of subclasses are also
471      *              evicted
472      *
473      * @see VersantPersistenceManagerFactory#evictAll(java.lang.Class, boolean)
474      */
475     public void evictAllFromL2CacheAfterCommit(Class   cls, boolean includeSubclasses);
476 
477     /**
478      * Evict all JDO instances from the level 2 cache if the current
479      * transaction commits. If there is no active transaction the cache is
480      * emptied immediately.
481      */
482     public void evictAllFromL2CacheAfterCommit();
483 
484     /**
485      * Return the Optimistic locking field value.
486      * If the instance is persistent-new or if changedChecking is used then
487      * 'null' will be returned.
488      */
489     public Object   getOptimisticLockingValue(Object   o);
490 
491     /**
492      * This PersistenceManager method adds the listener to the list of
493      * lifecycle event listeners. The classes parameter identifies all
494      * of the classes of interest. If the classes parameter is specified
495      * as null, events for all persistent classes and interfaces are
496      * generated. If the classes specified have persistence-capable
497      * subclasses, all such subclasses are registered implicitly. The
498      * listener will be called for each event for which it implements
499      * the corresponding listener interface.
500      */
501     public void addLifecycleListener(LifecycleListener listener,
502             Class  [] classes);
503 
504     /**
505      * This PersistenceManager method removes the listener from the list of
506      * event listeners.
507      */
508     public void removeLifecycleListener(LifecycleListener listener);
509 
510 }
511 
512
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags