Add a vendor-specific extension to this query. The key and value are not standard. An implementation must ignore keys that are not recognized.

Add a subquery to this query.

Add a subquery to this query. The Map version of the method treats the key of each map entry as the name of the parameter in the subquery, with or without the leading ":", and the value as the name of the expression in the outer query. If the trimmed expression is the empty String for either the parameter or the value of the String[], or for any map key or value, that expression is ignored.

Add a subquery to this query. The String version of the method binds the named expression to the parameter implictly or explicitly declared in the subquery.

Add a subquery to this query. A subquery is composed as a Query and subsequently attached to a different query (the outer query) by calling this method. The query parameter instance is unmodified as a result of the addSubquery or subsequent execution of the outer query. Only some of the query parts are copied for use as the subquery. The parts copied include the candidate class, filter, parameter declarations, variable declarations, imports, ordering specification, uniqueness, result specification, and grouping specification. The association with a PersistenceManager, the candidate collection or extent, result class, and range limits are not used. The String parameters are trimmed of white space. The variableDeclaration parameter is the name of the variable containing the results of the subquery execution. If the same value of variableDeclaration is used to add multiple subqueries, the subquery replaces the previous subquery for the same named variable. If the subquery parameter is null, the variable is unset, effectively making the variable named in the variableDeclaration unbound. If the trimmed value is the empty String, or the parameter is null, then JDOUserException is thrown. The candidateCollectionExpression is the expression from the outer query that represents the candidates over which the subquery is evaluated. If the trimmed value is the empty String, or the parameter is null, then the candidate collection is the extent of the candidate class. The String... version of the method binds the named expressions in turn to parameters in the order in which they are declared in the subquery, or in the order they are found in the filter if not explicitly declared in the subquery.

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().

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().

Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.

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.

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.

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.

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.

Deletes all the instances of the candidate class that pass the filter.

Deletes all the instances of the candidate class that pass the filter.

Execute the query and return the filtered Collection.

Execute the query and return the filtered Collection.

Execute the query and return the filtered Collection.

Execute the query and return the filtered Collection.

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.

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.

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.

Get the ignoreCache option setting.

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.

The unmodifiable flag, when set, disallows further modification of the query, except for specifying the range, result class, and ignoreCache option.

Set the candidate Extent to query.

Set the candidate Collection to query.

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.

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.

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.

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.

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.

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.

Set the range of results to return. The parameter is a String containing a comma-separated fromIncl and toExcl. The fromIncl and toExcl can be either String representations of long values, or can be parameters identified with a leading ":". For example, setRange("50, 70"); or setRange(":from, :to"); or setRange("50, :to");. 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.

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.

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.

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:

JDO 2.0