db-jdo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From m..@apache.org
Subject svn commit: r158175 [2/4] - in incubator/jdo/trunk/api11: ./ src/ src/dtd/ src/dtd/javax/ src/dtd/javax/jdo/ src/java/ src/java/javax/ src/java/javax/jdo/ src/java/javax/jdo/spi/ test/ test/java/ test/java/javax/ test/java/javax/jdo/ test/java/javax/jdo/pc/ test/java/javax/jdo/spi/ test/java/javax/jdo/util/ xdocs/
Date Sat, 19 Mar 2005 00:53:55 GMT
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
+ * {@link 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 {@link PersistenceManager} is the factory for <code>Query</code> instances.  There
+ * may be many <code>Query</code> instances associated with a <code>PersistenceManager</code>.
+ * Multiple queries might be executed simultaneously by different threads, but the
+ * implementation might choose to execute them serially.  In either case, the
+ * implementation must be thread safe.
+ *
+ * <P>There are three required elements in a <code>Query</code>: the class of the results,
+ * the candidate collection of instances, and the filter.
+ *
+ * <P>There are optional elements: parameter declarations, variable
+ * declarations, import statements, and an ordering specification.
+ * <P>The query namespace is modeled after methods in Java:
+ * <ul>
+ * <li><code>setClass</code> corresponds to the class definition
+ * <li><code>declareParameters</code> corresponds to formal parameters of a method
+ * <li><code>declareVariables</code> corresponds to local variables of a method
+ * <li><code>setFilter</code> and <code>setOrdering</code> correspond to the method body
+ * </ul>
+ * <P>There are two namespaces in queries. Type names have their own
+ * namespace that is separate from the namespace for fields, variables
+ * and parameters.
+ * <P>The method <code>setClass</code> introduces the name of the candidate class in
+ * the type namespace. The method <code>declareImports</code> introduces the names of
+ * the imported class or interface types in the type namespace. Imported
+ * type names must be unique. When used (e.g. in a parameter declaration,
+ * cast expression, etc.) a type name must be the name of the candidate
+ * class, the name of a class or interface imported by method
+ * <code>declareImports</code>, or denote a class or interface from the same
+ * package as the candidate class.
+ * <P>The method <code>setClass</code> introduces the names of the candidate class fields.
+ * <P>The method <code>declareParameters</code> introduces the names of the
+ * parameters. A name introduced by <code>declareParameters</code> hides the name
+ * of a candidate class field if equal. Parameter names must be unique.
+ * <P>The method <code>declareVariables</code> introduces the names of the variables.
+ * A name introduced by <code>declareVariables</code> hides the name of a candidate
+ * class field if equal. Variable names must be unique and must not
+ * conflict with parameter names.
+ * <P>A hidden field may be accessed using the 'this' qualifier:
+ * <code>this.fieldName</code>.
+ * <P>The <code>Query</code> interface provides methods which execute the query
+ * based on the parameters given. They return a <code>Collection</code> which the
+ * user can iterate to get results. For future extension, the signature
+ * of the <code>execute</code> methods specifies that they return an <code>Object</code> which
+ * must be cast to <code>Collection</code> by the user.
+ * <P>Any parameters passed to the <code>execute</code> methods are used only for
+ * this execution, and are not remembered for future execution.
+ * @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 {@link PersistenceManager}
+ * that deals with options and transaction demarcation. 
+ * <P>Transaction options include whether optimistic concurrency
+ * control should be used for the current transaction, whether instances
+ * may hold values in the cache outside transactions, and whether
+ * values should be retained in the cache after transaction completion.  These
+ * options are valid for both managed and non-managed transactions.
+ *
+ * <P>Transaction 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>



Mime
View raw message