Return-Path: Delivered-To: apmail-db-jdo-commits-archive@www.apache.org Received: (qmail 46022 invoked from network); 14 Oct 2005 05:10:11 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 14 Oct 2005 05:10:11 -0000 Received: (qmail 67397 invoked by uid 500); 14 Oct 2005 05:10:08 -0000 Mailing-List: contact jdo-commits-help@db.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: jdo-dev@db.apache.org Delivered-To: mailing list jdo-commits@db.apache.org Received: (qmail 66621 invoked by uid 99); 14 Oct 2005 05:09:07 -0000 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME,UPPERCASE_25_50 X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Thu, 13 Oct 2005 22:07:46 -0700 Received: (qmail 45082 invoked by uid 65534); 14 Oct 2005 05:07:26 -0000 Message-ID: <20051014050726.45081.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r321004 [8/50] - in /incubator/jdo/site: ./ docs/ docs/api11/ docs/api11/apidocs/ docs/api11/apidocs/javax/ docs/api11/apidocs/javax/jdo/ docs/api11/apidocs/javax/jdo/class-use/ docs/api11/apidocs/javax/jdo/spi/ docs/api11/apidocs/javax/jdo... Date: Fri, 14 Oct 2005 05:06:34 -0000 To: jdo-commits@db.apache.org From: clr@apache.org X-Mailer: svnmailer-1.0.5 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Added: incubator/jdo/site/docs/api11/apidocs/javax/jdo/PersistenceManagerFactory.html URL: http://svn.apache.org/viewcvs/incubator/jdo/site/docs/api11/apidocs/javax/jdo/PersistenceManagerFactory.html?rev=321004&view=auto ============================================================================== --- incubator/jdo/site/docs/api11/apidocs/javax/jdo/PersistenceManagerFactory.html (added) +++ incubator/jdo/site/docs/api11/apidocs/javax/jdo/PersistenceManagerFactory.html Thu Oct 13 22:05:52 2005 @@ -0,0 +1,1165 @@ + + + + + + + +PersistenceManagerFactory (JDO1 API 1.1) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+ +

+ +javax.jdo +
+Interface PersistenceManagerFactory

+
+
All Superinterfaces:
java.io.Serializable
+
+
+
+
public interface PersistenceManagerFactory
extends java.io.Serializable
+ +

+The PersistenceManagerFactory is the interface to use to obtain + PersistenceManager instances. All PersistenceManager instances obtained + from the same PersistenceManagerFactory will have the same default + properties. + +

PersistenceManagerFactory 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. + +

Once the first PersistenceManager is obtained from the + PersistenceManagerFactory, the factory can no longer be configured. +

If the ConnectionFactory property is set (non-null) then + all other Connection properties including ConnectionFactoryName are ignored; + otherwise, if ConnectionFactoryName is set (non-null) then + all other Connection properties are ignored. + Similarly, if the ConnectionFactory2 property is set (non-null) then + ConnectionFactory2Name is ignored. +

Operational state (PersistenceManager pooling, connection pooling, + operational parameters) must not be serialized. +

+ +

+

