Overview | Package | Class | Tree | Deprecated | 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:
  0.9
Author:
  Craig Russell

Method Summary
`void` | `close(java.lang.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(java.lang.String imports)` Set the import statements to be used to identify the fully qualified name of variables or parameters.
`void` | `declareParameters(java.lang.String parameters)` Declare the list of parameters query execution.
`void` | `declareVariables(java.lang.String variables)` Declare the unbound variables to be used in the query.
`java.lang.Object` | `execute()` Execute the query and return the filtered Collection.
`java.lang.Object` | `execute(java.lang.Object p1)` Execute the query and return the filtered `Collection`.
`java.lang.Object` | `execute(java.lang.Object p1, java.lang.Object p2)` Execute the query and return the filtered `Collection`.
`java.lang.Object` | `execute(java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)` Execute the query and return the filtered `Collection`.
`java.lang.Object` | `executeWithArray(java.lang.Object[] parameters)` Execute the query and return the filtered `Collection`.
`java.lang.Object` | `executeWithMap(java.util.Map parameters)` Execute the query and return the filtered `Collection`.
`boolean` | `getIgnoreCache()` Get the ignoreCache option setting.
`PersistenceManager` | `getPersistenceManager()` Get the `PersistenceManager` associated with this `Query`.
`void` | `setCandidates(java.util.Collection pcs)` Set the candidate `Collection` to query.
`void` | `setCandidates(Extent pcs)` Set the candidate `Extent` to query.
`void` | `setClass(java.lang.Class cls)` Set the class of the candidate instances of the query.
`void` | `setFilter(java.lang.String filter)` Set the filter for the query.
`void` | `setIgnoreCache(boolean ignoreCache)` Set the ignoreCache option.
`void` | `setOrdering(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 | Tree | Deprecated | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD