All Superinterfaces:: Serializable

public interface Query extends 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.1

Field Summary

Fields

Modifier and Type

Field

Description

static final 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.

static final 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.
Method Summary

Modifier and Type

Method

Description

void

addExtension(String key, Object value)

Add a vendor-specific extension to this query.

void

addSubquery(Query sub, String variableDeclaration, String candidateCollectionExpression)

Add a subquery to this query.

void

addSubquery(Query sub, String variableDeclaration, String candidateCollectionExpression, String parameter)

Add a subquery to this query.

void

addSubquery(Query sub, String variableDeclaration, String candidateCollectionExpression, String... parameters)

Add a subquery to this query.

void

addSubquery(Query sub, String variableDeclaration, String candidateCollectionExpression, Map parameters)

Add a subquery to this query.

void

close(Object queryResult)

Close a query result and release any resources associated with it.

void

closeAll()

Close all query results associated with this Query instance, and release all resources associated with them.

void

compile()

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

void

declareImports(String imports)

Set the import statements to be used to identify the fully qualified name of variables or parameters.

void

declareParameters(String parameters)

Declare the list of parameters query execution.

void

declareVariables(String variables)

Declare the unbound variables to be used in the query.

long

deletePersistentAll()

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

long

deletePersistentAll(Object... parameters)

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

long

deletePersistentAll(Map parameters)

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

Object

execute()

Execute the query and return the filtered Collection.

Object

execute(Object p1)

Execute the query and return the filtered Collection.

Object

execute(Object p1, Object p2)

Execute the query and return the filtered Collection.

Object

execute(Object p1, Object p2, Object p3)

Execute the query and return the filtered Collection.

Object

executeWithArray(Object... parameters)

Execute the query and return the filtered Collection.

Object

executeWithMap(Map parameters)

Execute the query and return the filtered Collection.

FetchPlan

getFetchPlan()

Returns the FetchPlan used by this Query.

boolean

getIgnoreCache()

Get the ignoreCache option setting.

PersistenceManager

getPersistenceManager()

Get the PersistenceManager associated with this Query.

boolean

isUnmodifiable()

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

void

setCandidates(Collection pcs)

Set the candidate Collection to query.

void

setCandidates(Extent pcs)

Set the candidate Extent to query.

void

setClass(Class cls)

Set the class of the candidate instances of the query.

void

setExtensions(Map extensions)

Set multiple extensions, or use null to clear all extensions.

void

setFilter(String filter)

Set the filter for the query.

void

setGrouping(String group)

Set the grouping expressions, optionally including a "having" clause.

void

setIgnoreCache(boolean ignoreCache)

Set the ignoreCache option.

void

setOrdering(String ordering)

Set the ordering specification for the result Collection.

void

setRange(long fromIncl, long toExcl)

Set the range of results to return.

void

setRange(String fromInclToExcl)

Set the range of results to return.

void

setResult(String data)

Specifies what type of data this query should return.

void

setResultClass(Class cls)

Specify the type of object in which to return each element of the result of invoking execute() or one of its siblings.

void

setUnique(boolean unique)

Specify that only the first result of the query should be returned, rather than a collection.

void

setUnmodifiable()

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

Field Details
- JDOQL
  static final 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
  static final 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 Details
- setClass
  
  void setClass(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
  
  void setCandidates(Extent pcs)
  
  Set the candidate Extent to query.
  
  Parameters:
  
  pcs - the candidate Extent.
- setCandidates
  
  void setCandidates(Collection pcs)
  
  Set the candidate Collection to query.
  
  Parameters:
  
  pcs - the candidate Collection.
- setFilter
  void setFilter(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
  
  void declareImports(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
  
  void declareParameters(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
  
  void declareVariables(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
  
  void setOrdering(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
  
  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
  boolean getIgnoreCache()
  
  Get the ignoreCache option setting.
  
  Returns:
  
  the ignoreCache option setting.
  
  See Also:
  
  setIgnoreCache(boolean)
- compile
  
  void compile()
  
  Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.
- execute
  Object execute()
  
  Execute the query and return the filtered Collection.
  
  Returns:
  
  the filtered Collection.
  
  See Also:
  
  executeWithArray(Object[] parameters)
- execute
  Object execute(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
  Object execute(Object p1, 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
  Object execute(Object p1, Object p2, 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
  Object executeWithMap(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
  
  Object executeWithArray(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
  
  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
  
  void close(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
  
  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
  
  void setGrouping(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
  
  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
  
  void setResult(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
  void setResultClass(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 setinvalid input: '<'/code method that returns void and matches the name of the result expression and takes a single parameter which is the exact type of the result expression;
  or 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 setinvalid input: '<'/code methods.
  Parameters: cls - the result class Since: 2.0

Interface Query

Field Summary

Method Summary

Field Details

JDOQL

SQL

Method Details

setClass

setCandidates

setCandidates

setFilter

declareImports

declareParameters

declareVariables

setOrdering

setIgnoreCache

getIgnoreCache

compile

execute

execute

execute

execute

executeWithMap

executeWithArray

getPersistenceManager

close

closeAll

setGrouping

setUnique

setResult

setResultClass

setRange

setRange

addExtension

setExtensions

getFetchPlan

deletePersistentAll

deletePersistentAll

deletePersistentAll

setUnmodifiable

isUnmodifiable

addSubquery

addSubquery

addSubquery

addSubquery