+
Version:
+
1.0.1
+
Author:
+
Craig Russell
+
+
+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Method Summary
+ voidclose() + +
+          Close this PersistenceManagerFactory.
+ java.lang.StringgetConnectionDriverName() + +
+          Get the driver name for the data store connection.
+ java.lang.ObjectgetConnectionFactory() + +
+          Get the data store connection factory.
+ java.lang.ObjectgetConnectionFactory2() + +
+          Get the second data store connection factory.
+ java.lang.StringgetConnectionFactory2Name() + +
+          Get the name for the second data store connection factory.
+ java.lang.StringgetConnectionFactoryName() + +
+          Get the name for the data store connection factory.
+ java.lang.StringgetConnectionURL() + +
+          Get the URL for the data store connection.
+ java.lang.StringgetConnectionUserName() + +
+          Get the user name for the data store connection.
+ booleangetIgnoreCache() + +
+          Get the default IgnoreCache setting for all PersistenceManager instances + obtained from this factory.
+ booleangetMultithreaded() + +
+          Get the default Multithreaded setting for all PersistenceManager instances + obtained from this factory.
+ booleangetNontransactionalRead() + +
+          Get the default NontransactionalRead setting for all PersistenceManager instances + obtained from this factory.
+ booleangetNontransactionalWrite() + +
+          Get the default NontransactionalWrite setting for all PersistenceManager instances + obtained from this factory.
+ booleangetOptimistic() + +
+          Get the default Optimistic setting for all PersistenceManager instances + obtained from this factory.
+ PersistenceManagergetPersistenceManager() + +
+          Get an instance of PersistenceManager from this factory.
+ PersistenceManagergetPersistenceManager(java.lang.String userid, + java.lang.String password) + +
+          Get an instance of PersistenceManager from this factory.
+ java.util.PropertiesgetProperties() + +
+          Return non-configurable properties of this PersistenceManagerFactory.
+ booleangetRestoreValues() + +
+          Get the default value for the RestoreValues property.
+ booleangetRetainValues() + +
+          Get the default RetainValues setting for all PersistenceManager instances + obtained from this factory.
+ voidsetConnectionDriverName(java.lang.String driverName) + +
+          Set the driver name for the data store connection.
+ voidsetConnectionFactory(java.lang.Object connectionFactory) + +
+          Set the data store connection factory.
+ voidsetConnectionFactory2(java.lang.Object connectionFactory) + +
+          Set the second data store connection factory.
+ voidsetConnectionFactory2Name(java.lang.String connectionFactoryName) + +
+          Set the name for the second data store connection factory.
+ voidsetConnectionFactoryName(java.lang.String connectionFactoryName) + +
+          Set the name for the data store connection factory.
+ voidsetConnectionPassword(java.lang.String password) + +
+          Set the password for the data store connection.
+ voidsetConnectionURL(java.lang.String URL) + +
+          Set the URL for the data store connection.
+ voidsetConnectionUserName(java.lang.String userName) + +
+          Set the user name for the data store connection.
+ voidsetIgnoreCache(boolean flag) + +
+          Set the default IgnoreCache setting for all PersistenceManager instances + obtained from this factory.
+ voidsetMultithreaded(boolean flag) + +
+          Set the default Multithreaded setting for all PersistenceManager instances + obtained from this factory.
+ voidsetNontransactionalRead(boolean flag) + +
+          Set the default NontransactionalRead setting for all PersistenceManager instances + obtained from this factory.
+ voidsetNontransactionalWrite(boolean flag) + +
+          Set the default NontransactionalWrite setting for all PersistenceManager instances + obtained from this factory.
+ voidsetOptimistic(boolean flag) + +
+          Set the default Optimistic setting for all PersistenceManager instances + obtained from this factory.
+ voidsetRestoreValues(boolean restoreValues) + +
+          Set the default value for the RestoreValues property.
+ voidsetRetainValues(boolean flag) + +
+          Set the default RetainValues setting for all PersistenceManager instances + obtained from this factory.
+ java.util.CollectionsupportedOptions() + +
+          The application can determine from the results of this + method which optional features, and which query languages + are supported by the JDO implementation.
+  +

+ + + + + + + + + + + + + + +
+Method Detail
+ +

+close

+
+public void close()
+
+
Close this PersistenceManagerFactory. Check for + JDOPermission("closePersistenceManagerFactory") and if not authorized, + throw SecurityException. +

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. +

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
+
+
+
+
+ +

+getPersistenceManager

+
+public PersistenceManager getPersistenceManager()
+
+
Get an instance of PersistenceManager from this factory. The instance has + default values for options. + +

After the first use of getPersistenceManager, no "set" methods will + succeed. +

+

+
+
+
+ +
Returns:
a PersistenceManager instance with default options.
+
+
+
+ +

+getPersistenceManager

+
+public PersistenceManager getPersistenceManager(java.lang.String userid,
+                                                java.lang.String password)
+
+
Get an instance of PersistenceManager from this factory. The instance has + default values for options. The parameters userid and password are used + when obtaining datastore connections from the connection pool. + +

After the first use of getPersistenceManager, no "set" methods will + succeed. +

+

+
+
+
+
Parameters:
userid - the userid for the connection
password - the password for the connection +
Returns:
a PersistenceManager instance with default options.
+
+
+
+ +

+setConnectionUserName

+
+public void setConnectionUserName(java.lang.String userName)
+
+
Set the user name for the data store connection. +

