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 + * [EMAIL PROTECTED] 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 [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 + * [EMAIL PROTECTED] #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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 + * [EMAIL PROTECTED] #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 [EMAIL PROTECTED] + * JDOOptimisticVerificationException} is thrown. This exception + * contains a nested [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] + * 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 [EMAIL PROTECTED] + * PersistenceManager#newQuery} methods, except [EMAIL PROTECTED] + * 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 [EMAIL PROTECTED] + * 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 + * [EMAIL PROTECTED] 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 + * [EMAIL PROTECTED] #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 [EMAIL PROTECTED] #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 + * [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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(); +}
