Added: incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java
URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java?view=auto&rev=159273
==============================================================================
--- incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java (added)
+++ incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManager.java Mon Mar 28 10:25:05 2005
@@ -0,0 +1,904 @@
+/*
+ * Copyright 2005 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * PersistenceManager.java
+ *
+ */
+
+package javax.jdo;
+
+import java.util.Collection;
+import java.util.Map;
+import java.util.Properties;
+import java.util.Comparator;
+import java.lang.Class;
+
+import javax.jdo.spi.StateInterrogation;
+
+import javax.jdo.listener.InstanceLifecycleListener;
+
+import javax.jdo.datastore.Sequence;
+import javax.jdo.datastore.JDOConnection;
+
+/** <code>PersistenceManager</code> is the primary interface for JDO-aware application
+ * components. It is the factory for <code>Query</code> and <code>Transaction</code> instances,
+ * and contains methods to manage the life cycle of <code>PersistenceCapable</code>
+ * instances.
+ *
+ * <P>A <code>PersistenceManager</code> is obtained from the
+ * {@link PersistenceManagerFactory}
+ * (recommended) or by construction.
+ * @version 2.0
+ */
+
+public interface PersistenceManager {
+ /**
+ * A <code>PersistenceManager</code> instance can be used until it is closed.
+ * @return <code>true</code> if this <code>PersistenceManager</code> has been closed.
+ * @see #close()
+ */
+ boolean isClosed ();
+
+ /** Close this <code>PersistenceManager</code> so that no further requests may be
+ * made on it. A <code>PersistenceManager</code> instance can be used
+ * only until it is closed.
+ *
+ * <P>Closing a <code>PersistenceManager</code> might release it to the pool of available
+ * <code>PersistenceManager</code>s, or might be garbage collected, at the option of
+ * the JDO implementation. Before being used again to satisfy a
+ * <code>getPersistenceManager()</code> request, the default values for options will
+ * be restored to their values as specified in the <code>PersistenceManagerFactory</code>.
+ *
+ * <P>This method closes the <code>PersistenceManager</code>.
+ */
+ void close ();
+
+ /** Return the <code>Transaction</code> instance associated with a <code>PersistenceManager</code>.
+ * There is one <code>Transaction</code> instance associated with each <code>PersistenceManager</code>
+ * instance. The <code>Transaction</code> instance supports options as well as
+ * transaction completion requests.
+ * @return the <code>Transaction</code> associated with this
+ * <code>PersistenceManager</code>.
+ */
+ Transaction currentTransaction();
+
+ /** Mark an instance as no longer needed in the cache.
+ * Eviction is normally done automatically by the <code>PersistenceManager</code>
+ * at transaction completion. This method allows the application to
+ * explicitly provide a hint to the <code>PersistenceManager</code> that the instance
+ * is no longer needed in the cache.
+ * @param pc the instance to evict from the cache.
+ */
+ void evict (Object pc);
+
+ /** Mark an array of instances as no longer needed in the cache.
+ * @see #evict(Object pc)
+ * @param pcs the array of instances to evict from the cache.
+ */
+ void evictAll (Object[] pcs);
+
+ /** Mark a <code>Collection</code> of instances as no longer needed in the cache.
+ * @see #evict(Object pc)
+ * @param pcs the <code>Collection</code> of instances to evict from the cache.
+ */
+ void evictAll (Collection pcs);
+
+ /** Mark all persistent-nontransactional instances as no longer needed
+ * in the cache. It transitions
+ * all persistent-nontransactional instances to hollow. Transactional
+ * instances are subject to eviction based on the RetainValues setting.
+ * @see #evict(Object pc)
+ */
+ void evictAll ();
+
+ /** Refresh the state of the instance from the data store.
+ *
+ * <P>In an optimistic transaction, the state of instances in the cache
+ * might not match the state in the data store. This method is used to
+ * reload the state of the instance from the data store so that a subsequent
+ * commit is more likely to succeed.
+ * <P>Outside a transaction, this method will refresh nontransactional state.
+ * @param pc the instance to refresh.
+ */
+ void refresh (Object pc);
+
+ /** Refresh the state of an array of instances from the data store.
+ *
+ * @see #refresh(Object pc)
+ * @param pcs the array of instances to refresh.
+ */
+ void refreshAll (Object[] pcs);
+
+ /** Refresh the state of a <code>Collection</code> of instances from the data store.
+ *
+ * @see #refresh(Object pc)
+ * @param pcs the <code>Collection</code> of instances to refresh.
+ */
+ void refreshAll (Collection pcs);
+
+ /** Refresh the state of all applicable instances from the data store.
+ * <P>If called with an active transaction, all transactional instances
+ * will be refreshed. If called outside an active transaction, all
+ * nontransactional instances will be refreshed.
+ * @see #refresh(Object pc)
+ */
+ void refreshAll ();
+
+ /**
+ * Refreshes all instances in the exception that failed verification.
+ *
+ * @since 2.0
+ */
+ void refreshAll (JDOException jdoe);
+
+ /** Create a new <code>Query</code> with no elements.
+ * @return the new <code>Query</code>.
+ */
+ Query newQuery ();
+
+ /** Create a new <code>Query</code> using elements from another <code>Query</code>.
+ * The other <code>Query</code> must have been created by the same JDO implementation.
+ * It might be active
+ * in a different <code>PersistenceManager</code> or might have been serialized and restored.
+ * <P>All of the settings of the other <code>Query</code> are copied to this <code>Query</code>,
+ * except for the candidate <code>Collection</code> or <code>Extent</code>.
+ * @return the new <code>Query</code>
+ * @param compiled another <code>Query</code> from the same JDO implementation
+ */
+ Query newQuery (Object compiled);
+
+ /** Create a Construct a new query instance using the specified String
+ * as the single-string representation of the query.
+ * @param query the single-string query
+ * @return the new <code>Query</code>
+ * @since 2.0
+ */
+ Query newQuery (String query);
+
+ /** Create a new <code>Query</code> using the specified language.
+ * @param language the language of the query parameter
+ * @param query the query, which is of a form determined by the language
+ * @return the new <code>Query</code>
+ */
+ Query newQuery (String language, Object query);
+
+ /** Create a new <code>Query</code> specifying the <code>Class</code> of the candidate instances.
+ * @param cls the <code>Class</code> of the candidate instances
+ * @return the new <code>Query</code>
+ */
+ Query newQuery (Class cls);
+
+ /** Create a new <code>Query</code> with the <code>Class</code> of the
+ * candidate instances and candidate <code>Extent</code>.
+ * @param cln the <code>Extent</code> of candidate instances
+ * @return the new <code>Query</code>
+ */
+ Query newQuery (Extent cln);
+
+ /** Create a new <code>Query</code> with the candidate <code>Class</code>
+ * and <code>Collection</code>.
+ * @param cls the <code>Class</code> of results
+ * @param cln the <code>Collection</code> of candidate instances
+ * @return the new <code>Query</code>
+ */
+ Query newQuery (Class cls, Collection cln);
+
+ /** Create a new <code>Query</code> with the <code>Class</code> of the
+ * candidate instances and filter.
+ * @param cls the <code>Class</code> of results
+ * @param filter the filter for candidate instances
+ * @return the new <code>Query</code>
+ */
+ Query newQuery (Class cls, String filter);
+
+ /** Create a new <code>Query</code> with the <code>Class</code> of the candidate instances,
+ * candidate <code>Collection</code>, and filter.
+ * @param cls the <code>Class</code> of candidate instances
+ * @param cln the <code>Collection</code> of candidate instances
+ * @param filter the filter for candidate instances
+ * @return the new <code>Query</code>
+ */
+ Query newQuery (Class cls, Collection cln, String filter);
+
+ /** Create a new <code>Query</code> with the
+ * candidate <code>Extent</code> and filter; the class
+ * is taken from the <code>Extent</code>.
+ * @param cln the <code>Extent</code> of candidate instances
+ * @param filter the filter for candidate instances
+ * @return the new <code>Query</code>
+ */
+ Query newQuery (Extent cln, String filter);
+
+ /**
+ * Create a new <code>Query</code> with the given candidate class
+ * from a named query. The query name given must be the name of a
+ * query defined in metadata.
+ * @param cls the <code>Class</code> of candidate instances
+ * @param queryName the name of the query to look up in metadata
+ * @return the new <code>Query</code>
+ */
+ Query newNamedQuery (Class cls, String queryName);
+
+ /** The <code>PersistenceManager</code> manages a collection of instances in the data
+ * store based on the class of the instances. This method returns an
+ * <code>Extent</code> of instances in the data store that might be iterated or
+ * given to a <code>Query</code>. The <code>Extent</code> itself might not reference any
+ * instances, but only hold the class name and an
+ * indicator as to whether subclasses are included in the <code>Extent</code>.
+ * <P>Note that the <code>Extent</code> might be very large.
+ * @param persistenceCapableClass <code>Class</code> of instances
+ * @param subclasses whether to include instances of subclasses
+ * @return an <code>Extent</code> of the specified <code>Class</code>
+ * @see Query
+ */
+ Extent getExtent (Class persistenceCapableClass, boolean subclasses);
+
+ /**
+ * Equivalent to <code>getExtent (persistenceCapableClass,
+ * true)</code>.
+ * @see #getExtent(Class,boolean)
+ * @since 2.0
+ */
+ Extent getExtent (Class persistenceCapableClass);
+
+ /** This method locates a persistent instance in the cache of instances
+ * managed by this <code>PersistenceManager</code>.
+ * The <code>getObjectById</code> method attempts
+ * to find an instance in the cache with the specified JDO identity.
+ * The <code>oid</code> parameter object might have been returned by an earlier call
+ * to <code>getObjectId</code> or <code>getTransactionalObjectId</code>,
+ * or might have been constructed by the application.
+ * <P>If the <code>PersistenceManager</code> is unable to resolve the <code>oid</code> parameter
+ * to an ObjectId instance, then it throws a <code>JDOUserException</code>.
+ * <P>If the <code>validate</code> flag is <code>false</code>, and there is already an instance in the
+ * cache with the same JDO identity as the <code>oid</code> parameter, then this method
+ * returns it. There is no change made to the state of the returned
+ * instance.
+ * <P>If there is not an instance already in the cache with the same JDO
+ * identity as the <code>oid</code> parameter, then this method creates an instance
+ * with the specified JDO identity and returns it. If there is no
+ * transaction in progress, the returned instance will be hollow or
+ * persistent-nontransactional, at the choice of the implementation.
+ * <P>If there is a transaction in progress, the returned instance will
+ * be hollow, persistent-nontransactional, or persistent-clean, at the
+ * choice of the implementation.
+ * <P>It is an implementation decision whether to access the data store,
+ * if required to determine the exact class. This will be the case of
+ * inheritance, where multiple <code>PersistenceCapable</code> classes share the
+ * same ObjectId class.
+ * <P>If the validate flag is <code>false</code>, and the instance does not exist in
+ * the data store, then this method might not fail. It is an
+ * implementation choice whether to fail immediately with a
+ * <code>JDODataStoreException</code>. But a subsequent access of the fields of the
+ * instance will throw a <code>JDODataStoreException</code> if the instance does not
+ * exist at that time. Further, if a relationship is established to this
+ * instance, then the transaction in which the association was made will
+ * fail.
+ * <P>If the <code>validate</code> flag is <code>true</code>, and there is already a transactional
+ * instance in the cache with the same JDO identity as the <code>oid</code> parameter,
+ * then this method returns it. There is no change made to the state of
+ * the returned instance.
+ * <P>If there is an instance already in the cache with the same JDO
+ * identity as the <code>oid</code> parameter, but the instance is not transactional,
+ * then it must be verified in the data store. If the instance does not
+ * exist in the datastore, then a <code>JDODataStoreException</code> is thrown.
+ * <P>If there is not an instance already in the cache with the same JDO
+ * identity as the <code>oid</code> parameter, then this method creates an instance
+ * with the specified JDO identity, verifies that it exists in the data
+ * store, and returns it. If there is no transaction in progress, the
+ * returned instance will be hollow or persistent-nontransactional,
+ * at the choice of the implementation.
+ * <P>If there is a data store transaction in progress, the returned
+ * instance will be persistent-clean.
+ * If there is an optimistic transaction in progress, the returned
+ * instance will be persistent-nontransactional.
+ * @see #getObjectId(Object pc)
+ * @see #getTransactionalObjectId(Object pc)
+ * @return the <code>PersistenceCapable</code> instance with the specified ObjectId
+ * @param oid an ObjectId
+ * @param validate if the existence of the instance is to be validated
+ */
+ Object getObjectById (Object oid, boolean validate);
+
+ /**
+ * Looks up the instance of the given type with the given key.
+ * @param cls The type of object to load
+ * @param key either the string representation of the object id, or
+ * an object representation of a single field identity key
+ * @return the corresponding persistent instance
+ * @since 2.0
+ */
+ Object getObjectById (Class cls, Object key);
+
+ /**
+ * Looks up the instance corresponding to the specified oid. This is
+ * equivalent to <code>getObjectById(oid, true);
+ * @param oid The object id of the object to load
+ * @return the corresponding persistent instance
+ */
+ Object getObjectById (Object oid);
+
+ /** The ObjectId returned by this method represents the JDO identity of
+ * the instance. The ObjectId is a copy (clone) of the internal state
+ * of the instance, and changing it does not affect the JDO identity of
+ * the instance.
+ * <P>The <code>getObjectId</code> method returns an ObjectId instance that represents
+ * the object identity of the specified JDO instance. The identity is
+ * guaranteed to be unique only in the context of the JDO
+ * <code>PersistenceManager</code> that created the identity, and only for two types
+ * of JDO Identity: those that are managed by the application, and
+ * those that are managed by the data store.
+ * <P>If the object identity is being changed in the transaction, by the
+ * application modifying one or more of the application key fields,
+ * then this method returns the identity as of the beginning of the
+ * transaction. The value returned by <code>getObjectId</code> will be different
+ * following <code>afterCompletion</code> processing for successful transactions.
+ * <P>Within a transaction, the ObjectId returned will compare equal to
+ * the ObjectId returned by only one among all JDO instances associated
+ * with the <code>PersistenceManager</code> regardless of the type of ObjectId.
+ * <P>The ObjectId does not necessarily contain any internal state of the
+ * instance, nor is it necessarily an instance of the class used to
+ * manage identity internally. Therefore, if the application makes a
+ * change to the ObjectId instance returned by this method, there is
+ * no effect on the instance from which the ObjectId was obtained.
+ * <P>The <code>getObjectById</code> method can be used between instances of
+ * <code>PersistenceManager</code> of different JDO vendors only for instances of
+ * persistence capable classes using application-managed (primary key)
+ * JDO identity. If it is used for instances of classes using datastore
+ * identity, the method might succeed, but there are no guarantees that
+ * the parameter and return instances are related in any way.
+ * @see #getTransactionalObjectId(Object pc)
+ * @see #getObjectById(Object oid, boolean validate)
+ * @param pc the <code>PersistenceCapable</code> instance
+ * @return the ObjectId of the instance
+ */
+ Object getObjectId (Object pc);
+
+ /** The ObjectId returned by this method represents the JDO identity of
+ * the instance. The ObjectId is a copy (clone) of the internal state
+ * of the instance, and changing it does not affect the JDO identity of
+ * the instance.
+ * <P>If the object identity is being changed in the transaction, by the
+ * application modifying one or more of the application key fields,
+ * then this method returns the current identity in the transaction.
+ * <P>If there is no transaction in progress, or if none of the key fields
+ * is being modified, then this method will return the same value as
+ * <code>getObjectId</code>.
+ * @see #getObjectId(Object pc)
+ * @see #getObjectById(Object oid, boolean validate)
+ * @param pc a <code>PersistenceCapable</code> instance
+ * @return the ObjectId of the instance
+ */
+ Object getTransactionalObjectId (Object pc);
+
+ /**
+ * This method returns an object id instance corresponding to the pcClass
+ * and key arguments.
+ * @param pcClass the <code>Class</code> of the persistence-capable instance
+ * @param key the value of the key field for single-field identity.
+ * @return an instance of the object identity class
+ */
+ Object newObjectIdInstance (Class pcClass, Object key);
+
+ /**
+ * Return the objects with the given oids.
+ * @param oids the oids of the objects to return
+ * @param validate if true, the existance of the objects in
+ * the datastore will be validated.
+ * @return the objects that were looked up, in the
+ * same order as the oids parameter.
+ * @see #getObjectById(Object,boolean)
+ * @since 2.0
+ */
+ Collection getObjectsById (Collection oids, boolean validate);
+
+ /**
+ * Return the objects with the given oids. This method is equivalent
+ * to calling {@link #getObjectsById(Collection, boolean)}
+ * with the validate flag true.
+ * @param oids the oids of the objects to return
+ * @return the objects that were looked up, in the
+ * same order as the oids parameter.
+ * @see #getObjectsById(Collection,boolean)
+ * @since 2.0
+ */
+ Collection getObjectsById (Collection oids);
+
+ /**
+ * Return the objects with the given oids.
+ * @param oids the oids of the objects to return
+ * @param validate if true, the existance of the objects in
+ * the datastore will be validated.
+ * @return the objects that were looked up, in the
+ * same order as the oids parameter.
+ * @see #getObjectById(Object,boolean)
+ * @since 2.0
+ */
+ Object[] getObjectsById (Object[] oids, boolean validate);
+
+ /**
+ * Return the objects with the given oids. This method is equivalent
+ * to calling {@link #getObjectsById(Object[],boolean)}
+ * with the validate flag true.
+ * @param oids the oids of the objects to return
+ * @return the objects that were looked up, in the
+ * same order as the oids parameter.
+ * @see #getObjectsById(Object[],boolean)
+ * @since 2.0
+ */
+ Object[] getObjectsById (Object[] oids);
+
+ /** Make the transient instance persistent in this <code>PersistenceManager</code>.
+ * This method must be called in an active transaction.
+ * The <code>PersistenceManager</code> assigns an ObjectId to the instance and
+ * transitions it to persistent-new.
+ * The instance will be managed in the <code>Extent</code> associated with its <code>Class</code>.
+ * The instance will be put into the data store at commit.
+ * The closure of instances of <code>PersistenceCapable</code> classes
+ * reachable from persistent
+ * fields will be made persistent at commit. [This is known as
+ * persistence by reachability.]
+ * @param pc a transient instance of a <code>Class</code> that implements
+ * <code>PersistenceCapable</code>
+ */
+ void makePersistent (Object pc);
+
+ /** Make an array of instances persistent.
+ * @param pcs an array of transient instances
+ * @see #makePersistent(Object pc)
+ */
+ void makePersistentAll (Object[] pcs);
+
+ /** Make a <code>Collection</code> of instances persistent.
+ * @param pcs a <code>Collection</code> of transient instances
+ * @see #makePersistent(Object pc)
+ */
+ void makePersistentAll (Collection pcs);
+
+ /** Delete the persistent instance from the data store.
+ * This method must be called in an active transaction.
+ * The data store object will be removed at commit.
+ * Unlike <code>makePersistent</code>, which makes the closure of the instance persistent,
+ * the closure of the instance is not deleted from the data store.
+ * This method has no effect if the instance is already deleted in the
+ * current transaction.
+ * This method throws <code>JDOUserException</code> if the instance is transient or
+ * is managed by another <code>PersistenceManager</code>.
+ *
+ * @param pc a persistent instance
+ */
+ void deletePersistent (Object pc);
+
+ /** Delete an array of instances from the data store.
+ * @param pcs a <code>Collection</code> of persistent instances
+ * @see #deletePersistent(Object pc)
+ */
+ void deletePersistentAll (Object[] pcs);
+
+ /** Delete a <code>Collection</code> of instances from the data store.
+ * @param pcs a <code>Collection</code> of persistent instances
+ * @see #deletePersistent(Object pc)
+ */
+ void deletePersistentAll (Collection pcs);
+
+ /** Make an instance transient, removing it from management by this
+ * <code>PersistenceManager</code>.
+ *
+ * <P>The instance loses its JDO identity and it is no longer associated
+ * with any <code>PersistenceManager</code>. The state of fields is preserved unchanged.
+ * @param pc the instance to make transient.
+ */
+ void makeTransient (Object pc);
+
+ /** Make an array of instances transient, removing them from management by this
+ * <code>PersistenceManager</code>.
+ *
+ * <P>The instances lose their JDO identity and they are no longer associated
+ * with any <code>PersistenceManager</code>. The state of fields is preserved unchanged.
+ * @param pcs the instances to make transient.
+ */
+ void makeTransientAll (Object[] pcs);
+
+ /** Make a <code>Collection</code> of instances transient, removing them from
+ * management by this <code>PersistenceManager</code>.
+ *
+ * <P>The instances lose their JDO identity and they are no longer associated
+ * with any <code>PersistenceManager</code>. The state of fields is preserved unchanged.
+ * @param pcs the instances to make transient.
+ */
+ void makeTransientAll (Collection pcs);
+
+ /** Make an instance subject to transactional boundaries.
+ *
+ * <P>Transient instances normally do not observe transaction boundaries.
+ * This method makes transient instances sensitive to transaction completion.
+ * If an instance is modified in a transaction, and the transaction rolls back,
+ * the state of the instance is restored to the state before the first change
+ * in the transaction.
+ *
+ * <P>For persistent instances read in optimistic transactions, this method
+ * allows the application to make the state of the instance part of the
+ * transactional state. At transaction commit, the state of the instance in
+ * the cache is compared to the state of the instance in the data store. If they
+ * are not the same, then an exception is thrown.
+ * @param pc the instance to make transactional.
+ */
+ void makeTransactional (Object pc);
+
+ /** Make an array of instances subject to transactional boundaries.
+ * @param pcs the array of instances to make transactional.
+ * @see #makeTransactional(Object pc)
+ */
+ void makeTransactionalAll (Object[] pcs);
+
+ /** Make a <code>Collection</code> of instances subject to transactional boundaries.
+ * @param pcs the <code>Collection</code> of instances to make transactional.
+ * @see #makeTransactional(Object pc)
+ */
+ void makeTransactionalAll (Collection pcs);
+
+ /** Make an instance non-transactional after commit.
+ *
+ * <P>Normally, at transaction completion, instances are evicted from the
+ * cache. This method allows an application to identify an instance as
+ * not being evicted from the cache at transaction completion. Instead,
+ * the instance remains in the cache with nontransactional state.
+ *
+ * @param pc the instance to make nontransactional.
+ */
+ void makeNontransactional (Object pc);
+
+ /** Make an array of instances non-transactional after commit.
+ *
+ * @param pcs the array of instances to make nontransactional.
+ * @see #makeNontransactional(Object pc)
+ */
+ void makeNontransactionalAll (Object[] pcs);
+
+ /** Make a <code>Collection</code> of instances non-transactional after commit.
+ *
+ * @param pcs the <code>Collection</code> of instances to make nontransactional.
+ * @see #makeNontransactional(Object pc)
+ */
+ void makeNontransactionalAll (Collection pcs);
+
+ /** Retrieve field values of an instance from the store. This tells
+ * the <code>PersistenceManager</code> that the application intends to use the
+ * instance, and its field values must be retrieved.
+ * <P>The <code>PersistenceManager</code> might use policy information about the
+ * class to retrieve associated instances.
+ * @param pc the instance
+ */
+ void retrieve (Object pc);
+
+ /** Retrieve field values of instances from the store. This tells
+ * the <code>PersistenceManager</code> that the application intends to use the
+ * instances, and all field values must be retrieved.
+ * <P>The <code>PersistenceManager</code> might use policy information about the
+ * class to retrieve associated instances.
+ * @param pcs the instances
+ */
+ void retrieveAll (Collection pcs);
+
+ /** Retrieve field values of instances from the store. This tells
+ * the <code>PersistenceManager</code> that the application intends to use the
+ * instances, and their field values should be retrieved. The fields
+ * in the default fetch group must be retrieved, and the implementation
+ * might retrieve more fields than the default fetch group.
+ * <P>The <code>PersistenceManager</code> might use policy information about the
+ * class to retrieve associated instances.
+ * @param pcs the instances
+ * @param DFGOnly whether to retrieve only the default fetch group fields
+ * @since 1.0.1
+ */
+ void retrieveAll (Collection pcs, boolean DFGOnly);
+
+ /** Retrieve field values of instances from the store. This tells
+ * the <code>PersistenceManager</code> that the application intends to use the
+ * instances, and all field values must be retrieved.
+ * <P>The <code>PersistenceManager</code> might use policy information about the
+ * class to retrieve associated instances.
+ * @param pcs the instances
+ */
+ void retrieveAll (Object[] pcs);
+
+ /** Retrieve field values of instances from the store. This tells
+ * the <code>PersistenceManager</code> that the application intends to use the
+ * instances, and their field values should be retrieved. The fields
+ * in the default fetch group must be retrieved, and the implementation
+ * might retrieve more fields than the default fetch group.
+ * <P>The <code>PersistenceManager</code> might use policy information about the
+ * class to retrieve associated instances.
+ * @param pcs the instances
+ * @param DFGOnly whether to retrieve only the default fetch group fields
+ * @since 1.0.1
+ */
+ void retrieveAll (Object[] pcs, boolean DFGOnly);
+
+ /** The application can manage the <code>PersistenceManager</code> instances
+ * more easily by having an application object associated with each
+ * <code>PersistenceManager</code> instance.
+ * @param o the user instance to be remembered by the <code>PersistenceManager</code>
+ * @see #getUserObject
+ */
+ void setUserObject (Object o);
+
+ /** The application can manage the <code>PersistenceManager</code> instances
+ * more easily by having an application object associated with each
+ * <code>PersistenceManager</code> instance.
+ * @return the user object associated with this <code>PersistenceManager</code>
+ * @see #setUserObject
+ */
+ Object getUserObject ();
+
+ /** This method returns the <code>PersistenceManagerFactory</code> used to create
+ * this <code>PersistenceManager</code>.
+ * @return the <code>PersistenceManagerFactory</code> that created
+ * this <code>PersistenceManager</code>
+ */
+ PersistenceManagerFactory getPersistenceManagerFactory();
+
+ /** Return the <code>Class</code> that implements the JDO Identity for the
+ * specified <code>PersistenceCapable</code> class. The application can use the
+ * returned <code>Class</code> to construct a JDO Identity instance for
+ * application identity <code>PersistenceCapable</code> classes. This JDO Identity
+ * instance can then be used to get an instance of the
+ * <code>PersistenceCapable</code> class for use in the application.
+ *
+ * <P>In order for the application to construct an instance of the ObjectId class
+ * it needs to know the class being used by the JDO implementation.
+ * @param cls the <code>PersistenceCapable Class</code>
+ * @return the <code>Class</code> of the ObjectId of the parameter
+ * @see #getObjectById
+ */
+ Class getObjectIdClass(Class cls);
+
+ /** Set the Multithreaded flag for this <code>PersistenceManager</code>. Applications
+ * that use multiple threads to invoke methods or access fields from
+ * instances managed by this <code>PersistenceManager</code> must set this flag to <code>true</code>.
+ * Instances managed by this <code>PersistenceManager</code> include persistent or
+ * transactional instances of <code>PersistenceCapable</code> classes, as well as
+ * helper instances such as <code>Query</code>, <code>Transaction</code>, or <code>Extent</code>.
+ * @param flag the Multithreaded setting.
+ */
+ void setMultithreaded (boolean flag);
+
+ /** Get the current Multithreaded flag for this <code>PersistenceManager</code>.
+ * @see #setMultithreaded
+ * @return the Multithreaded setting.
+ */
+ boolean getMultithreaded();
+
+ /** Set the ignoreCache parameter for queries.
+ *
+ * <P>IgnoreCache set to <code>true</code> specifies that for all <code>Query</code> instances created by this
+ * <code>PersistenceManager</code>, the default is the cache should be ignored for queries.
+ * @param flag the ignoreCache setting.
+ */
+ void setIgnoreCache(boolean flag);
+
+ /** Get the ignoreCache setting for queries.
+ *
+ * <P>IgnoreCache set to <code>true</code> specifies that for all <code>Query</code> instances created by this
+ * <code>PersistenceManager</code>, the default is the cache should be ignored for queries.
+ * @return the ignoreCache setting.
+ */
+ boolean getIgnoreCache();
+ /**
+ * Detach the specified object from the <code>PersistenceManager</code>.
+ * @param pc the instance to detach
+ * @return the detached instance
+ * @see #detachCopyAll(Object[])
+ * @since 2.0
+ */
+ Object detachCopy (Object pc);
+
+ /**
+ * Detach the specified objects from the <code>PersistenceManager</code>.
+ * @param pcs the instances to detach
+ * @return the detached instances
+ * @see #detachCopyAll(Object[])
+ * @since 2.0
+ */
+ Collection detachCopyAll (Collection pcs);
+
+ /**
+ * Detach the specified objects from the
+ * <code>PersistenceManager</code>. The objects returned can be
+ * manipulated and re-attached with
+ * {@link #attachCopyAll(Object[], boolean)}.
+ * The detached instances will be
+ * unmanaged copies of the specified parameters, and are suitable
+ * for serialization and manipulation outside of a JDO
+ * environment. When detaching instances, only fields in the
+ * current {@link FetchPlan} will be traversed. Thus, to detach a
+ * graph of objects, relations to other persistent instances must
+ * either be in the <code>default-fetch-group</code>, or in the
+ * current custom {@link FetchPlan}.
+ * @param pcs the instances to detach
+ * @return the detached instances
+ * @throws JDOUserException if any of the instances do not
+ * @see #attachCopyAll(Object[], boolean)
+ * @see #getFetchPlan
+ * @since 2.0
+ */
+ Object[] detachCopyAll (Object [] pcs);
+
+ /**
+ * Import the specified object into the
+ * <code>PersistenceManager</code>.
+ * @param pc instance to import
+ * @param makeTransactional if <code>true</code>, this method will
+ * mark transactional the persistent instances corresponding
+ * to all instances in the closure of the detached graph.
+ * @return the re-attached instance
+ * @see #attachCopyAll(Object[],boolean)
+ * @since 2.0
+ */
+ Object attachCopy (Object pc, boolean makeTransactional);
+
+ /**
+ * Import the specified objects into the
+ * <code>PersistenceManager</code>.
+ * @param pcs Collection of instances to import
+ * @param makeTransactional if <code>true</code>, this method will
+ * mark transactional the persistent instances corresponding
+ * to all instances in the closure of the detached graph.
+ * @return the re-attached instances
+ * @see #attachCopyAll(Object[],boolean)
+ * @since 2.0
+ */
+ Collection attachCopyAll (Collection pcs, boolean makeTransactional);
+
+ /**
+ * Import the specified objects into the
+ * <code>PersistenceManager</code>. Instances that were
+ * previously detached from this or another
+ * <code>PersistenceManager</code> will have their changed merged
+ * into the persistent instances. Instances that are new will be
+ * persisted as new instances.
+ * @param pcs array of instances to import
+ * @param makeTransactional if <code>true</code>, this method will
+ * mark transactional the persistent instances corresponding
+ * to all instances in the closure of the detached graph.
+ * @return the re-attached instances
+ * @see #detachCopyAll(Object[])
+ * @since 2.0
+ */
+ Object[] attachCopyAll (Object[] pcs, boolean makeTransactional);
+
+ /**
+ * Put the specified key-value pair into the map of user objects.
+ * @since 2.0
+ */
+ Object putUserObject (Object key, Object val);
+
+ /**
+ * Get the value for the specified key from the map of user objects.
+ * @param key the key of the object to be returned
+ * @return the object
+ * @since 2.0
+ */
+ Object getUserObject (Object key);
+
+ /**
+ * Remove the specified key and its value from the map of user objects.
+ * @param key the key of the object to be removed
+ * @since 2.0
+ */
+ Object removeUserObject (Object key);
+
+ /**
+ * Flushes all dirty, new, and deleted instances to the data
+ * store. It has no effect if a transaction is not active.
+ * <p>If a datastore transaction is active, this method
+ * synchronizes the cache with the datastore and reports any
+ * exceptions.</p>
+ * <p>If an optimistic transaction is active, this method obtains
+ * a datastore connection, synchronizes the cache with the
+ * datastore using this connection and reports any
+ * exceptions. The connection obtained by this method is held
+ * until the end of the transaction.</p>
+ * <p>If exceptions occur during flush, the implementation will
+ * set the current transaction's <code>RollbackOnly</code> flag
+ * (see {@link Transaction#setRollbackOnly}).</p>
+ * @since 2.0
+ */
+ void flush ();
+
+ /**
+ * Validates the <code>PersistenceManager</code> cache with the
+ * datastore. This method has no effect if a transaction is not
+ * active.
+ * <p>If a datastore transaction is active, this method verifies
+ * the consistency of instances in the cache against the
+ * datastore. An implementation might flush instances as if
+ * {@link #flush} were called, but it is not required to do
+ * so.</p>
+ * <p>If an optimistic transaction is active, this method obtains
+ * a datastore connection and verifies the consistency of the
+ * instances in the cache against the datastore. If any
+ * inconsistencies are detected, a {@link
+ * JDOOptimisticVerificationException} is thrown. This exception
+ * contains a nested {@link JDOOptimisticVerificationException}
+ * for each object that failed the consistency check. No
+ * datastore resources acquired during the execution of this
+ * method are held beyond the scope of this method.</p>
+ * @since 2.0
+ */
+ void checkConsistency ();
+
+ /**
+ * Returns the <code>FetchPlan</code> used by this
+ * <code>PersistenceManager</code>.
+ * @return the FetchPlan
+ * @since 2.0
+ */
+ FetchPlan getFetchPlan ();
+
+ /**
+ * Creates an instance of a persistence-capable interface or
+ * abstract class. The returned instance is transient.
+ * @param pcClass Must be an abstract class or interface
+ * that is declared in the metadata.
+ * @return the created instance
+ * @since 2.0
+ */
+ Object newInstance (Class pcClass);
+
+ /**
+ * Returns the sequence identified by <code>name</code>.
+ * @param name the name of the Sequence
+ * @return the Sequence
+ * @since 2.0
+ */
+ Sequence getSequence (String name);
+
+ /**
+ * If this method is called while a datastore transaction is
+ * active, the object returned will be enlisted in the current
+ * transaction. If called in an optimistic transaction or outside
+ * an active transaction, the object returned will not be
+ * enlisted in any transaction.
+ * @return the JDOConnection instance
+ * @since 2.0
+ */
+ JDOConnection getDataStoreConnection ();
+
+ /**
+ * Adds the listener instance to the list of lifecycle event
+ * listeners. The <code>classes</code> parameter identifies all
+ * of the classes of interest. If the <code>classes</code>
+ * parameter is specified as <code>null</code>, events for all
+ * persistent classes and interfaces will be sent to
+ * <code>listenerInstance</code>.
+ * <p>The listenerInstance will be called for each event for which it
+ * implements the corresponding listenerInstance interface.</p>
+ * @param listener the lifecycle listener
+ * @param classes the classes of interest to the listener
+ * @since 2.0
+ */
+ void addInstanceLifecycleListener (InstanceLifecycleListener listener,
+ Class[] classes);
+
+ /**
+ * Removes the listener instance from the list of lifecycle event listeners.
+ * @param listener the listener instance to be removed
+ * @since 2.0
+ */
+ void removeInstanceLifecycleListener (InstanceLifecycleListener listener);
+}
Added: incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java
URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java?view=auto&rev=159273
==============================================================================
--- incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java (added)
+++ incubator/jdo/trunk/api20/src/java/javax/jdo/PersistenceManagerFactory.java Mon Mar 28 10:25:05 2005
@@ -0,0 +1,343 @@
+/*
+ * Copyright 2005 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * PersistenceManagerFactory.java
+ *
+ */
+
+package javax.jdo;
+
+import java.util.Properties;
+import java.util.Collection;
+
+import javax.jdo.datastore.DataStoreCache;
+
+/** The <code>PersistenceManagerFactory</code> is the interface to use to obtain
+ * <code>PersistenceManager</code> instances. All <code>PersistenceManager</code> instances obtained
+ * from the same <code>PersistenceManagerFactory</code> will have the same default
+ * properties.
+ *
+ * <P><code>PersistenceManagerFactory</code> instances may be configured and
+ * serialized for later use. They may be stored via JNDI and looked up
+ * and used later. Any properties configured will be saved and restored.
+ *
+ * <P>Once the first <code>PersistenceManager</code> is obtained from the
+ * <code>PersistenceManagerFactory</code>, the factory can no longer be configured.
+ * <P>If the <code>ConnectionFactory</code> property is set (non-<code>null</code>) then
+ * all other Connection properties including <code>ConnectionFactoryName</code> are ignored;
+ * otherwise, if <code>ConnectionFactoryName</code> is set (non-<code>null</code>) then
+ * all other Connection properties are ignored.
+ * Similarly, if the <code>ConnectionFactory2</code> property is set (non-<code>null</code>) then
+ * <code>ConnectionFactory2Name</code> is ignored.
+ * <P>Operational state (<code>PersistenceManager</code> pooling, connection pooling,
+ * operational parameters) must not be serialized.
+ *
+ * @version 2.0
+ */
+
+public interface PersistenceManagerFactory extends java.io.Serializable {
+
+ /** Close this PersistenceManagerFactory. Check for
+ * JDOPermission("closePersistenceManagerFactory") and if not authorized,
+ * throw SecurityException.
+ * <P>If the authorization check succeeds, check to see that all
+ * PersistenceManager instances obtained from this PersistenceManagerFactory
+ * have no active transactions. If any PersistenceManager instances have
+ * an active transaction, throw a JDOUserException, with one nested
+ * JDOUserException for each PersistenceManager with an active Transaction.
+ * <P>If there are no active transactions, then close all PersistenceManager
+ * instances obtained from this PersistenceManagerFactory, mark this
+ * PersistenceManagerFactory as closed, disallow getPersistenceManager
+ * methods, and allow all other get methods. If a set method or
+ * getPersistenceManager method is called after close, then
+ * JDOUserException is thrown.
+ * @since 1.0.1
+ */
+ void close();
+
+ /** Get an instance of <code>PersistenceManager</code> from this factory. The instance has
+ * default values for options.
+ *
+ * <P>After the first use of <code>getPersistenceManager</code>, no "set" methods will
+ * succeed.
+ *
+ * @return a <code>PersistenceManager</code> instance with default options.
+ */
+ PersistenceManager getPersistenceManager();
+
+ /** Get an instance of <code>PersistenceManager</code> from this factory. The instance has
+ * default values for options. The parameters <code>userid</code> and <code>password</code> are used
+ * when obtaining datastore connections from the connection pool.
+ *
+ * <P>After the first use of <code>getPersistenceManager</code>, no "set" methods will
+ * succeed.
+ *
+ * @return a <code>PersistenceManager</code> instance with default options.
+ * @param userid the userid for the connection
+ * @param password the password for the connection
+ */
+ PersistenceManager getPersistenceManager(String userid, String password);
+
+ /** Set the user name for the data store connection.
+ * @param userName the user name for the data store connection.
+ */
+ void setConnectionUserName(String userName);
+
+ /** Get the user name for the data store connection.
+ * @return the user name for the data store connection.
+ */
+ String getConnectionUserName ();
+
+ /** Set the password for the data store connection.
+ * @param password the password for the data store connection.
+ */
+ void setConnectionPassword (String password);
+
+ /** Set the URL for the data store connection.
+ * @param URL the URL for the data store connection.
+ */
+ void setConnectionURL (String URL);
+
+ /** Get the URL for the data store connection.
+ * @return the URL for the data store connection.
+ */
+ String getConnectionURL ();
+
+ /** Set the driver name for the data store connection.
+ * @param driverName the driver name for the data store connection.
+ */
+ void setConnectionDriverName (String driverName);
+
+ /** Get the driver name for the data store connection.
+ * @return the driver name for the data store connection.
+ */
+ String getConnectionDriverName ();
+
+ /** Set the name for the data store connection factory.
+ * @param connectionFactoryName the name of the data store connection factory.
+ */
+ void setConnectionFactoryName (String connectionFactoryName);
+
+ /** Get the name for the data store connection factory.
+ * @return the name of the data store connection factory.
+ */
+ String getConnectionFactoryName ();
+
+ /** Set the data store connection factory. JDO implementations
+ * will support specific connection factories. The connection
+ * factory interfaces are not part of the JDO specification.
+ * @param connectionFactory the data store connection factory.
+ */
+ void setConnectionFactory (Object connectionFactory);
+
+ /** Get the data store connection factory.
+ * @return the data store connection factory.
+ */
+ Object getConnectionFactory ();
+
+ /** Set the name for the second data store connection factory. This is
+ * needed for managed environments to get nontransactional connections for
+ * optimistic transactions.
+ * @param connectionFactoryName the name of the data store connection factory.
+ */
+ void setConnectionFactory2Name (String connectionFactoryName);
+
+ /** Get the name for the second data store connection factory. This is
+ * needed for managed environments to get nontransactional connections for
+ * optimistic transactions.
+ * @return the name of the data store connection factory.
+ */
+ String getConnectionFactory2Name ();
+
+ /** Set the second data store connection factory. This is
+ * needed for managed environments to get nontransactional connections for
+ * optimistic transactions. JDO implementations
+ * will support specific connection factories. The connection
+ * factory interfaces are not part of the JDO specification.
+ * @param connectionFactory the data store connection factory.
+ */
+ void setConnectionFactory2 (Object connectionFactory);
+
+ /** Get the second data store connection factory. This is
+ * needed for managed environments to get nontransactional connections for
+ * optimistic transactions.
+ * @return the data store connection factory.
+ */
+ Object getConnectionFactory2 ();
+
+ /** Set the default Multithreaded setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @param flag the default Multithreaded setting.
+ */
+ void setMultithreaded (boolean flag);
+
+ /** Get the default Multithreaded setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @return the default Multithreaded setting.
+ */
+ boolean getMultithreaded();
+
+ /** Set the default Optimistic setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @param flag the default Optimistic setting.
+ */
+ void setOptimistic (boolean flag);
+
+ /** Get the default Optimistic setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @return the default Optimistic setting.
+ */
+ boolean getOptimistic();
+
+ /** Set the default RetainValues setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @param flag the default RetainValues setting.
+ */
+ void setRetainValues (boolean flag);
+
+ /** Get the default RetainValues setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @return the default RetainValues setting.
+ */
+ boolean getRetainValues ();
+
+ /** Set the default value for the RestoreValues property.
+ * If <code>true</code>, at rollback, fields of newly persistent instances
+ * are restored to
+ * their values as of the beginning of the transaction, and the instances
+ * revert to transient. Additionally, fields of modified
+ * instances of primitive types and immutable reference types
+ * are restored to their values as of the beginning of the
+ * transaction.
+ * <P>If <code>false</code>, at rollback, the values of fields of
+ * newly persistent instances are unchanged and the instances revert to
+ * transient. Additionally, dirty instances transition to hollow.
+ * If an implementation does not support this option, a
+ * <code>JDOUnsupportedOptionException</code> is thrown.
+ * @param restoreValues the value of the restoreValues property
+ */
+ void setRestoreValues(boolean restoreValues);
+
+ /** Get the default value for the RestoreValues property.
+ * @return the value of the restoreValues property
+ */
+ boolean getRestoreValues();
+
+ /** Set the default NontransactionalRead setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @param flag the default NontransactionalRead setting.
+ */
+ void setNontransactionalRead (boolean flag);
+
+ /** Get the default NontransactionalRead setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @return the default NontransactionalRead setting.
+ */
+ boolean getNontransactionalRead ();
+
+ /** Set the default NontransactionalWrite setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @param flag the default NontransactionalWrite setting.
+ */
+ void setNontransactionalWrite (boolean flag);
+
+ /** Get the default NontransactionalWrite setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @return the default NontransactionalWrite setting.
+ */
+ boolean getNontransactionalWrite ();
+
+ /** Set the default IgnoreCache setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @param flag the default IgnoreCache setting.
+ */
+ void setIgnoreCache (boolean flag);
+
+ /** Get the default IgnoreCache setting for all <code>PersistenceManager</code> instances
+ * obtained from this factory.
+ *
+ * @return the default IngoreCache setting.
+ */
+ boolean getIgnoreCache ();
+
+ /** Return non-configurable properties of this <code>PersistenceManagerFactory</code>.
+ * Properties with keys <code>VendorName</code> and <code>VersionNumber</code> are required. Other
+ * keys are optional.
+ * @return the non-configurable properties of this
+ * <code>PersistenceManagerFactory</code>.
+ */
+ Properties getProperties();
+
+ /** The application can determine from the results of this
+ * method which optional features, and which query languages
+ * are supported by the JDO implementation.
+ * <P>Each supported JDO optional feature is represented by a
+ * <code>String</code> with one of the following values:
+ *
+ * <P><code>javax.jdo.option.TransientTransactional
+ * <BR>javax.jdo.option.NontransactionalRead
+ * <BR>javax.jdo.option.NontransactionalWrite
+ * <BR>javax.jdo.option.RetainValues
+ * <BR>javax.jdo.option.Optimistic
+ * <BR>javax.jdo.option.ApplicationIdentity
+ * <BR>javax.jdo.option.DatastoreIdentity
+ * <BR>javax.jdo.option.NonDatastoreIdentity
+ * <BR>javax.jdo.option.ArrayList
+ * <BR>javax.jdo.option.HashMap
+ * <BR>javax.jdo.option.Hashtable
+ * <BR>javax.jdo.option.LinkedList
+ * <BR>javax.jdo.option.TreeMap
+ * <BR>javax.jdo.option.TreeSet
+ * <BR>javax.jdo.option.Vector
+ * <BR>javax.jdo.option.Map
+ * <BR>javax.jdo.option.List
+ * <BR>javax.jdo.option.Array
+ * <BR>javax.jdo.option.NullCollection
+ * <BR>javax.jdo.option.ChangeApplicationIdentity
+ * <BR>javax.jdo.option.BinaryCompatibility
+ * <BR>javax.jdo.option.GetDataStoreConnection
+ * <BR>javax.jdo.option.UnconstrainedQueryVariables
+ * <BR>javax.jdo.query.SQL
+ * <BR>javax.jdo.query.JDOQL
+ * </code>
+ *
+ *<P>The standard JDO query language is represented by a <code>String</code>:
+ *<P><code>javax.jdo.query.JDOQL</code>
+ * @return the <code>Collection</code> of <code>String</code>s representing the supported options.
+ */
+ Collection supportedOptions();
+
+ /**
+ * Return the {@link DataStoreCache} that this factory uses for
+ * controlling a second-level cache. If this factory does not use
+ * a second-level cache, the returned instance does nothing. This
+ * method never returns <code>null</code>.
+ * @since 2.0
+ */
+ DataStoreCache getDataStoreCache ();
+}
Added: incubator/jdo/trunk/api20/src/java/javax/jdo/Query.java
URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax/jdo/Query.java?view=auto&rev=159273
==============================================================================
--- incubator/jdo/trunk/api20/src/java/javax/jdo/Query.java (added)
+++ incubator/jdo/trunk/api20/src/java/javax/jdo/Query.java Mon Mar 28 10:25:05 2005
@@ -0,0 +1,448 @@
+/*
+ * Copyright 2005 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * Query.java
+ *
+ */
+
+package javax.jdo;
+import java.io.Serializable;
+import java.util.Collection;
+import java.util.Map;
+
+/** The <code>Query</code> interface allows applications to obtain persistent instances
+ * from the data store.
+ *
+ * The {@link PersistenceManager} is the factory for <code>Query</code> instances. There
+ * may be many <code>Query</code> instances associated with a <code>PersistenceManager</code>.
+ * Multiple queries might be executed simultaneously by different threads, but the
+ * implementation might choose to execute them serially. In either case, the
+ * implementation must be thread safe.
+ *
+ * <P>There are three required elements in a <code>Query</code>: the class of the results,
+ * the candidate collection of instances, and the filter.
+ *
+ * <P>There are optional elements: parameter declarations, variable
+ * declarations, import statements, and an ordering specification.
+ * <P>The query namespace is modeled after methods in Java:
+ * <ul>
+ * <li><code>setClass</code> corresponds to the class definition
+ * <li><code>declareParameters</code> corresponds to formal parameters of a method
+ * <li><code>declareVariables</code> corresponds to local variables of a method
+ * <li><code>setFilter</code> and <code>setOrdering</code> correspond to the method body
+ * </ul>
+ * <P>There are two namespaces in queries. Type names have their own
+ * namespace that is separate from the namespace for fields, variables
+ * and parameters.
+ * <P>The method <code>setClass</code> introduces the name of the candidate class in
+ * the type namespace. The method <code>declareImports</code> introduces the names of
+ * the imported class or interface types in the type namespace. Imported
+ * type names must be unique. When used (e.g. in a parameter declaration,
+ * cast expression, etc.) a type name must be the name of the candidate
+ * class, the name of a class or interface imported by method
+ * <code>declareImports</code>, or denote a class or interface from the same
+ * package as the candidate class.
+ * <P>The method <code>setClass</code> introduces the names of the candidate class fields.
+ * <P>The method <code>declareParameters</code> introduces the names of the
+ * parameters. A name introduced by <code>declareParameters</code> hides the name
+ * of a candidate class field if equal. Parameter names must be unique.
+ * <P>The method <code>declareVariables</code> introduces the names of the variables.
+ * A name introduced by <code>declareVariables</code> hides the name of a candidate
+ * class field if equal. Variable names must be unique and must not
+ * conflict with parameter names.
+ * <P>A hidden field may be accessed using the 'this' qualifier:
+ * <code>this.fieldName</code>.
+ * <P>The <code>Query</code> interface provides methods which execute the query
+ * based on the parameters given. They return a <code>Collection</code> which the
+ * user can iterate to get results. For future extension, the signature
+ * of the <code>execute</code> methods specifies that they return an <code>Object</code> which
+ * must be cast to <code>Collection</code> by the user.
+ * <P>Any parameters passed to the <code>execute</code> methods are used only for
+ * this execution, and are not remembered for future execution.
+ * @version 2.0
+ */
+
+public interface Query extends Serializable {
+
+ /**
+ * The string constant used as the first argument to {@link
+ * PersistenceManager#newQuery(String,Object)} to identify that
+ * the created query should obey the JDOQL syntax and semantic
+ * rules.
+ * <p>This is the default query language used when creating a
+ * query with any of the other {@link
+ * PersistenceManager#newQuery} methods, except {@link
+ * PersistenceManager#newQuery(Object)}, which uses the query
+ * language of the compiled query template object passed to that
+ * method.</p>
+ * @since 2.0
+ */
+ String JDOQL = "javax.jdo.query.JDOQL";
+
+ /**
+ * The string constant used as the first argument to {@link
+ * PersistenceManager#newQuery(String,Object)} to identify that
+ * the created query should use SQL semantics. This is only
+ * meaningful for relational JDO implementations.
+ * <p>If this is used, the <code>Object</code> argument to the
+ * {@link PersistenceManager#newQuery(String,Object)} method
+ * should be a <code>String</code> containing a SQL
+ * <code>SELECT</code> statement.</p>
+ * @since 2.0
+ */
+ String SQL = "javax.jdo.query.SQL";
+
+ /** Set the class of the candidate instances of the query.
+ * <P>The class specifies the class
+ * of the candidates of the query. Elements of the candidate collection
+ * that are of the specified class are filtered before being
+ * put into the result <code>Collection</code>.
+ *
+ * @param cls the <code>Class</code> of the candidate instances.
+ */
+ void setClass(Class cls);
+
+ /** Set the candidate <code>Extent</code> to query.
+ * @param pcs the candidate <code>Extent</code>.
+ */
+ void setCandidates(Extent pcs);
+
+ /** Set the candidate <code>Collection</code> to query.
+ * @param pcs the candidate <code>Collection</code>.
+ */
+ void setCandidates(Collection pcs);
+
+ /** Set the filter for the query.
+ *
+ * <P>The filter specification is a <code>String</code> containing a Boolean
+ * expression that is to be evaluated for each of the instances
+ * in the candidate collection. If the filter is not specified,
+ * then it defaults to "true", which has the effect of filtering
+ * the input <code>Collection</code> only for class type.
+ * <P>An element of the candidate collection is returned in the result if:
+ * <ul><li>it is assignment compatible to the candidate <code>Class</code> of the <code>Query</code>; and
+ * <li>for all variables there exists a value for which the filter
+ * expression evaluates to <code>true</code>.
+ * </ul>
+ * <P>The user may denote uniqueness in the filter expression by
+ * explicitly declaring an expression (for example, <code>e1 != e2</code>).
+ * <P>Rules for constructing valid expressions follow the Java
+ * language, except for these differences:
+ * <ul>
+ * <li>Equality and ordering comparisons between primitives and instances
+ * of wrapper classes are valid.
+ * <li>Equality and ordering comparisons of <code>Date</code> fields and <code>Date</code>
+ * parameters are valid.
+ * <li>White space (non-printing characters space, tab, carriage
+ * return, and line feed) is a separator and is otherwise ignored.
+ * <li>The assignment operators <code>=</code>, <code>+=</code>, etc. and pre- and post-increment
+ * and -decrement are not supported. Therefore, there are no side
+ * effects from evaluation of any expressions.
+ * <li>Methods, including object construction, are not supported, except
+ * for <code>Collection.contains(Object o)</code>, <code>Collection.isEmpty()</code>,
+ * <code>String.startsWith(String s)</code>, and <code>String.endsWith(String e)</code>.
+ * Implementations might choose to support non-mutating method
+ * calls as non-standard extensions.
+ * <li>Navigation through a <code>null</code>-valued field, which would throw
+ * <code>NullPointerException</code>, is treated as if the filter expression
+ * returned <code>false</code> for the evaluation of the current set of variable
+ * values. Other values for variables might still qualify the candidate
+ * instance for inclusion in the result set.
+ * <li>Navigation through multi-valued fields (<code>Collection</code> types) is
+ * specified using a variable declaration and the
+ * <code>Collection.contains(Object o)</code> method.
+ * </ul>
+ * <P>Identifiers in the expression are considered to be in the name
+ * space of the specified class, with the addition of declared imports,
+ * parameters and variables. As in the Java language, <code>this</code> is a reserved
+ * word which means the element of the collection being evaluated.
+ * <P>Navigation through single-valued fields is specified by the Java
+ * language syntax of <code>field_name.field_name....field_name</code>.
+ * <P>A JDO implementation is allowed to reorder the filter expression
+ * for optimization purposes.
+ * @param filter the query filter.
+ */
+ void setFilter(String filter);
+
+ /** Set the import statements to be used to identify the fully qualified name of
+ * variables or parameters. Parameters and unbound variables might
+ * come from a different class from the candidate class, and the names
+ * need to be declared in an import statement to eliminate ambiguity.
+ * Import statements are specified as a <code>String</code> with semicolon-separated
+ * statements.
+ * <P>The <code>String</code> parameter to this method follows the syntax of the
+ * import statement of the Java language.
+ * @param imports import statements separated by semicolons.
+ */
+ void declareImports(String imports);
+
+ /** Declare the list of parameters query execution.
+ *
+ * The parameter declaration is a <code>String</code> containing one or more query
+ * parameter declarations separated with commas. Each parameter named
+ * in the parameter declaration must be bound to a value when
+ * the query is executed.
+ * <P>The <code>String</code> parameter to this method follows the syntax for formal
+ * parameters in the Java language.
+ * @param parameters the list of parameters separated by commas.
+ */
+ void declareParameters(String parameters);
+
+ /** Declare the unbound variables to be used in the query. Variables
+ * might be used in the filter, and these variables must be declared
+ * with their type. The unbound variable declaration is a <code>String</code>
+ * containing one or more unbound variable declarations separated
+ * with semicolons. It follows the syntax for local variables in
+ * the Java language.
+ * @param variables the variables separated by semicolons.
+ */
+ void declareVariables(String variables);
+
+ /** Set the ordering specification for the result <code>Collection</code>. The
+ * ordering specification is a <code>String</code> containing one or more ordering
+ * declarations separated by commas.
+ *
+ * <P>Each ordering declaration is the name of the field on which
+ * to order the results followed by one of the following words:
+ * "<code>ascending</code>" or "<code>descending</code>".
+ *
+ *<P>The field must be declared in the candidate class or must be
+ * a navigation expression starting with a field in the candidate class.
+ *
+ *<P>Valid field types are primitive types except <code>boolean</code>; wrapper types
+ * except <code>Boolean</code>; <code>BigDecimal</code>; <code>BigInteger</code>;
+ * <code>String</code>; and <code>Date</code>.
+ * @param ordering the ordering specification.
+ */
+ void setOrdering(String ordering);
+
+ /** Set the ignoreCache option. The default value for this option was
+ * set by the <code>PersistenceManagerFactory</code> or the
+ * <code>PersistenceManager</code> used to create this <code>Query</code>.
+ *
+ * The ignoreCache option setting specifies whether the query should execute
+ * entirely in the back end, instead of in the cache. If this flag is set
+ * to <code>true</code>, an implementation might be able to optimize the query
+ * execution by ignoring changed values in the cache. For optimistic
+ * transactions, this can dramatically improve query response times.
+ * @param ignoreCache the setting of the ignoreCache option.
+ */
+ void setIgnoreCache(boolean ignoreCache);
+
+ /** Get the ignoreCache option setting.
+ * @return the ignoreCache option setting.
+ * @see #setIgnoreCache
+ */
+ boolean getIgnoreCache();
+
+ /** Verify the elements of the query and provide a hint to the query to
+ * prepare and optimize an execution plan.
+ */
+ void compile();
+
+ /** Execute the query and return the filtered Collection.
+ * @return the filtered <code>Collection</code>.
+ * @see #executeWithArray(Object[] parameters)
+ */
+ Object execute();
+
+ /** Execute the query and return the filtered <code>Collection</code>.
+ * @return the filtered <code>Collection</code>.
+ * @see #executeWithArray(Object[] parameters)
+ * @param p1 the value of the first parameter declared.
+ */
+ Object execute(Object p1);
+
+ /** Execute the query and return the filtered <code>Collection</code>.
+ * @return the filtered <code>Collection</code>.
+ * @see #executeWithArray(Object[] parameters)
+ * @param p1 the value of the first parameter declared.
+ * @param p2 the value of the second parameter declared.
+ */
+ Object execute(Object p1, Object p2);
+
+ /** Execute the query and return the filtered <code>Collection</code>.
+ * @return the filtered <code>Collection</code>.
+ * @see #executeWithArray(Object[] parameters)
+ * @param p1 the value of the first parameter declared.
+ * @param p2 the value of the second parameter declared.
+ * @param p3 the value of the third parameter declared.
+ */
+ Object execute(Object p1, Object p2, Object p3);
+
+ /** Execute the query and return the filtered <code>Collection</code>. The query
+ * is executed with the parameters set by the <code>Map</code> values. Each <code>Map</code> entry
+ * consists of a key which is the name of the parameter in the
+ * <code>declareParameters</code> method, and a value which is the value used in
+ * the <code>execute</code> method. The keys in the <code>Map</code> and the declared parameters
+ * must exactly match or a <code>JDOUserException</code> is thrown.
+ * @return the filtered <code>Collection</code>.
+ * @see #executeWithArray(Object[] parameters)
+ * @param parameters the <code>Map</code> containing all of the parameters.
+ */
+ Object executeWithMap (Map parameters);
+
+ /** Execute the query and return the filtered <code>Collection</code>.
+ *
+ * <P>The execution of the query obtains the values of the parameters and
+ * matches them against the declared parameters in order. The names
+ * of the declared parameters are ignored. The type of
+ * the declared parameters must match the type of the passed parameters,
+ * except that the passed parameters might need to be unwrapped to get
+ * their primitive values.
+ *
+ * <P>The filter, import, declared parameters, declared variables, and
+ * ordering statements are verified for consistency.
+ *
+ * <P>Each element in the candidate <code>Collection</code> is examined to see that it
+ * is assignment compatible to the <code>Class</code> of the query. It is then evaluated
+ * by the Boolean expression of the filter. The element passes the filter
+ * if there exist unique values for all variables for which the filter
+ * expression evaluates to <code>true</code>.
+ * @return the filtered <code>Collection</code>.
+ * @param parameters the <code>Object</code> array with all of the parameters.
+ */
+ Object executeWithArray (Object[] parameters);
+
+ /** Get the <code>PersistenceManager</code> associated with this <code>Query</code>.
+ *
+ * <P>If this <code>Query</code> was restored from a serialized form, it has no
+ * <code>PersistenceManager</code>, and this method returns <code>null</code>.
+ * @return the <code>PersistenceManager</code> associated with this <code>Query</code>.
+ */
+ PersistenceManager getPersistenceManager();
+
+ /** Close a query result and release any resources associated with it. The
+ * parameter is the return from <code>execute(...)</code> and might have iterators open on it.
+ * Iterators associated with the query result are invalidated: they return <code>false</code>
+ * to <code>hasNext()</code> and throw <code>NoSuchElementException</code> to <code>next()</code>.
+ * @param queryResult the result of <code>execute(...)</code> on this <code>Query</code> instance.
+ */
+ void close (Object queryResult);
+
+ /** Close all query results associated with this <code>Query</code> instance, and release all
+ * resources associated with them. The query results might have iterators open
+ * on them. Iterators associated with the query results are invalidated:
+ * they return <code>false</code> to <code>hasNext()</code> and throw
+ * <code>NoSuchElementException</code> to <code>next()</code>.
+ */
+ void closeAll ();
+
+ /**
+ * Set the grouping expressions, optionally including a "having"
+ * clause. When grouping is specified, each result expression
+ * must either be an expression contained in the grouping, or an
+ * aggregate evaluated once per group.
+ *
+ * @param group a comma-delimited list of expressions, optionally
+ * followed by the "having" keyword and a boolean expression
+ * @since 2.0
+ */
+ void setGrouping (String group);
+
+ /**
+ * Specify that only the first result of the query should be
+ * returned, rather than a collection. The execute method will
+ * return null if the query result size is 0.
+ * @since 2.0
+ */
+ void setUnique (boolean unique);
+
+ /**
+ * Configures what type of data this query should return. If this
+ * is unset or set to <code>null</code>, this query will return a
+ * list of the query's candidate class. Otherwise, this query
+ * will return aggregate function results and / or individual
+ * field values (projections).
+ * @param data a comma-delimited list of fields, functions on fields,
+ * or aggregate functions to return from this query
+ * @since 2.0
+ */
+ void setResult (String data);
+
+ /**
+ * Specify the type of object in which the result of invoking
+ * {@link #execute} or one of its siblings. The behavior of this
+ * method depends the nature of the query being executed. In
+ * particular, if used in conjunction with {@link #setResult},
+ * the argument to this method should be
+ * <code>Object[].class</code>, a class with bean-like setters
+ * for each of the items listed in the result specification, or a
+ * class with a method called <code>put</code> with two
+ * <code>Object</code> arguments.
+ * @since 2.0
+ */
+ void setResultClass (Class cls);
+
+ /**
+ * Set the range of results to return.
+ * @param fromIncl 0-based inclusive start index
+ * @param toExcl 0-based exclusive end index, or
+ * {@link Integer#MAX_VALUE} for no limit.
+ * @since 2.0
+ */
+ void setRange (long fromIncl, long toExcl);
+
+ /**
+ * Add a vendor-specific extension this query. The key and value
+ * are not standard.
+ * An implementation must ignore keys that are not recognized.
+ * @since 2.0
+ */
+ void addExtension (String key, Object value);
+
+ /**
+ * Set multiple extensions, or use null to clear extensions.
+ * Map keys and values are not standard.
+ * An implementation must ignore entries that are not recognized.
+ * @param extensions
+ * @see #addExtension
+ * @since 2.0
+ */
+ void setExtensions (Map extensions);
+
+ /**
+ * Returns the <code>FetchPlan</code> used by this
+ * <code>Query</code>. Mutations of the returned object will not
+ * cause this query's owning <code>PersistenceManager</code>'s
+ * <code>FetchPlan</code> to be mutated.
+ * @since 2.0
+ */
+ FetchPlan getFetchPlan ();
+
+ /**
+ * Deletes all the instances of the candidate class that pass the
+ * filter.
+ * @since 2.0
+ */
+ Object deletePersistentAll (Object[] parameters);
+
+ /**
+ * Deletes all the instances of the candidate class that pass the
+ * filter.
+ * @since 2.0
+ */
+ Object deletePersistentAll (Map parameters);
+
+ /**
+ * Deletes all the instances of the candidate class that pass the
+ * filter.
+ * @since 2.0
+ */
+ Object deletePersistentAll ();
+}
+
Added: incubator/jdo/trunk/api20/src/java/javax/jdo/Transaction.java
URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api20/src/java/javax/jdo/Transaction.java?view=auto&rev=159273
==============================================================================
--- incubator/jdo/trunk/api20/src/java/javax/jdo/Transaction.java (added)
+++ incubator/jdo/trunk/api20/src/java/javax/jdo/Transaction.java Mon Mar 28 10:25:05 2005
@@ -0,0 +1,190 @@
+/*
+ * Copyright 2005 The Apache Software Foundation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * Transaction.java
+ *
+ */
+
+package javax.jdo;
+import javax.transaction.Synchronization;
+
+/** The JDO <code>Transaction</code> interface provides for initiation and completion
+ * of transactions under user control.
+ * It is a sub-interface of the {@link PersistenceManager}
+ * that deals with options and transaction demarcation.
+ * <P>Transaction options include whether optimistic concurrency
+ * control should be used for the current transaction, whether instances
+ * may hold values in the cache outside transactions, and whether
+ * values should be retained in the cache after transaction completion. These
+ * options are valid for both managed and non-managed transactions.
+ *
+ * <P>Transaction initiation and completion methods have similar semantics to
+ * <code>javax.transaction.UserTransaction</code> when used outside a managed
+ * environment. When used in a managed environment, transaction initiation
+ * and completion methods may only be used with bean-managed transaction semantics.
+ * @version 2.0
+ */
+
+public interface Transaction
+{
+ /** Begin a transaction. The type of transaction is determined by the
+ * setting of the Optimistic flag.
+ * @see #setOptimistic
+ * @see #getOptimistic
+ * @throws JDOUserException if transactions are managed by a container
+ * in the managed environment, or if the transaction is already active.
+ */
+ void begin();
+
+ /** Commit the current transaction.
+ * @throws JDOUserException if transactions are managed by a container
+ * in the managed environment, or if the transaction is not active.
+ */
+ void commit();
+
+ /** Roll back the current transaction.
+ * @throws JDOUserException if transactions are managed by a container
+ * in the managed environment, or if the transaction is not active.
+ */
+ void rollback();
+
+ /** Returns whether there is a transaction currently active.
+ * @return <code>true</code> if the transaction is active.
+ */
+ boolean isActive();
+
+ /**
+ * Returns the rollback-only status of the transaction. When
+ * begun, the rollback-only status is false. Either the
+ * application or the JDO implementation may set this flag
+ * using setRollbackOnly.
+ * @return <code>true</code> if the transaction has been
+ * marked for rollback.
+ * @since 2.0
+ */
+ boolean getRollbackOnly();
+
+ /**
+ * Sets the rollback-only status of the transaction to <code>true</code>.
+ * After this flag is set to <code>true</code>, the transaction
+ * can no longer be committed, and any attempt to commit the
+ * transaction will throw <code>JDOUserException<code>.
+ * @since 2.0
+ */
+ void setRollbackOnly();
+
+ /** If <code>true</code>, allow persistent instances to be read without
+ * a transaction active.
+ * If an implementation does not support this option, a
+ * <code>JDOUnsupportedOptionException</code> is thrown.
+ * @param nontransactionalRead the value of the nontransactionalRead property
+ */
+ void setNontransactionalRead (boolean nontransactionalRead);
+
+ /** If <code>true</code>, allows persistent instances to be read without
+ * a transaction active.
+ * @return the value of the nontransactionalRead property
+ */
+ boolean getNontransactionalRead ();
+
+ /** If <code>true</code>, allow persistent instances to be written without
+ * a transaction active.
+ * If an implementation does not support this option, a
+ * <code>JDOUnsupportedOptionException</code> is thrown.
+ * @param nontransactionalWrite the value of the nontransactionalRead property
+ */
+ void setNontransactionalWrite (boolean nontransactionalWrite);
+
+ /** If <code>true</code>, allows persistent instances to be written without
+ * a transaction active.
+ * @return the value of the nontransactionalWrite property
+ */
+ boolean getNontransactionalWrite ();
+
+ /** If <code>true</code>, at commit instances retain their values and the instances
+ * transition to persistent-nontransactional.
+ * If an implementation does not support this option, a
+ * <code>JDOUnsupportedOptionException</code> is thrown.
+ * @param retainValues the value of the retainValues property
+ */
+ void setRetainValues(boolean retainValues);
+
+ /** If <code>true</code>, at commit time instances retain their field values.
+ * @return the value of the retainValues property
+ */
+ boolean getRetainValues();
+
+ /** If <code>true</code>, at rollback, fields of newly persistent instances
+ * are restored to
+ * their values as of the beginning of the transaction, and the instances
+ * revert to transient. Additionally, fields of modified
+ * instances of primitive types and immutable reference types
+ * are restored to their values as of the beginning of the
+ * transaction.
+ * <P>If <code>false</code>, at rollback, the values of fields of
+ * newly persistent instances are unchanged and the instances revert to
+ * transient. Additionally, dirty instances transition to hollow.
+ * If an implementation does not support this option, a
+ * <code>JDOUnsupportedOptionException</code> is thrown.
+ * @param restoreValues the value of the restoreValues property
+ */
+ void setRestoreValues(boolean restoreValues);
+
+ /** Return the current value of the restoreValues property.
+ * @return the value of the restoreValues property
+ */
+ boolean getRestoreValues();
+
+ /** Optimistic transactions do not hold data store locks until commit time.
+ * If an implementation does not support this option, a
+ * <code>JDOUnsupportedOptionException</code> is thrown.
+ * @param optimistic the value of the Optimistic flag.
+ */
+ void setOptimistic(boolean optimistic);
+
+ /** Optimistic transactions do not hold data store locks until commit time.
+ * @return the value of the Optimistic property.
+ */
+ boolean getOptimistic();
+
+ /** The user can specify a <code>Synchronization</code> instance to be notified on
+ * transaction completions. The <code>beforeCompletion</code> method is called prior
+ * to flushing instances to the data store.
+ *
+ * <P>The <code>afterCompletion</code> method is called after performing state
+ * transitions of persistent and transactional instances, following
+ * the data store commit or rollback operation.
+ * <P>Only one <code>Synchronization</code> instance can be registered with the
+ * <code>Transaction</code>. If the application requires more than one instance to
+ * receive synchronization callbacks, then the single application instance
+ * is responsible for managing them, and forwarding callbacks to them.
+ * @param sync the <code>Synchronization</code> instance to be notified; <code>null</code> for none
+ */
+ void setSynchronization(Synchronization sync);
+
+ /** The user-specified <code>Synchronization</code> instance for this <code>Transaction</code> instance.
+ * @return the user-specified <code>Synchronization</code> instance.
+ */
+ Synchronization getSynchronization();
+
+ /** The <code>Transaction</code> instance is always associated with exactly one
+ * <code>PersistenceManager</code>.
+ *
+ * @return the <code>PersistenceManager</code> for this <code>Transaction</code> instance
+ */
+ PersistenceManager getPersistenceManager();
+}
|