Added: incubator/jdo/trunk/api11/src/java/javax/jdo/JDOUserException.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api11/src/java/javax/jdo/JDOUserException.java?view=auto&rev=158175 ============================================================================== --- incubator/jdo/trunk/api11/src/java/javax/jdo/JDOUserException.java (added) +++ incubator/jdo/trunk/api11/src/java/javax/jdo/JDOUserException.java Fri Mar 18 16:53:48 2005 @@ -0,0 +1,96 @@ +/* + * 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. + */ + +/* + * JDOUserException.java + * + * Created on March 8, 2000, 8:33 AM + */ + +package javax.jdo; + +/** This class represents user errors that can possibly be retried. + * + * @author Craig Russell + * @version 1.0 + */ +public class JDOUserException extends JDOCanRetryException { + + /** + * Constructs a new <code>JDOUserException</code> without a detail message. + */ + public JDOUserException() { + } + + + /** + * Constructs a new <code>JDOUserException</code> with the specified detail message. + * @param msg the detail message. + */ + public JDOUserException(String msg) { + super(msg); + } + + /** + * Constructs a new <code>JDOUserException</code> with the specified detail message + * and nested <code>Throwable</code>s. + * @param msg the detail message. + * @param nested the nested <code>Throwable[]</code>. + */ + public JDOUserException(String msg, Throwable[] nested) { + super(msg, nested); + } + + /** + * Constructs a new <code>JDOUserException</code> with the specified detail message + * and nested <code>Throwable</code>s. + * @param msg the detail message. + * @param nested the nested <code>Throwable</code>. + */ + public JDOUserException(String msg, Throwable nested) { + super(msg, nested); + } + + /** Constructs a new <code>JDOUserException</code> with the specified detail message + * and failed object. + * @param msg the detail message. + * @param failed the failed object. + */ + public JDOUserException(String msg, Object failed) { + super(msg, failed); + } + + /** Constructs a new <code>JDOUserException</code> with the specified detail message, + * nested <code>Throwable</code>s, and failed object. + * @param msg the detail message. + * @param nested the nested <code>Throwable[]</code>. + * @param failed the failed object. + */ + public JDOUserException(String msg, Throwable[] nested, Object failed) { + super(msg, nested, failed); + } + + /** Constructs a new <code>JDOUserException</code> with the specified detail message, + * nested <code>Throwable</code>s, and failed object. + * @param msg the detail message. + * @param nested the nested <code>Throwable</code>. + * @param failed the failed object. + */ + public JDOUserException(String msg, Throwable nested, Object failed) { + super(msg, nested, failed); + } +} +
Added: incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManager.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManager.java?view=auto&rev=158175 ============================================================================== --- incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManager.java (added) +++ incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManager.java Fri Mar 18 16:53:48 2005 @@ -0,0 +1,596 @@ +/* + * 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 + * + * Created on February 25, 2000 + */ + +package javax.jdo; +import java.util.Collection; +import java.lang.Class; + +/** <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. + * @author Craig Russell + * @version 1.0.1 + */ + +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 (); + + /** 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 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); + + /** 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); + + /** 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); + + /** 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 <code>Class</code> + * and <code>String</code> arguments. The <code>String</code> argument might have been the + * result of executing <code>toString</code> on an object id instance. + * @param pcClass the <code>Class</code> of the persistence-capable instance + * @param str the <code>String</code> form of the object id + * @return an instance of the object identity class + */ + Object newObjectIdInstance (Class pcClass, String str); + + /** 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(); + } Added: incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManagerFactory.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManagerFactory.java?view=auto&rev=158175 ============================================================================== --- incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManagerFactory.java (added) +++ incubator/jdo/trunk/api11/src/java/javax/jdo/PersistenceManagerFactory.java Fri Mar 18 16:53:48 2005 @@ -0,0 +1,328 @@ +/* + * 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 + * + * Created on February 25, 2000 + */ + +package javax.jdo; + +import java.util.Properties; +import java.util.Collection; + +/** 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. + * + * @author Craig Russell + * @version 1.0.1 + */ + +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</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(); + +} Added: incubator/jdo/trunk/api11/src/java/javax/jdo/Query.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api11/src/java/javax/jdo/Query.java?view=auto&rev=158175 ============================================================================== --- incubator/jdo/trunk/api11/src/java/javax/jdo/Query.java (added) +++ incubator/jdo/trunk/api11/src/java/javax/jdo/Query.java Fri Mar 18 16:53:48 2005 @@ -0,0 +1,313 @@ +/* + * 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. + */ + +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. + * @author Craig Russell + * @version 1.0 + */ + +public interface Query extends Serializable +{ + /** 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 (); +} + Added: incubator/jdo/trunk/api11/src/java/javax/jdo/Transaction.java URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api11/src/java/javax/jdo/Transaction.java?view=auto&rev=158175 ============================================================================== --- incubator/jdo/trunk/api11/src/java/javax/jdo/Transaction.java (added) +++ incubator/jdo/trunk/api11/src/java/javax/jdo/Transaction.java Fri Mar 18 16:53:48 2005 @@ -0,0 +1,175 @@ +/* + * 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 + * + * Created on February 25, 2000 + */ + +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 completion methods have the same semantics as + * <code>javax.transaction.UserTransaction</code>, and are valid only in the + * non-managed, non-distributed transaction environment. + * <P>For operation in the distributed environment, <code>Transaction</code> is declared + * to implement <code>javax.transaction.Synchronization</code>. This allows for + * flushing the cache to the data store during externally managed + * transaction completion. + * @author Craig Russell + * @version 1.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(); + + /** 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(); +} Added: incubator/jdo/trunk/api11/src/java/javax/jdo/package.html URL: http://svn.apache.org/viewcvs/incubator/jdo/trunk/api11/src/java/javax/jdo/package.html?view=auto&rev=158175 ============================================================================== --- incubator/jdo/trunk/api11/src/java/javax/jdo/package.html (added) +++ incubator/jdo/trunk/api11/src/java/javax/jdo/package.html Fri Mar 18 16:53:48 2005 @@ -0,0 +1,90 @@ +<!-- + 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. +--> + +<html> +<head> +<title>JDO package</title> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +</head> + +<body bgcolor="#FFFFFF"> +This package contains the JDO specification interfaces and classes. +<P>There are two major objectives of the JDO architecture: +first, to provide application programmers a transparent, +Java-centric view of persistent information, including enterprise data +and locally stored data; and second, to enable pluggable implementations +of data stores into +application servers. Data stored in data stores is presented as +instances of persistence-capable classes. +<P>JDO defines interfaces and classes to be used by application programmers +when using classes whose instances are to be stored in persistent storage +(persistence-capable classes), and specifies the contracts between +suppliers of persistence-capable classes and the +runtime environment (which is part of the JDO implementation). +<P>The JDO architecture defines a standard set of contracts between an +application programmer and an JDO vendor. These contracts focus on the +view of the Java instances of persistence capable classes. +<P>The JDO PersistenceManagerFactory is the boostrap class for a JDO +application. The application gets an instance of the +PersistenceManagerFactory by construction or via JDNI lookup. +<P>The application acquires an instance of the JDO PersistenceManager by +calling the getPersistenceManager method on an instance of JDO +PersistenceManagerFactory. +<P>The JDO PersistenceManager is the primary interface for JDO-aware +application components: +<ul> +<li>it gives access to the current Transaction interface; +<li>it is the factory for the Query interface; +<li>it contains methods for managing the life cycle of persistent instances. +</ul> +<P>A JDO PersistenceManager instance supports any number of JDO instances +at a time. It is responsible for managing the identity of its +associated JDO instances. A JDO instance is associated with either +zero or one JDO PersistenceManager. It will be zero if and only if the +JDO instance is transient nontransactional. As soon as the instance is made persistent +or transactional, it will be associated with exactly one JDO PersistenceManager. +<P>A JDO PersistenceManager instance supports one transaction at a time, +and uses one connection to the underlying data source at a time. The JDO +PersistenceManager instance might use multiple transactions serially, +and might use multiple connections serially. +<P>Normally, cache management is automatic and transparent. When instances +are queried, navigated to, or modified, instantiation of instances and +their fields and garbage collection of unreferenced instances occurs +without any explicit control. When the transaction in which persistent +instances are created, deleted, or modified commits, eviction is +automatically done by the transaction completion mechanisms. +<P>Operations on persistent JDO instances at the user's choice might be +performed in the context of a transaction. That is, the view of data +in the data store is transactionally consistent, according to the +standard definition of ACID transactions. +<P>The Transaction interface is used to mark the beginning and end of a +application-defined unit of work. The PersistenceManager allows the +application to get the instance that manages these transactional +boundaries via the currentTransaction method. +<P>The persistent manager instance is a factory for query instances, +and queries are executed in the context of the persistent manager instance. +The actual query execution might be performed by the JDO PersistenceManager +or might be delegated by the JDO PersistenceManager to its data store. +The actual query executed thus might be implemented in a very different +language from Java, and might be optimized to take advantage of particular +query language implementations. +<P>Extents are collections of data store objects managed by the data store, +not by explicit user operations on collections. Extent capability is a +boolean property of classes that are persistence capable. If an instance +of a class that has a managed extent is made persistent via reachability, +the instance is put into the extent implicitly. +</body> +</html>