+

+
+
+
+
Parameters:
userName - the user name for the data store connection.
+
+
+
+ +

+getConnectionUserName

+
+public java.lang.String getConnectionUserName()
+
+
Get the user name for the data store connection. +

+

+
+
+
+ +
Returns:
the user name for the data store connection.
+
+
+
+ +

+setConnectionPassword

+
+public void setConnectionPassword(java.lang.String password)
+
+
Set the password for the data store connection. +

+

+
+
+
+
Parameters:
password - the password for the data store connection.
+
+
+
+ +

+setConnectionURL

+
+public void setConnectionURL(java.lang.String URL)
+
+
Set the URL for the data store connection. +

+

+
+
+
+
Parameters:
URL - the URL for the data store connection.
+
+
+
+ +

+getConnectionURL

+
+public java.lang.String getConnectionURL()
+
+
Get the URL for the data store connection. +

+

+
+
+
+ +
Returns:
the URL for the data store connection.
+
+
+
+ +

+setConnectionDriverName

+
+public void setConnectionDriverName(java.lang.String driverName)
+
+
Set the driver name for the data store connection. +

+

+
+
+
+
Parameters:
driverName - the driver name for the data store connection.
+
+
+
+ +

+getConnectionDriverName

+
+public java.lang.String getConnectionDriverName()
+
+
Get the driver name for the data store connection. +

+

+
+
+
+ +
Returns:
the driver name for the data store connection.
+
+
+
+ +

+setConnectionFactoryName

+
+public void setConnectionFactoryName(java.lang.String connectionFactoryName)
+
+
Set the name for the data store connection factory. +

+

+
+
+
+
Parameters:
connectionFactoryName - the name of the data store connection factory.
+
+
+
+ +

+getConnectionFactoryName

+
+public java.lang.String getConnectionFactoryName()
+
+
Get the name for the data store connection factory. +

+

+
+
+
+ +
Returns:
the name of the data store connection factory.
+
+
+
+ +

+setConnectionFactory

+
+public void setConnectionFactory(java.lang.Object connectionFactory)
+
+
Set the data store connection factory. JDO implementations + will support specific connection factories. The connection + factory interfaces are not part of the JDO specification. +

+

+
+
+
+
Parameters:
connectionFactory - the data store connection factory.
+
+
+
+ +

+getConnectionFactory

+
+public java.lang.Object getConnectionFactory()
+
+
Get the data store connection factory. +

+

+
+
+
+ +
Returns:
the data store connection factory.
+
+
+
+ +

+setConnectionFactory2Name

+
+public void setConnectionFactory2Name(java.lang.String connectionFactoryName)
+
+
Set the name for the second data store connection factory. This is + needed for managed environments to get nontransactional connections for + optimistic transactions. +

+

+
+
+
+
Parameters:
connectionFactoryName - the name of the data store connection factory.
+
+
+
+ +

+getConnectionFactory2Name

+
+public java.lang.String getConnectionFactory2Name()
+
+
Get the name for the second data store connection factory. This is + needed for managed environments to get nontransactional connections for + optimistic transactions. +

+

+
+
+
+ +
Returns:
the name of the data store connection factory.
+
+
+
+ +

+setConnectionFactory2

+
+public void setConnectionFactory2(java.lang.Object connectionFactory)
+
+
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. +

+

+
+
+
+
Parameters:
connectionFactory - the data store connection factory.
+
+
+
+ +

+getConnectionFactory2

+
+public java.lang.Object getConnectionFactory2()
+
+
Get the second data store connection factory. This is + needed for managed environments to get nontransactional connections for + optimistic transactions. +

+

+
+
+
+ +
Returns:
the data store connection factory.
+
+
+
+ +

+setMultithreaded

+
+public void setMultithreaded(boolean flag)
+
+
Set the default Multithreaded setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+
Parameters:
flag - the default Multithreaded setting.
+
+
+
+ +

+getMultithreaded

+
+public boolean getMultithreaded()
+
+
Get the default Multithreaded setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+ +
Returns:
the default Multithreaded setting.
+
+
+
+ +

+setOptimistic

+
+public void setOptimistic(boolean flag)
+
+
Set the default Optimistic setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+
Parameters:
flag - the default Optimistic setting.
+
+
+
+ +

