001: /*
002: * Copyright (c) 1998 - 2005 Versant Corporation
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * Versant Corporation - initial API and implementation
010: */
011: package com.versant.core.jdo;
012:
013: import javax.jdo.PersistenceManager;
014: import javax.jdo.Query;
015: import java.sql.Connection;
016: import java.util.Collection;
017: import java.util.List;
018:
019: /**
020: * JDO Genie extension of the standard JDO PersistenceManager interface.
021: */
022: public interface VersantPersistenceManager extends PersistenceManager {
023:
024: /**
025: * Do not lock any objects in datastore tx.
026: */
027: public static final int LOCKING_NONE = 1;
028: /**
029: * Lock only the first object navigated or fetched in datastore tx.
030: */
031: public static final int LOCKING_FIRST = 2;
032: /**
033: * Lock all objects in datastore tx (not fully supported on all db's).
034: */
035: public static final int LOCKING_ALL = 3;
036:
037: public static final int EVENT_ERRORS = VersantPersistenceManagerFactory.EVENT_ERRORS;
038: public static final int EVENT_NORMAL = VersantPersistenceManagerFactory.EVENT_NORMAL;
039: public static final int EVENT_VERBOSE = VersantPersistenceManagerFactory.EVENT_VERBOSE;
040: public static final int EVENT_ALL = VersantPersistenceManagerFactory.EVENT_ALL;
041:
042: /**
043: * Use strong references to instances in the local PM cache. *
044: */
045: public final static int PM_CACHE_REF_TYPE_STRONG = 1;
046: /**
047: * Use soft references to instances in the local PM cache. *
048: */
049: public final static int PM_CACHE_REF_TYPE_SOFT = 2;
050: /**
051: * Use weak references to instances in the local PM cache. *
052: */
053: public final static int PM_CACHE_REF_TYPE_WEAK = 3;
054:
055: /**
056: * If this flag is true then access to default fetch group fields loaded
057: * into an instance is intercepted. See the "Cache Management" chapter of
058: * the manual for more information on this flag.
059: */
060: public boolean isInterceptDfgFieldAccess();
061:
062: /**
063: * Control the interception of access to default fetch group fields loaded
064: * into an instance. See the "Cache Management" chapter of the manual
065: * for more information on this flag.
066: */
067: public void setInterceptDfgFieldAccess(
068: boolean interceptDfgFieldAccess);
069:
070: /**
071: * This will cancel the last exectuted query.
072: */
073: public void cancelQueryExecution();
074:
075: /**
076: * Does the current transaction contain any dirty instances?
077: */
078: public boolean isDirty();
079:
080: /**
081: * Utility method to return an datastore identity instance by the String
082: * value that was returned from the id of the instance. This avoids having
083: * to obtain the identity class for an Object and then via reflection
084: * creating an instance of the id and asking the pm for the pc instance
085: * by the id instance.
086: */
087: public Object getObjectByIDString(String value, boolean toValidate);
088:
089: /**
090: * <p>This method returns an OID instance for the given class and String.
091: * If the String is for a datastore identity class then the pcClass
092: * parameter may be null. Calling this method with resolved true is
093: * equivalent to calling {@link #newObjectIdInstance(Class, String) }.</p>
094: * <p/>
095: * <p>If resolved is false then the String may be for a superclass of the
096: * actual class. For datastore identity classes this is only possible if
097: * you have constructed the String yourself from the class ID of the base
098: * class and the primary key of the instance.</p>
099: *
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,
307: String fetchGroup);
308:
309: /**
310: * Are instances in the local PM cache checked for consistency on commit?
311: * The default is false.
312: *
313: * @see #checkModelConsistency()
314: * @see #setCheckModelConsistencyOnCommit(boolean)
315: * @see VersantPersistenceManagerFactory#isCheckModelConsistencyOnCommit()
316: */
317: public boolean isCheckModelConsistencyOnCommit();
318:
319: /**
320: * Enable or disable commit time consistency checking. When this flag is
321: * enabled all instances in the local PM cache checked for consistency on
322: * commit. This check is expensive and should only be enabled during
323: * development.
324: *
325: * @see #checkModelConsistency()
326: * @see VersantPersistenceManagerFactory#setCheckModelConsistencyOnCommit(boolean)
327: */
328: public void setCheckModelConsistencyOnCommit(boolean on);
329:
330: /**
331: * Check the consistency of all instances in the local cache. Currently
332: * this makes sure that all birectional relationships have been completed
333: * properly (both sides in sync) but other checks may will be added in
334: * future. This method is very slow and should only be used for debugging
335: * during development.
336: *
337: * @see #setCheckModelConsistencyOnCommit(boolean)
338: */
339: public void checkModelConsistency();
340:
341: /**
342: * This method applies the changes contained in the collection of detached
343: * instances to the corresponding persistent instances in the cache and
344: * returns a collection of persistent instances that exactly corresponds to
345: * the parameter instances. The order of instances in the parameter
346: * Collection's iteration corresponds to the order of corresponding
347: * instances in the returned Collection's iteration.
348: * <p/>
349: * Changes made to instances while detached are applied to the corresponding
350: * persistent instances in the cache. New instances associated with the
351: * detached instances are added to the persistent instances in the
352: * corresponding place.
353: */
354: public Collection versantAttachCopy(Collection detached,
355: boolean makeTransactional);
356:
357: /**
358: * This method applies the changes contained in the collection of detached
359: * instances to the corresponding persistent instances in the cache and
360: * returns a collection of persistent instances that exactly corresponds to
361: * the parameter instances. The order of instances in the parameter
362: * Collection's iteration corresponds to the order of corresponding
363: * instances in the returned Collection's iteration.
364: * <p/>
365: * Changes made to instances while detached are applied to the corresponding
366: * persistent instances in the cache. New instances associated with the
367: * detached instances are added to the persistent instances in the
368: * corresponding place.
369: *
370: * @param detached VersantDetachable objects to attach in the current
371: * transaction
372: * @param shallow attach only the objects in 'detached' Collection and not
373: * reachable objects if true.
374: */
375: public Collection versantAttachCopy(Collection detached,
376: boolean makeTransactional, boolean shallow);
377:
378: /**
379: * Change the type of reference to an instance in the local PM cache
380: * i.e. an instance managed by this PM.
381: *
382: * @see #PM_CACHE_REF_TYPE_WEAK
383: * @see #PM_CACHE_REF_TYPE_SOFT
384: * @see #PM_CACHE_REF_TYPE_STRONG
385: */
386: public void setPmCacheRefType(Object pc, int type);
387:
388: /**
389: * Change the type of reference to an array of instances in the local PM
390: * cache i.e. an array of instances managed by this PM.
391: *
392: * @see #PM_CACHE_REF_TYPE_WEAK
393: * @see #PM_CACHE_REF_TYPE_SOFT
394: * @see #PM_CACHE_REF_TYPE_STRONG
395: */
396: public void setPmCacheRefType(Object[] pcs, int type);
397:
398: /**
399: * Change the type of reference to a collection of instances in the local
400: * PM cache i.e. an array of instances managed by this PM.
401: *
402: * @see #PM_CACHE_REF_TYPE_WEAK
403: * @see #PM_CACHE_REF_TYPE_SOFT
404: * @see #PM_CACHE_REF_TYPE_STRONG
405: */
406: public void setPmCacheRefType(Collection col, int type);
407:
408: /**
409: * Set the type of reference used to reference new instances added to
410: * the local PM cache.
411: *
412: * @see #PM_CACHE_REF_TYPE_WEAK
413: * @see #PM_CACHE_REF_TYPE_SOFT
414: * @see #PM_CACHE_REF_TYPE_STRONG
415: */
416: public void setPmCacheRefType(int type);
417:
418: /**
419: * Get the type of reference used to reference new instances added to
420: * the local PM cache.
421: *
422: * @see #PM_CACHE_REF_TYPE_WEAK
423: * @see #PM_CACHE_REF_TYPE_SOFT
424: * @see #PM_CACHE_REF_TYPE_STRONG
425: */
426: public int getPmCacheRefType();
427:
428: /**
429: * If this is true then the datastore connection is retained throughout
430: * an optimistic tx even for JDBC databases. Note that the datastore
431: * may ignore this flag (e.g. Versant which always retains the
432: * connection).
433: */
434: public void setRetainConnectionInOptTx(boolean on);
435:
436: /**
437: * Evict all information for an OID or persistent instance from the
438: * level 2 cache if the current transaction commits. If there is no
439: * active transaction the oid will be evicted after the next transaction
440: * that commits changes to the database. This is a NOP
441: * if there is no information in the cache for the OID or object or
442: * if the object is transient.
443: *
444: * @see VersantPersistenceManagerFactory#evict(java.lang.Object)
445: */
446: public void evictFromL2CacheAfterCommit(Object o);
447:
448: /**
449: * Do {@link #evictFromL2CacheAfterCommit(java.lang.Object)} for each
450: * entry in the array.
451: *
452: * @see VersantPersistenceManagerFactory#evictAll(java.lang.Object[])
453: */
454: public void evictAllFromL2CacheAfterCommit(Object[] a);
455:
456: /**
457: * Do {@link #evictFromL2CacheAfterCommit(java.lang.Object)} for each
458: * entry in the collection.
459: *
460: * @see VersantPersistenceManagerFactory#evictAll(java.util.Collection)
461: */
462: public void evictAllFromL2CacheAfterCommit(Collection c);
463:
464: /**
465: * Evict all information for all instances of a Class from the level
466: * 2 cache if the current transaction commits. If there is no
467: * active transaction the class(es) will be evicted after the next
468: * transaction that commits changes to the database.
469: *
470: * @param cls Class to be evicted
471: * @param includeSubclasses If true then instances of subclasses are also
472: * evicted
473: *
474: * @see VersantPersistenceManagerFactory#evictAll(java.lang.Class, boolean)
475: */
476: public void evictAllFromL2CacheAfterCommit(Class cls,
477: boolean includeSubclasses);
478:
479: /**
480: * Evict all JDO instances from the level 2 cache if the current
481: * transaction commits. If there is no active transaction the cache is
482: * emptied immediately.
483: */
484: public void evictAllFromL2CacheAfterCommit();
485:
486: /**
487: * Return the Optimistic locking field value.
488: * If the instance is persistent-new or if changedChecking is used then
489: * 'null' will be returned.
490: */
491: public Object getOptimisticLockingValue(Object o);
492:
493: /**
494: * This PersistenceManager method adds the listener to the list of
495: * lifecycle event listeners. The classes parameter identifies all
496: * of the classes of interest. If the classes parameter is specified
497: * as null, events for all persistent classes and interfaces are
498: * generated. If the classes specified have persistence-capable
499: * subclasses, all such subclasses are registered implicitly. The
500: * listener will be called for each event for which it implements
501: * the corresponding listener interface.
502: */
503: public void addLifecycleListener(LifecycleListener listener,
504: Class[] classes);
505:
506: /**
507: * This PersistenceManager method removes the listener from the list of
508: * event listeners.
509: */
510: public void removeLifecycleListener(LifecycleListener listener);
511:
512: }
|