db-jdo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From c..@apache.org
Subject svn commit: r159273 [2/5] - in incubator/jdo/trunk/api20: ./ src/java/ src/java/javax/ src/java/javax/jdo/ src/java/javax/jdo/datastore/ src/java/javax/jdo/identity/ src/java/javax/jdo/listener/ src/java/javax/jdo/spi/ test/ test/java/ test/java/javax/ test/java/javax/jdo/ test/java/javax/jdo/identity/ test/java/javax/jdo/listener/
Date Mon, 28 Mar 2005 18:25:16 GMT
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();
+}



Mime
View raw message