+getOptimistic

+
+public boolean getOptimistic()
+
+
Get the default Optimistic setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+ +
Returns:
the default Optimistic setting.
+
+
+
+ +

+setRetainValues

+
+public void setRetainValues(boolean flag)
+
+
Set the default RetainValues setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+
Parameters:
flag - the default RetainValues setting.
+
+
+
+ +

+getRetainValues

+
+public boolean getRetainValues()
+
+
Get the default RetainValues setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+ +
Returns:
the default RetainValues setting.
+
+
+
+ +

+setRestoreValues

+
+public void setRestoreValues(boolean restoreValues)
+
+
Set the default value for the RestoreValues property. + If true, 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. +

If false, 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 + JDOUnsupportedOptionException is thrown. +

+

+
+
+
+
Parameters:
restoreValues - the value of the restoreValues property
+
+
+
+ +

+getRestoreValues

+
+public boolean getRestoreValues()
+
+
Get the default value for the RestoreValues property. +

+

+
+
+
+ +
Returns:
the value of the restoreValues property
+
+
+
+ +

+setNontransactionalRead

+
+public void setNontransactionalRead(boolean flag)
+
+
Set the default NontransactionalRead setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+
Parameters:
flag - the default NontransactionalRead setting.
+
+
+
+ +

+getNontransactionalRead

+
+public boolean getNontransactionalRead()
+
+
Get the default NontransactionalRead setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+ +
Returns:
the default NontransactionalRead setting.
+
+
+
+ +

+setNontransactionalWrite

+
+public void setNontransactionalWrite(boolean flag)
+
+
Set the default NontransactionalWrite setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+
Parameters:
flag - the default NontransactionalWrite setting.
+
+
+
+ +

+getNontransactionalWrite

+
+public boolean getNontransactionalWrite()
+
+
Get the default NontransactionalWrite setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+ +
Returns:
the default NontransactionalWrite setting.
+
+
+
+ +

+setIgnoreCache

+
+public void setIgnoreCache(boolean flag)
+
+
Set the default IgnoreCache setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+
Parameters:
flag - the default IgnoreCache setting.
+
+
+
+ +

+getIgnoreCache

+
+public boolean getIgnoreCache()
+
+
Get the default IgnoreCache setting for all PersistenceManager instances + obtained from this factory. +

+

+
+
+
+ +
Returns:
the default IngoreCache setting.
+
+
+
+ +

+getProperties

+
+public java.util.Properties getProperties()
+
+
Return non-configurable properties of this PersistenceManagerFactory. + Properties with keys VendorName and VersionNumber are required. Other + keys are optional. +

+

+
+
+
+ +
Returns:
the non-configurable properties of this + PersistenceManagerFactory.
+
+
+
+ +

+supportedOptions

+
+public java.util.Collection supportedOptions()
+
+
The application can determine from the results of this + method which optional features, and which query languages + are supported by the JDO implementation. +

Each supported JDO optional feature is represented by a + String with one of the following values: + +

javax.jdo.option.TransientTransactional +
javax.jdo.option.NontransactionalRead +
javax.jdo.option.NontransactionalWrite +
javax.jdo.option.RetainValues +
javax.jdo.option.Optimistic +
javax.jdo.option.ApplicationIdentity +
javax.jdo.option.DatastoreIdentity +
javax.jdo.option.NonDatastoreIdentity +
javax.jdo.option.ArrayList +
javax.jdo.option.HashMap +
javax.jdo.option.Hashtable +
javax.jdo.option.LinkedList +
javax.jdo.option.TreeMap +
javax.jdo.option.TreeSet +
javax.jdo.option.Vector +
javax.jdo.option.Map +
javax.jdo.option.List +
javax.jdo.option.Array +
javax.jdo.option.NullCollection + +

The standard JDO query language is represented by a String: +

javax.jdo.query.JDOQL +

+

