Return-Path: Delivered-To: apmail-db-jdo-commits-archive@www.apache.org Received: (qmail 46361 invoked from network); 14 Oct 2005 05:10:26 -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:26 -0000 Received: (qmail 67930 invoked by uid 500); 14 Oct 2005 05:10:23 -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 66819 invoked by uid 99); 14 Oct 2005 05:09:39 -0000 X-ASF-Spam-Status: No, hits=0.6 required=10.0 tests=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:51 -0700 Received: (qmail 45152 invoked by uid 65534); 14 Oct 2005 05:07:30 -0000 Message-ID: <20051014050730.45151.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r321004 [28/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/jd... 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/api20/apidocs/javax/jdo/Query.html URL: http://svn.apache.org/viewcvs/incubator/jdo/site/docs/api20/apidocs/javax/jdo/Query.html?rev=321004&view=auto ============================================================================== --- incubator/jdo/site/docs/api20/apidocs/javax/jdo/Query.html (added) +++ incubator/jdo/site/docs/api20/apidocs/javax/jdo/Query.html Thu Oct 13 22:05:52 2005 @@ -0,0 +1,1411 @@ + + + + + + + +Query (JDO2 API 2.0-SNAPSHOT) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
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, values, and aggregate data + 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, ordering and grouping specifications, + result and result class, the range of results, + and flags indicating whether the query result + is unique and whether the query can be modified. +

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 of the same name. 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. +

The result of the query by default is a list of result class instances, + but might be specified via setResult. The class of the result + by default is the candidate class, but might be specified via + setResultClass. +

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 single instance or a + List of result class instances which the + user can iterate to get results. The signature + of the execute methods specifies that they return an Object which + must be cast to the appropriate result by the user. +

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

+ +

+

+
Version:
+
2.0
+
+
+ +

+ + + + + + + + + + + + + + + + + + +
+Field Summary
+static java.lang.StringJDOQL + +
+          The string constant used as the first argument to PersistenceManager.newQuery(String,Object) to identify that + the created query should obey the JDOQL syntax and semantic + rules.
+static java.lang.StringSQL + +
+          The string constant used as the first argument to PersistenceManager.newQuery(String,Object) to identify that + the created query should use SQL semantics.
+  + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Method Summary
+ voidaddExtension(java.lang.String key, + java.lang.Object value) + +
+          Add a vendor-specific extension to this query.
+ 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.
+ longdeletePersistentAll() + +
+          Deletes all the instances of the candidate class that pass the + filter.
+ longdeletePersistentAll(java.util.Map parameters) + +
+          Deletes all the instances of the candidate class that pass the + filter.
+ longdeletePersistentAll(java.lang.Object[] parameters) + +
+          Deletes all the instances of the candidate class that pass the + filter.
+ 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.
+ FetchPlangetFetchPlan() + +
+          Returns the FetchPlan used by this + Query.
+ booleangetIgnoreCache() + +
+          Get the ignoreCache option setting.
+ PersistenceManagergetPersistenceManager() + +
+          Get the PersistenceManager associated with this Query.
+ booleanisUnmodifiable() + +
+          The unmodifiable flag, when set, disallows further + modification of the query, except for specifying the range, + result class, and ignoreCache option.
+ 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.
+ voidsetExtensions(java.util.Map extensions) + +
+          Set multiple extensions, or use null to clear all extensions.
+ voidsetFilter(java.lang.String filter) + +
+          Set the filter for the query.
+ voidsetGrouping(java.lang.String group) + +
+          Set the grouping expressions, optionally including a "having" + clause.
+ voidsetIgnoreCache(boolean ignoreCache) + +
+          Set the ignoreCache option.
+ voidsetOrdering(java.lang.String ordering) + +
+          Set the ordering specification for the result Collection.
+ voidsetRange(long fromIncl, + long toExcl) + +
+          Set the range of results to return.
+ voidsetResult(java.lang.String data) + +
+          Specifies what type of data this query should return.
+ voidsetResultClass(java.lang.Class cls) + +
+          Specify the type of object in which to return each element of + the result of invoking execute() or one of its siblings.
+ voidsetUnique(boolean unique) + +
+          Specify that only the first result of the query should be + returned, rather than a collection.
+ voidsetUnmodifiable() + +
+          The unmodifiable flag, when set, disallows further + modification of the query, except for specifying the range, + result class, and ignoreCache option.
+  +

+ + + + + + + + +
+Field Detail
+ +

+JDOQL

+
+public static final java.lang.String JDOQL
+
+
The string constant used as the first argument to PersistenceManager.newQuery(String,Object) to identify that + the created query should obey the JDOQL syntax and semantic + rules. +

This is the default query language used when creating a + query with any of the other PersistenceManager.newQuery() methods, except PersistenceManager.newQuery(Object), which uses the query + language of the compiled query template object passed to that + method.

+

+

+
Since:
+
2.0
+
See Also:
Constant Field Values
+
+
+ +

+SQL

+
+public static final java.lang.String SQL
+
+
The string constant used as the first argument to PersistenceManager.newQuery(String,Object) to identify that + the created query should use SQL semantics. This is only + meaningful for relational JDO implementations. +

If this is used, the Object argument to the + PersistenceManager.newQuery(String,Object) method + should be a String containing a SQL + SELECT statement.

+

+

+
Since:
+
2.0
+
See Also:
Constant Field Values
+
+ + + + + + + + + + + +
+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(). +

+

+
+
+
+
+
+
+
+ +

+setGrouping

+
+public void setGrouping(java.lang.String group)
+
+
Set the grouping expressions, optionally including a "having" + clause. When grouping is specified, each result expression + must either be an expression contained in the grouping, or an + aggregate evaluated once per group. +

+

+
+
+
+
Parameters:
group - a comma-delimited list of expressions, optionally + followed by the "having" keyword and a boolean expression
Since:
+
2.0
+
+
+
+
+ +

+setUnique

+
+public void setUnique(boolean unique)
+
+
Specify that only the first result of the query should be + returned, rather than a collection. The execute method will + return null if the query result size is 0. +

+

+
+
+
+
Parameters:
unique - if true, only one element is returned
Since:
+
2.0
+
+
+
+
+ +

+setResult

+
+public void setResult(java.lang.String data)
+
+
Specifies what type of data this query should return. If this + is unset or set to null, this query returns + instances of the query's candidate class. If set, this query + will return expressions, including field values (projections) and + aggregate function results. +

+

+
+
+
+
Parameters:
data - a comma-delimited list of expressions + (fields, functions on fields, or aggregate functions) + to return from this query
Since:
+
2.0
+
+
+
+
+ +

+setResultClass

+
+public void setResultClass(java.lang.Class cls)
+
+
Specify the type of object in which to return each element of + the result of invoking execute() or one of its siblings. + If the result is not set or set to null, the result class defaults + to the candidate class of the query. If the result consists of one + expression, the result class defaults to the type of that expression. + If the result consists of more than one expression, the result class + defaults to Object[]. + The result class may be specified to be one of the java.lang classes + Character, Boolean, Byte, Short, Integer, Long, Float, Double, String, + or Object[]; or one of the java.math classes BigInteger or BigDecimal; + or the java.util class Date; or one of the java.sql classes Date, + Time, or Timestamp; or a user-defined class. +

If there are multiple result expressions, the result class + must be able to hold all elements of the result specification + or a JDOUserException is thrown. +

If there is only one result expression, the result class must be + assignable from the type of the result expression or must be able + to hold all elements of the result specification. A single value + must be able to be coerced into the specified result class + (treating wrapper classes as equivalent to their unwrapped + primitive types) or by matching. If the result class does not satisfy + these conditions, a JDOUserException is thrown. +

A constructor of a result class specified in the setResult method + will be used if the results specification matches the parameters + of the constructor by position and type. If more than one constructor + satisfies the requirements, the JDO implementation chooses one of them. + If no constructor satisfies the results requirements, or if the result + class is specified via the setResultClass method, the following + requirements apply: +

    +
  • A user-defined result class must have a no-args constructor and + one or more public set or put methods or fields. +
  • Each result expression must match one of: +
      +
    • a public field that matches the name of the result expression + and is of the type (treating wrapper types equivalent to primitive + types) of the result expression; +
    • or if no public field matches the name and type, a public + setor if neither of the above applies,a public method must be found + with the signature void put(Object, Object). + During processing of the results, + the first argument is the name of the result expression and + the second argument is the value from the query result. +
    +
+ Portable result classes do not invoke any persistence behavior + during their no-args constructor or set +
+
+
+
+
Parameters:
cls - the result class
Since:
+
2.0
+
+
+
+
+ +

+setRange

+
+public void setRange(long fromIncl,
+                     long toExcl)
+
+
Set the range of results to return. The execution of the query is + modified to return only a subset of results. If the filter would + normally return 100 instances, and fromIncl is set to 50, and + toExcl is set to 70, then the first 50 results that would have + been returned are skipped, the next 20 results are returned and the + remaining 30 results are ignored. An implementation should execute + the query such that the range algorithm is done at the data store. +

+

+
+
+
+
Parameters:
fromIncl - 0-based inclusive start index
toExcl - 0-based exclusive end index, or + Long.MAX_VALUE for no limit.
Since:
+
2.0
+
+
+
+
+ +

+addExtension

+
+public void addExtension(java.lang.String key,
+                         java.lang.Object value)
+
+
Add a vendor-specific extension to this query. The key and value + are not standard. + An implementation must ignore keys that are not recognized. +

+

+
+
+
+
Parameters:
key - the key of the extension
value - the value of the extension
Since:
+
2.0
+
+
+
+
+ +

+setExtensions

+
+public void setExtensions(java.util.Map extensions)
+
+
Set multiple extensions, or use null to clear all extensions. + Map keys and values are not standard. + An implementation must ignore entries that are not recognized. +

+

+
+
+
+
Parameters:
extensions - the map of extensions
Since:
+
2.0
+
See Also:
addExtension(java.lang.String, java.lang.Object)
+
+
+
+ +

+getFetchPlan

+
+public FetchPlan getFetchPlan()
+
+
Returns the FetchPlan used by this + Query. Modifications of the returned fetch plan will not + cause this query's owning PersistenceManager's + FetchPlan to be modified. +

+

+
+
+
+ +
Returns:
the fetch plan used by this query
Since:
+
2.0
+
+
+
+
+ +

+deletePersistentAll

+
+public long deletePersistentAll(java.lang.Object[] parameters)
+
+
Deletes all the instances of the candidate class that pass the + filter. +

+

+
+
+
+
Parameters:
parameters - for the query +
Returns:
the number of instances of the candidate class that were deleted
Since:
+
2.0
+
See Also:
deletePersistentAll()
+
+
+
+ +

+deletePersistentAll

+
+public long deletePersistentAll(java.util.Map parameters)
+
+
Deletes all the instances of the candidate class that pass the + filter. +

+

+
+
+
+
Parameters:
parameters - for the query +
Returns:
the number of instances of the candidate class that were deleted
Since:
+
2.0
+
See Also:
deletePersistentAll()
+
+
+
+ +

+deletePersistentAll

+
+public long deletePersistentAll()
+
+
Deletes all the instances of the candidate class that pass the + filter. Returns the number of instances of the candidate + class that were deleted, specifically not including the number + of dependent and embedded instances. +

Dirty instances of affected classes in the cache are first + flushed to the datastore. Instances in the cache or brought into + the cache as a result of executing one of the + deletePersistentAll + methods undergo life cycle changes as if deletePersistent + were called on them. +

Specifically, if the class of deleted instances implements the + delete callback interface, the corresponding callback methods + are called on the deleted instances. Similarly, if there are + lifecycle listeners registered for delete events on affected + classes, the listener is called for each appropriate deleted instance. +

Before returning control to the application, instances of affected + classes in the cache are refreshed to reflect whether they were + deleted from the datastore. +

+

+
+
+
+ +
Returns:
the number of instances of the candidate class that were deleted
Since:
+
2.0
+
+
+
+
+ +

+setUnmodifiable

+
+public void setUnmodifiable()
+
+
The unmodifiable flag, when set, disallows further + modification of the query, except for specifying the range, + result class, and ignoreCache option. + The unmodifiable flag can also be set in metadata. +

+

+
+
+
+
Since:
+
2.0
+
+
+
+
+ +

+isUnmodifiable

+
+public boolean isUnmodifiable()
+
+
The unmodifiable flag, when set, disallows further + modification of the query, except for specifying the range, + result class, and ignoreCache option. +

+

+
+
+
+ +
Returns:
the current setting of the flag
Since:
+
2.0
+
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
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/api20/apidocs/javax/jdo/Transaction.html URL: http://svn.apache.org/viewcvs/incubator/jdo/site/docs/api20/apidocs/javax/jdo/Transaction.html?rev=321004&view=auto ============================================================================== --- incubator/jdo/site/docs/api20/apidocs/javax/jdo/Transaction.html (added) +++ incubator/jdo/site/docs/api20/apidocs/javax/jdo/Transaction.html Thu Oct 13 22:05:52 2005 @@ -0,0 +1,690 @@ + + + + + + + +Transaction (JDO2 API 2.0-SNAPSHOT) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
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 Transaction

+
+
+
public interface Transaction
+ +

+The JDO Transaction interface provides for initiation and completion + of transactions under user control. + It is a sub-interface of the PersistenceManager + that deals with options and transaction demarcation. +

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

Transaction initiation and completion methods have similar semantics to + javax.transaction.UserTransaction when used outside a managed + environment. When used in a managed environment, transaction initiation + and completion methods may only be used with bean-managed transaction semantics. +

+ +

+

+
Version:
+
2.0
+
+
+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Method Summary
+ voidbegin() + +
+          Begin a transaction.
+ voidcommit() + +
+          Commit the current transaction.
+ booleangetNontransactionalRead() + +
+          If true, allows persistent instances to be read without + a transaction active.
+ booleangetNontransactionalWrite() + +
+          If true, allows persistent instances to be written without + a transaction active.
+ booleangetOptimistic() + +
+          Optimistic transactions do not hold data store locks until commit time.
+ PersistenceManagergetPersistenceManager() + +
+          The Transaction instance is always associated with exactly one + PersistenceManager.
+ booleangetRestoreValues() + +
+          Return the current value of the restoreValues property.
+ booleangetRetainValues() + +
+          If true, at commit time instances retain their field values.
+ booleangetRollbackOnly() + +
+          Returns the rollback-only status of the transaction.
+ javax.transaction.SynchronizationgetSynchronization() + +
+          The user-specified Synchronization instance for this Transaction instance.
+ booleanisActive() + +
+          Returns whether there is a transaction currently active.
+ voidrollback() + +
+          Roll back the current transaction.
+ voidsetNontransactionalRead(boolean nontransactionalRead) + +
+          If true, allow persistent instances to be read without + a transaction active.
+ voidsetNontransactionalWrite(boolean nontransactionalWrite) + +
+          If true, allow persistent instances to be written without + a transaction active.
+ voidsetOptimistic(boolean optimistic) + +
+          Optimistic transactions do not hold data store locks until commit time.
+ voidsetRestoreValues(boolean restoreValues) + +
+          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.
+ voidsetRetainValues(boolean retainValues) + +
+          If true, at commit instances retain their values and the instances + transition to persistent-nontransactional.
+ voidsetRollbackOnly() + +
+          Sets the rollback-only status of the transaction to true.
+ voidsetSynchronization(javax.transaction.Synchronization sync) + +
+          The user can specify a Synchronization instance to be notified on + transaction completions.
+  +

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

+begin

+
+public void begin()
+
+
Begin a transaction. The type of transaction is determined by the + setting of the Optimistic flag. +

+

+ +
Throws: +
JDOUserException - if transactions are managed by a container + in the managed environment, or if the transaction is already active.
See Also:
setOptimistic(boolean), +getOptimistic()
+
+
+
+ +

+commit

+
+public void commit()
+
+
Commit the current transaction. +

+

+ +
Throws: +
JDOUserException - if transactions are managed by a container + in the managed environment, or if the transaction is not active.
+
+
+
+ +

+rollback

+
+public void rollback()
+
+
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.
+
+
+
+ +

+isActive

+
+public boolean isActive()
+
+
Returns whether there is a transaction currently active. +

+

+ +
Returns:
true if the transaction is active.
+
+
+
+ +

+getRollbackOnly

+
+public boolean getRollbackOnly()
+
+
Returns the rollback-only status of the transaction. When + begun, the rollback-only status is false. Either the + application or the JDO implementation may set this flag + using setRollbackOnly. +

+

+ +
Returns:
true if the transaction has been + marked for rollback.
Since:
+
2.0
+
+
+
+
+ +

+setRollbackOnly

+
+public void setRollbackOnly()
+
+
Sets the rollback-only status of the transaction to true. + After this flag is set to true, the transaction + can no longer be committed, and any attempt to commit the + transaction will throw JDOUserException. +

+

+
Since:
+
2.0
+
+
+
+
+ +

+setNontransactionalRead

+
+public void setNontransactionalRead(boolean nontransactionalRead)
+
+
If true, allow persistent instances to be read without + a transaction active. + If an implementation does not support this option, a + JDOUnsupportedOptionException is thrown. +

+

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

+getNontransactionalRead

+
+public boolean getNontransactionalRead()
+
+
If true, allows persistent instances to be read without + a transaction active. +

+

+ +
Returns:
the value of the nontransactionalRead property
+
+
+
+ +

+setNontransactionalWrite

+
+public void setNontransactionalWrite(boolean nontransactionalWrite)
+
+
If true, allow persistent instances to be written without + a transaction active. + If an implementation does not support this option, a + JDOUnsupportedOptionException is thrown. +

+

+
Parameters:
nontransactionalWrite - the value of the nontransactionalRead property
+
+
+
+ +

+getNontransactionalWrite

+
+public boolean getNontransactionalWrite()
+
+
If true, allows persistent instances to be written without + a transaction active. +

+

+ +
Returns:
the value of the nontransactionalWrite property
+
+
+
+ +

+setRetainValues

+
+public void setRetainValues(boolean retainValues)
+
+
If true, at commit instances retain their values and the instances + transition to persistent-nontransactional. + If an implementation does not support this option, a + JDOUnsupportedOptionException is thrown. +

+

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

+getRetainValues

+
+public boolean getRetainValues()
+
+
If true, at commit time instances retain their field values. +

+

+ +
Returns:
the value of the retainValues property
+
+
+
+ +

+setRestoreValues

+
+public void setRestoreValues(boolean restoreValues)
+
+
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()
+
+
Return the current value of the restoreValues property. +

+

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

+setOptimistic

+
+public void setOptimistic(boolean optimistic)
+
+
Optimistic transactions do not hold data store locks until commit time. + If an implementation does not support this option, a + JDOUnsupportedOptionException is thrown. +

+

+
Parameters:
optimistic - the value of the Optimistic flag.
+
+
+
+ +

+getOptimistic

+
+public boolean getOptimistic()
+
+
Optimistic transactions do not hold data store locks until commit time. +

+

+ +
Returns:
the value of the Optimistic property.
+
+
+
+ +

+setSynchronization

+
+public void setSynchronization(javax.transaction.Synchronization sync)
+
+
The user can specify a Synchronization instance to be notified on + transaction completions. The beforeCompletion method is called prior + to flushing instances to the data store. + +

The afterCompletion method is called after performing state + transitions of persistent and transactional instances, following + the data store commit or rollback operation. +

Only one Synchronization instance can be registered with the + Transaction. 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. +

+

+
Parameters:
sync - the Synchronization instance to be notified; null for none
+
+
+
+ +

+getSynchronization

+
+public javax.transaction.Synchronization getSynchronization()
+
+
The user-specified Synchronization instance for this Transaction instance. +

+

+ +
Returns:
the user-specified Synchronization instance.
+
+
+
+ +

+getPersistenceManager

+
+public PersistenceManager getPersistenceManager()
+
+
The Transaction instance is always associated with exactly one + PersistenceManager. +

+

+ +
Returns:
the PersistenceManager for this Transaction instance
+
+
+ +
+ + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + +
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. + +