javax.jdo

## Interface Query<T>

- All Superinterfaces:
    AutoCloseable, Serializable

      public interface Query<T>
      extends AutoCloseable, 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 and Description
    --- | ---
    `static 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 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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and 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, Map parameters)` 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, String parameter)` Add a subquery to this query.
    `void` | `cancel(Thread thread)` Method to cancel an executing query in the specified thread.
    `void` | `cancelAll()` Method to cancel any executing queries.
    `void` | `close()` Don't use this method directly; use `closeAll()` instead.
    `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.
    `Query<T>` | `datastoreReadTimeoutMillis(Integer interval)` Set the datastore read timeout (millis).
    `Query<T>` | `datastoreWriteTimeoutMillis(Integer interval)` Set the datastore write timeout (millis).
    `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(Map parameters)` 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.
    `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`.
    `List<T>` | `executeList()` Method to execute the query where there are (potentially) multiple rows and we are returning the candidate type.
    `List<Object>` | `executeResultList()` Method to execute the query where there are (potentially) multiple rows and we have a result defined but no result class.
    `<R> List<R>` | `executeResultList(Class<R> resultCls)` Method to execute the query where there are (potentially) multiple rows and we are returning a result type for the specified result.
    `Object` | `executeResultUnique()` Method to execute the query where there is a single row and we have a result defined but no result class.
    `<R> R` | `executeResultUnique(Class<R> resultCls)` Method to execute the query where there is a single row and we are returning a result type for the specified result.
    `T` | `executeUnique()` Method to execute the query where there is a single row and we are returning the candidate type.
    `Object` | `executeWithArray(Object... parameters)` Execute the query and return the filtered `Collection`.
    `Object` | `executeWithMap(Map parameters)` Execute the query and return the filtered `Collection`.
    `Query<T>` | `extension(String key, Object value)` Specify an extension for this query.
    `Query<T>` | `extensions(Map values)` Specify a map of extensions for this query.
    `Query<T>` | `filter(String filter)` Set the filter for the query.
    `Integer` | `getDatastoreReadTimeoutMillis()` Get the effective timeout setting for read operations.
    `Integer` | `getDatastoreWriteTimeoutMillis()` Get the effective timeout setting for write operations.
    `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` | `getSerializeRead()` Return the current value of the serializeRead property.
    `Query<T>` | `groupBy(String group)` Set the grouping expressions, optionally including a "having" clause.
    `Query<T>` | `ignoreCache(boolean flag)` Set whether we to ignore the cache with this query.
    `Query<T>` | `imports(String imports)` Set the import statements to be used to identify the fully qualified name of variables or parameters.
    `boolean` | `isUnmodifiable()` The unmodifiable flag, when set, disallows further modification of the query, except for specifying the range, result class, and ignoreCache option.
    `Query<T>` | `orderBy(String ordering)` Set the ordering specification for the result `Collection`.
    `Query<T>` | `parameters(String parameters)` Declare the list of parameters for query execution.
    `Query<T>` | `range(long fromIncl, long toExcl)` Set the range of results to return.
    `Query<T>` | `range(String fromInclToExcl)` Set the range of results to return.
    `Query<T>` | `result(String result)` Set the result clause for the query.
    `Query<T>` | `saveAsNamedQuery(String name)` Save the query, as it is currently defined, as a named query under the specified name.
    `Query<T>` | `serializeRead(Boolean serialize)` Set whether we to lock all objects read by this query.
    `void` | `setCandidates(Collection<T> pcs)` Set the candidate `Collection` to query.
    `void` | `setCandidates(Extent<T> pcs)` Set the candidate `Extent` to query.
    `void` | `setClass(Class<T> cls)` Set the class of the candidate instances of the query.
    `void` | `setDatastoreReadTimeoutMillis(Integer interval)` Specify a timeout interval (milliseconds) for any read operations associated with this query.
    `void` | `setDatastoreWriteTimeoutMillis(Integer interval)` Specify a timeout interval (milliseconds) for any write operations associated with this 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.
    `Query<T>` | `setNamedParameters(Map<String,?> namedParamMap)` Method to set the named parameters on this query prior to execution.
    `void` | `setOrdering(String ordering)` Set the ordering specification for the result `Collection`.
    `Query<T>` | `setParameters(Object... paramValues)` Method to set the values of the numbered parameters on this query prior to execution.
    `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` | `setSerializeRead(Boolean serialize)` If `true`, a lock will be applied to all objects read in this query.
    `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.
    `Query<T>` | `subquery(Query sub, String variableDeclaration, String candidateCollectionExpression)` Add a subquery to this query.
    `Query<T>` | `subquery(Query sub, String variableDeclaration, String candidateCollectionExpression, Map parameters)` Add a subquery to this query.
    `Query<T>` | `subquery(Query sub, String variableDeclaration, String candidateCollectionExpression, String... parameters)` Add a subquery to this query.
    `Query<T>` | `subquery(Query sub, String variableDeclaration, String candidateCollectionExpression, String parameter)` Add a subquery to this query.
    `Query<T>` | `unmodifiable()` Set whether to make this query unmodifiable.
    `Query<T>` | `variables(String variables)` Declare the unbound variables to be used in the query.

- - ### Field Detail

    - #### 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 Detail

    - #### setClass

          void setClass(Class<T> 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<T> pcs)

      Set the candidate `Extent` to query.
      Parameters:
        `pcs` - the candidate `Extent`.

    - #### setCandidates

          void setCandidates(Collection<T> 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.

      Cancellation of the query using cancel() will result in JDOQueryInterruptedException being thrown here

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

    - #### execute

          Object execute(Object p1)

      Execute the query and return the filtered `Collection`.

      Cancellation of the query using cancel() will result in JDOQueryInterruptedException being thrown here

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

      Cancellation of the query using cancel() will result in JDOQueryInterruptedException being thrown here

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

      Cancellation of the query using cancel() will result in JDOQueryInterruptedException being thrown here

      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.

      Cancellation of the query using cancel() will result in JDOQueryInterruptedException being thrown here

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

      Cancellation of the query using cancel() will result in JDOQueryInterruptedException being thrown here

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

    - #### close

          void close()
              throws Exception

      Don't use this method directly; use `closeAll()` instead. It is intended for use with try-with-resources.
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `Exception` - if this resource cannot be closed

    - #### 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 `set` 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 `set` methods.
      Parameters:
        `cls` - the result class
      Since:
        2.0

    - #### setRange

          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

    - #### setRange

          void setRange(String fromInclToExcl)

      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.
      Parameters:
        `fromInclToExcl` - comma-separated fromIncl and toExcl values
      Since:
        2.0
      See Also:
        `setRange(long, long)`

    - #### addExtension

          void addExtension(String key,
                            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

          void setExtensions(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

          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

          long deletePersistentAll(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

          long deletePersistentAll(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

          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

          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

          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

    - #### addSubquery

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

      Add a subquery to this query.
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable in the outer query to bind the results of the subquery
        `candidateCollectionExpression` - the candidate collection of the subquery as an expression using terms of the outer query
      Since:
        2.1
      See Also:
        `addSubquery(Query sub, String variableDeclaration, String candidateCollectionExpression, String... parameters)`

    - #### addSubquery

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

      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.
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable to be used in this Query
        `candidateCollectionExpression` - the candidate collection to apply to the subquery
        `parameter` - the expression from the outer query to bind the parameter in the subquery
      Since:
        2.1
      See Also:
        `addSubquery(Query sub, String variableDeclaration, String candidateCollectionExpression, String... parameters)`

    - #### addSubquery

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

      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.
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable in the outer query to bind the results of the subquery
        `candidateCollectionExpression` - the candidate collection of the subquery as an expression using terms of the outer query
        `parameters` - the expressions from the outer query to bind the parameters in the subquery
      Since:
        2.1

    - #### addSubquery

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

      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.
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable to be used in this Query
        `candidateCollectionExpression` - the candidate collection to apply to the subquery
        `parameters` - the expressions from the outer query to bind the parameter in the subquery
      Since:
        2.1
      See Also:
        `addSubquery(Query sub, String variableDeclaration, String candidateCollectionExpression, String... parameters)`

    - #### setDatastoreReadTimeoutMillis

          void setDatastoreReadTimeoutMillis(Integer interval)

      Specify a timeout interval (milliseconds) for any read operations associated with this query. To unset the explicit timeout for this query, specify null. For no timeout, specify 0. If the datastore granularity is larger than milliseconds, the timeout value will be rounded up to the nearest supported datastore value. If a read operation hasn't completed within this interval, executeXXX will throw a JDODatastoreException. If multiple datastore operations are required to complete the query, the timeout value applies to each of them individually. If the datastore and JDO implementation support timeouts, then javax.jdo.option.DatastoreTimeout is returned by PersistenceManagerFactory.supportedOptions(). If timeouts are not supported,this method will throw JDOUnsupportedOptionException.
      Parameters:
        `interval` - the timeout interval (milliseconds)
      Since:
        3.0

    - #### getDatastoreReadTimeoutMillis

          Integer getDatastoreReadTimeoutMillis()

      Get the effective timeout setting for read operations. If the timeout has not been set on this query explicitly, the effective datastore read timeout value from the persistence manager is returned.
      Returns:
        the effective timeout setting (milliseconds).
      Since:
        3.0
      See Also:
        `setDatastoreReadTimeoutMillis(Integer)`, `PersistenceManager.setDatastoreReadTimeoutMillis(Integer)`

    - #### setDatastoreWriteTimeoutMillis

          void setDatastoreWriteTimeoutMillis(Integer interval)

      Specify a timeout interval (milliseconds) for any write operations associated with this query. To unset the explicit timeout for this query, specify null. For no timeout, specify 0. If the datastore granularity is larger than milliseconds, the timeout value will be rounded up to the nearest supported datastore value. If a write operation hasn't completed within this interval, deleteXXX will throw a JDODatastoreException. If multiple datastore operations are required to complete the query, the timeout value applies to each of them individually. If the datastore and JDO implementation support timeouts, then javax.jdo.option.DatastoreTimeout is returned by PersistenceManagerFactory.supportedOptions(). If timeouts are not supported,this method will throw JDOUnsupportedOptionException.
      Parameters:
        `interval` - the timeout interval (milliseconds)
      Since:
        3.0

    - #### getDatastoreWriteTimeoutMillis

          Integer getDatastoreWriteTimeoutMillis()

      Get the effective timeout setting for write operations. If the timeout has not been set on this query explicitly, the effective datastore write timeout value from the persistence manager is returned.
      Returns:
        the effective timeout setting (milliseconds).
      Since:
        3.0
      See Also:
        `setDatastoreWriteTimeoutMillis(Integer)`, `PersistenceManager.setDatastoreWriteTimeoutMillis(Integer)`

    - #### cancelAll

          void cancelAll()

      Method to cancel any executing queries. If the underlying datastore doesn't support cancellation of queries this will throw JDOUnsupportedOptionException. If the cancellation fails (e.g in the underlying datastore) then this will throw a JDOException.
      Since:
        3.0

    - #### cancel

          void cancel(Thread thread)

      Method to cancel an executing query in the specified thread. If the underlying datastore doesn't support cancellation of queries this will throw JDOUnsupportedOptionException. If the cancellation fails (e.g in the underlying datastore) then this will throw a JDOException.
      Parameters:
        `thread` - The thread to cancel
      Since:
        3.0

    - #### setSerializeRead

          void setSerializeRead(Boolean serialize)

      If `true`, a lock will be applied to all objects read in this query.

      If `false` then retrieved objects will not be locked. If null will fallback to the value for metadata for the class in question.

      Parameters:
        `serialize` - the value of the serializeRead property
      Since:
        3.0

    - #### getSerializeRead

          Boolean getSerializeRead()

      Return the current value of the serializeRead property.
      Returns:
        the value of the serializeRead property
      Since:
        3.0

    - #### saveAsNamedQuery

          Query<T> saveAsNamedQuery(String name)

      Save the query, as it is currently defined, as a named query under the specified name. If a named query already exists under this name (either defined in metadata, or previously saved) then it will be overwritten.
      Parameters:
        `name` - Name to save it under.
      Returns:
        This query

    - #### filter

          Query<T> filter(String filter)

      Set the filter for the query. Shortcut for the `setFilter(String)` method
      Parameters:
        `filter` - the query filter.
      Returns:
        This query

    - #### orderBy

          Query<T> orderBy(String ordering)

      Set the ordering specification for the result `Collection`. Shortcut for the `setOrdering(String)` method
      Parameters:
        `ordering` - the ordering specification.
      Returns:
        This query

    - #### groupBy

          Query<T> groupBy(String group)

      Set the grouping expressions, optionally including a "having" clause. Shortcut for the `setGrouping(String)` method
      Parameters:
        `group` - a comma-delimited list of expressions, optionally followed by the "having" keyword and a boolean expression
      Returns:
        This query

    - #### result

          Query<T> result(String result)

      Set the result clause for the query. Shortcut for the `setResult(String)` method
      Parameters:
        `result` - The result clause
      Returns:
        This query

    - #### range

          Query<T> range(long fromIncl,
                         long toExcl)

      Set the range of results to return. Shortcut for the `setRange(long, long)` method
      Parameters:
        `fromIncl` - 0-based inclusive start index
        `toExcl` - 0-based exclusive end index, or `Long.MAX_VALUE` for no limit.
      Returns:
        This query

    - #### range

          Query<T> range(String fromInclToExcl)

      Set the range of results to return. Shortcut for the `setRange(String)` method
      Parameters:
        `fromInclToExcl` - comma-separated fromIncl and toExcl values
      Returns:
        This query

    - #### subquery

          Query<T> subquery(Query sub,
                            String variableDeclaration,
                            String candidateCollectionExpression)

      Add a subquery to this query. Shortcut for the `subquery(Query, String, String)` method
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable in the outer query to bind the results of the subquery
        `candidateCollectionExpression` - the candidate collection of the subquery as an expression using terms of the outer query
      Returns:
        This query

    - #### subquery

          Query<T> subquery(Query sub,
                            String variableDeclaration,
                            String candidateCollectionExpression,
                            String parameter)

      Add a subquery to this query. Shortcut for the `subquery(Query, String, String, String)` method
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable to be used in this Query
        `candidateCollectionExpression` - the candidate collection to apply to the subquery
        `parameter` - the expression from the outer query to bind the parameter in the subquery
      Returns:
        This query

    - #### subquery

          Query<T> subquery(Query sub,
                            String variableDeclaration,
                            String candidateCollectionExpression,
                            String... parameters)

      Add a subquery to this query. Shortcut for the `subquery(Query, String, String, String...)` method
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable in the outer query to bind the results of the subquery
        `candidateCollectionExpression` - the candidate collection of the subquery as an expression using terms of the outer query
        `parameters` - the expressions from the outer query to bind the parameters in the subquery
      Returns:
        This query

    - #### subquery

          Query<T> subquery(Query sub,
                            String variableDeclaration,
                            String candidateCollectionExpression,
                            Map parameters)

      Add a subquery to this query. Shortcut for the `subquery(Query, String, String, Map)` method
      Parameters:
        `sub` - the subquery to add to this Query
        `variableDeclaration` - the name of the variable to be used in this Query
        `candidateCollectionExpression` - the candidate collection to apply to the subquery
        `parameters` - the expressions from the outer query to bind the parameter in the subquery
      Returns:
        This query

    - #### imports

          Query<T> imports(String imports)

      Set the import statements to be used to identify the fully qualified name of variables or parameters. Shortcut for `declareImports(String)` method.
      Parameters:
        `imports` - the imports declaration
      Returns:
        This query

    - #### parameters

          Query<T> parameters(String parameters)

      Declare the list of parameters for query execution. Shortcut for `declareParameters(String)` method.
      Parameters:
        `parameters` - the list of parameters separated by commas.
      Returns:
        This query

    - #### variables

          Query<T> variables(String variables)

      Declare the unbound variables to be used in the query. Shortcut for `declareVariables(String)` method.
      Parameters:
        `variables` - the variables separated by semicolons.
      Returns:
        This query

    - #### datastoreReadTimeoutMillis

          Query<T> datastoreReadTimeoutMillis(Integer interval)

      Set the datastore read timeout (millis). Shortcut for `setDatastoreReadTimeoutMillis(Integer)` method.
      Parameters:
        `interval` - The interval
      Returns:
        This query

    - #### datastoreWriteTimeoutMillis

          Query<T> datastoreWriteTimeoutMillis(Integer interval)

      Set the datastore write timeout (millis). Shortcut for `setDatastoreWriteTimeoutMillis(Integer)` method.
      Parameters:
        `interval` - The interval
      Returns:
        This query

    - #### serializeRead

          Query<T> serializeRead(Boolean serialize)

      Set whether we to lock all objects read by this query. Shortcut for `setSerializeRead(Boolean)` method.
      Parameters:
        `serialize` - Whether to lock
      Returns:
        This query

    - #### unmodifiable

          Query<T> unmodifiable()

      Set whether to make this query unmodifiable. Shortcut for `setUnmodifiable()` method.
      Returns:
        This query

    - #### ignoreCache

          Query<T> ignoreCache(boolean flag)

      Set whether we to ignore the cache with this query. Shortcut for `setIgnoreCache(boolean)` method.
      Parameters:
        `flag` - Whether to ignore the cache
      Returns:
        This query

    - #### extension

          Query<T> extension(String key,
                             Object value)

      Specify an extension for this query. Shortcut for `addExtension(String, Object)` method.
      Parameters:
        `key` - The extension key
        `value` - The extension value
      Returns:
        This query

    - #### extensions

          Query<T> extensions(Map values)

      Specify a map of extensions for this query. Shortcut for `setExtensions(Map)` method.
      Parameters:
        `values` - The extension map of keys and values
      Returns:
        This query

    - #### setNamedParameters

          Query<T> setNamedParameters(Map<String,?> namedParamMap)

      Method to set the named parameters on this query prior to execution. If using the execute methods taking parameters then those parameter values will override these values. All parameter values specified in this method will only be retained until the subsequent query execution.
      Parameters:
        `namedParamMap` - The map of parameter values keyed by their names.
      Returns:
        This query

    - #### setParameters

          Query<T> setParameters(Object... paramValues)

      Method to set the values of the numbered parameters on this query prior to execution. If using the execute methods taking parameters then those parameter values will override these values. All parameter values specified in this method will only be retained until the subsequent query execution.
      Parameters:
        `paramValues` - Values of the numbered parameters, in order.
      Returns:
        This query

    - #### executeList

          List<T> executeList()

      Method to execute the query where there are (potentially) multiple rows and we are returning the candidate type. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

      Calling this method with a result being specified will result in JDOUserException being thrown.

      Returns:
        The List of candidate objects

    - #### executeUnique

          T executeUnique()

      Method to execute the query where there is a single row and we are returning the candidate type. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

      Calling this method with a result being specified will result in JDOUserException being thrown.

      Returns:
        The candidate object returned by the query (or null)

    - #### executeResultList

          <R> List<R> executeResultList(Class<R> resultCls)

      Method to execute the query where there are (potentially) multiple rows and we are returning a result type for the specified result. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

      Calling this method with no result being specified will result in JDOUserException being thrown.

      Type Parameters:
        `R` - The result type
      Parameters:
        `resultCls` - The result class
      Returns:
        List of result objects

    - #### executeResultUnique

          <R> R executeResultUnique(Class<R> resultCls)

      Method to execute the query where there is a single row and we are returning a result type for the specified result. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

      Calling this method with no result being specified will result in JDOUserException being thrown.

      Type Parameters:
        `R` - The result type
      Parameters:
        `resultCls` - The result class
      Returns:
        The result object (or null)

    - #### executeResultList

          List<Object> executeResultList()

      Method to execute the query where there are (potentially) multiple rows and we have a result defined but no result class. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

      Calling this method with no result being specified will result in JDOUserException being thrown.

      Returns:
        The list of query results

    - #### executeResultUnique

          Object executeResultUnique()

      Method to execute the query where there is a single row and we have a result defined but no result class. Any parameters required should be set prior to calling this method, using one of the setParameters methods.

      Calling this method with no result being specified will result in JDOUserException being thrown.

      Returns:
        The query result (or null)

Copyright © 2005–2022 The Apache Software Foundation. All rights reserved.