+
+
+
+ +
Returns:
the Collection of Strings representing the supported options.
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+Copyright © 2005 Apache Software Foundation. All Rights Reserved. + + Added: incubator/jdo/site/docs/api11/apidocs/javax/jdo/Query.html URL: http://svn.apache.org/viewcvs/incubator/jdo/site/docs/api11/apidocs/javax/jdo/Query.html?rev=321004&view=auto ============================================================================== --- incubator/jdo/site/docs/api11/apidocs/javax/jdo/Query.html (added) +++ incubator/jdo/site/docs/api11/apidocs/javax/jdo/Query.html Thu Oct 13 22:05:52 2005 @@ -0,0 +1,875 @@ + + + + + + + +Query (JDO1 API 1.1) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+ +

+ +javax.jdo +
+Interface Query

+
+
All Superinterfaces:
java.io.Serializable
+
+
+
+
public interface Query
extends java.io.Serializable
+ +

+The Query interface allows applications to obtain persistent instances + from the data store. + + The PersistenceManager is the factory for Query instances. There + may be many Query instances associated with a PersistenceManager. + 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. + +

There are three required elements in a Query: the class of the results, + the candidate collection of instances, and the filter. + +

There are optional elements: parameter declarations, variable + declarations, import statements, and an ordering specification. +

The query namespace is modeled after methods in Java: +

    +
  • setClass corresponds to the class definition +
  • declareParameters corresponds to formal parameters of a method +
  • declareVariables corresponds to local variables of a method +
  • setFilter and setOrdering correspond to the method body +
+

There are two namespaces in queries. Type names have their own + namespace that is separate from the namespace for fields, variables + and parameters. +

The method setClass introduces the name of the candidate class in + the type namespace. The method declareImports 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 + declareImports, or denote a class or interface from the same + package as the candidate class. +

The method setClass introduces the names of the candidate class fields. +

The method declareParameters introduces the names of the + parameters. A name introduced by declareParameters hides the name + of a candidate class field if equal. Parameter names must be unique. +

The method declareVariables introduces the names of the variables. + A name introduced by declareVariables hides the name of a candidate + class field if equal. Variable names must be unique and must not + conflict with parameter names. +

A hidden field may be accessed using the 'this' qualifier: + this.fieldName. +

The Query interface provides methods which execute the query + based on the parameters given. They return a Collection which the + user can iterate to get results. For future extension, the signature + of the execute methods specifies that they return an Object which + must be cast to Collection by the user. +

Any parameters passed to the execute methods are used only for + this execution, and are not remembered for future execution. +

+ +

+

+
Version:
+
1.0
+
Author:
+
Craig Russell
+
+
+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Method Summary
+ voidclose(java.lang.Object queryResult) + +
+          Close a query result and release any resources associated with it.
+ voidcloseAll() + +
+          Close all query results associated with this Query instance, and release all + resources associated with them.
+ voidcompile() + +
+          Verify the elements of the query and provide a hint to the query to + prepare and optimize an execution plan.
+ voiddeclareImports(java.lang.String imports) + +
+          Set the import statements to be used to identify the fully qualified name of + variables or parameters.
+ voiddeclareParameters(java.lang.String parameters) + +
+          Declare the list of parameters query execution.
+ voiddeclareVariables(java.lang.String variables) + +
+          Declare the unbound variables to be used in the query.
+ java.lang.Objectexecute() + +
+          Execute the query and return the filtered Collection.
+ java.lang.Objectexecute(java.lang.Object p1) + +
+          Execute the query and return the filtered Collection.
+ java.lang.Objectexecute(java.lang.Object p1, + java.lang.Object p2) + +
+          Execute the query and return the filtered Collection.
+ java.lang.Objectexecute(java.lang.Object p1, + java.lang.Object p2, + java.lang.Object p3) + +
+          Execute the query and return the filtered Collection.
+ java.lang.ObjectexecuteWithArray(java.lang.Object[] parameters) + +
+          Execute the query and return the filtered Collection.
+ java.lang.ObjectexecuteWithMap(java.util.Map parameters) + +
+          Execute the query and return the filtered Collection.
+ booleangetIgnoreCache() + +
+          Get the ignoreCache option setting.
+ PersistenceManagergetPersistenceManager() + +
+          Get the PersistenceManager associated with this Query.
+ voidsetCandidates(java.util.Collection pcs) + +
+          Set the candidate Collection to query.
+ voidsetCandidates(Extent pcs) + +
+          Set the candidate Extent to query.
+ voidsetClass(java.lang.Class cls) + +
+          Set the class of the candidate instances of the query.
+ voidsetFilter(java.lang.String filter) + +
+          Set the filter for the query.
+ voidsetIgnoreCache(boolean ignoreCache) + +
+          Set the ignoreCache option.
+ voidsetOrdering(java.lang.String ordering) + +
+          Set the ordering specification for the result Collection.
+  +

+ + + + + + + + + + + + + + +
+Method Detail
+ +

+setClass

+
+public void setClass(java.lang.Class cls)
+
+
Set the class of the candidate instances of the query. +

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 Collection. +

+

+
+
+
+
Parameters:
cls - the Class of the candidate instances.
+
+
+
+ +

+setCandidates

+
+public void setCandidates(Extent pcs)
+
+
Set the candidate Extent to query. +

+

+
+
+
+
Parameters:
pcs - the candidate Extent.
+
+
+
+ +

+setCandidates

+
+public void setCandidates(java.util.Collection pcs)
+
+
Set the candidate Collection to query. +

+

+
+
+
+
Parameters:
pcs - the candidate Collection.
+
+
+
+ +

+setFilter

+
+public void setFilter(java.lang.String filter)
+
+
Set the filter for the query. + +

The filter specification is a String 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 Collection only for class type. +

An element of the candidate collection is returned in the result if: +

  • it is assignment compatible to the candidate Class of the Query; and +
  • for all variables there exists a value for which the filter + expression evaluates to true. +
+

The user may denote uniqueness in the filter expression by + explicitly declaring an expression (for example, e1 != e2). +

Rules for constructing valid expressions follow the Java + language, except for these differences: +

    +
  • Equality and ordering comparisons between primitives and instances + of wrapper classes are valid. +
  • Equality and ordering comparisons of Date fields and Date + parameters are valid. +
  • White space (non-printing characters space, tab, carriage + return, and line feed) is a separator and is otherwise ignored. +
  • The assignment operators =, +=, etc. and pre- and post-increment + and -decrement are not supported. Therefore, there are no side + effects from evaluation of any expressions. +
  • Methods, including object construction, are not supported, except + for Collection.contains(Object o), Collection.isEmpty(), + String.startsWith(String s), and String.endsWith(String e). + Implementations might choose to support non-mutating method + calls as non-standard extensions. +
  • Navigation through a null-valued field, which would throw + NullPointerException, is treated as if the filter expression + returned false 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. +
  • Navigation through multi-valued fields (Collection types) is + specified using a variable declaration and the + Collection.contains(Object o) method. +
+

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, this is a reserved + word which means the element of the collection being evaluated. +

Navigation through single-valued fields is specified by the Java + language syntax of field_name.field_name....field_name. +

A JDO implementation is allowed to reorder the filter expression + for optimization purposes. +

+

+
+
+
+
Parameters:
filter - the query filter.
+
+
+
+ +

+declareImports

+
+public void declareImports(java.lang.String imports)
+
+
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 String with semicolon-separated + statements. +

The String parameter to this method follows the syntax of the + import statement of the Java language. +

+

+
+
+
+
Parameters:
imports - import statements separated by semicolons.
+
+
+
+ +

+declareParameters

+
+public void declareParameters(java.lang.String parameters)
+
+
Declare the list of parameters query execution. + + The parameter declaration is a String 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. +

The String parameter to this method follows the syntax for formal + parameters in the Java language. +

+

+
+
+
+
Parameters:
parameters - the list of parameters separated by commas.
+
+
+
+ +

+declareVariables

+
+public void declareVariables(java.lang.String variables)
+
+
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 String + containing one or more unbound variable declarations separated + with semicolons. It follows the syntax for local variables in + the Java language. +

+

+
+
+
+
Parameters:
variables - the variables separated by semicolons.
+
+
+
+ +

+setOrdering

+
+public void setOrdering(java.lang.String ordering)
+
+
Set the ordering specification for the result Collection. The + ordering specification is a String containing one or more ordering + declarations separated by commas. + +

Each ordering declaration is the name of the field on which + to order the results followed by one of the following words: + "ascending" or "descending". + +

The field must be declared in the candidate class or must be + a navigation expression starting with a field in the candidate class. + +

Valid field types are primitive types except boolean; wrapper types + except Boolean; BigDecimal; BigInteger; + String; and Date. +

+

+
+
+
+
Parameters:
ordering - the ordering specification.
+
+
+
+ +

+setIgnoreCache

+
+public void setIgnoreCache(boolean ignoreCache)
+
+
Set the ignoreCache option. The default value for this option was + set by the PersistenceManagerFactory or the + PersistenceManager used to create this Query. + + 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 true, 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. +

+

+
+
+
+
Parameters:
ignoreCache - the setting of the ignoreCache option.
+
+
+
+ +

+getIgnoreCache

+
+public boolean getIgnoreCache()
+
+
Get the ignoreCache option setting. +

+

+
+
+
+ +
Returns:
the ignoreCache option setting.
See Also:
setIgnoreCache(boolean)
+
+
+
+ +

+compile

+
+public void compile()
+
+
Verify the elements of the query and provide a hint to the query to + prepare and optimize an execution plan. +

+

+
+
+
+
+
+
+
+ +

+execute

+
+public java.lang.Object execute()
+
+
Execute the query and return the filtered Collection. +

+

+
+
+
+ +
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)
+
+
+
+ +

+execute

+
+public java.lang.Object execute(java.lang.Object p1)
+
+
Execute the query and return the filtered Collection. +

+

+
+
+
+
Parameters:
p1 - the value of the first parameter declared. +
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)
+
+
+
+ +

+execute

+
+public java.lang.Object execute(java.lang.Object p1,
+                                java.lang.Object p2)
+
+
Execute the query and return the filtered Collection. +

+

+
+
+
+
Parameters:
p1 - the value of the first parameter declared.
p2 - the value of the second parameter declared. +
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)
+
+
+
+ +

+execute

+
+public java.lang.Object execute(java.lang.Object p1,
+                                java.lang.Object p2,
+                                java.lang.Object p3)
+
+
Execute the query and return the filtered Collection. +

+

+
+
+
+
Parameters:
p1 - the value of the first parameter declared.
p2 - the value of the second parameter declared.
p3 - the value of the third parameter declared. +
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)
+
+
+
+ +

+executeWithMap

+
+public java.lang.Object executeWithMap(java.util.Map parameters)
+
+
Execute the query and return the filtered Collection. The query + is executed with the parameters set by the Map values. Each Map entry + consists of a key which is the name of the parameter in the + declareParameters method, and a value which is the value used in + the execute method. The keys in the Map and the declared parameters + must exactly match or a JDOUserException is thrown. +

+

+
+
+
+
Parameters:
parameters - the Map containing all of the parameters. +
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)
+
+
+
+ +

+executeWithArray

+
+public java.lang.Object executeWithArray(java.lang.Object[] parameters)
+
+
Execute the query and return the filtered Collection. + +

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. + +

The filter, import, declared parameters, declared variables, and + ordering statements are verified for consistency. + +

Each element in the candidate Collection is examined to see that it + is assignment compatible to the Class 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 true. +

+

+
+
+
+
Parameters:
parameters - the Object array with all of the parameters. +
Returns:
the filtered Collection.
+
+
+
+ +

+getPersistenceManager

+
+public PersistenceManager getPersistenceManager()
+
+
Get the PersistenceManager associated with this Query. + +

If this Query was restored from a serialized form, it has no + PersistenceManager, and this method returns null. +

+

+
+
+
+ +
Returns:
the PersistenceManager associated with this Query.
+
+
+
+ +

+close

+
+public void close(java.lang.Object queryResult)
+
+
Close a query result and release any resources associated with it. The + parameter is the return from execute(...) and might have iterators open on it. + Iterators associated with the query result are invalidated: they return false + to hasNext() and throw NoSuchElementException to next(). +

+

+
+
+
+
Parameters:
queryResult - the result of execute(...) on this Query instance.
+
+
+
+ +

+closeAll

+
+public void closeAll()
+
+
Close all query results associated with this Query 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 false to hasNext() and throw + NoSuchElementException to next(). +

+

+
+
+
+
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
+		 + +
+ PREV CLASS  + NEXT CLASS + FRAMES   + NO FRAMES   +  + + +
+ SUMMARY: NESTED | FIELD | CONSTR | METHOD +DETAIL: FIELD | CONSTR | METHOD
+ + + +
+Copyright © 2005 Apache Software Foundation. All Rights Reserved. + +