Class COM.odi.util.query.Query

java.lang.Object
   |
   +----COM.odi.util.query.Query

public class Query
extends Object

A Query object represents a query with zero or more free variables.

There are three steps to query usage: creation, optimization (optional), and execution.

There are three arguments to query creation: the query elementType, the queryExpression string, and an optional FreeVariables map.

The elementType class provides the context in which the queryExpression is interpreted. This must be a publicly accessible class. When the query is executed against a particular collection using the select(), pick(), or iterator() method, every element of that collection must be an instance of (in the sense of instanceof) the elementType that was specified when the query was created.

The queryExpression is a predicate (that is, an expression with a boolean result). The query is executed on a collection by evaluating this query expression on each element of the collection (it may not be necessary, however, to explicitly fetch and examine all elements of the collection, depending upon the available indexes and query optimization strategy). Complete query syntax information is in the user guide.

The queryExpression may contain both literals and names. Literals can be of any of the Java primitive types, including the special values true,false, and null. Note that because the query expression is itself a string, any embedded string literals must be inclosed in escaped quotes, like \"this\".

Names can be simple, consisting of a single identifier, or they can consist of a sequence of identifiers separated by ".". Names can be either free variables, or they can be member accesses. Free variables must be explicitly specified in the freeVariables argument. Any name that is not a free variable is interpreted as a member access. Member accesses are interpreted if possible as accessing public members, including class and instance fields, and class and instance methods of an object of class elementType. This interpretation works as though there were an implicit "this" argument, of elementType, at the root of the name expression. Any member access that cannot be interpreted as a member access on elementType is interpreted as a static access. Static accesses are resolved as if the package containing elementType were imported.

Once a query has been created, it can be optimized for use with a particular set of indexes, and then executed on a particular collection, using either the select(), pick(), or iterator() method; or it can be executed without prior explicit optimization, in which case it is optimized automatically when it is executed, based on the indexes actually available on the specified collection.

Additional information about queries is in the user guide.

Query(Class, String): Create a Query object.
Query(Class, String, FreeVariables): Create a Query object.

isOptimized(): Check whether a query has been explicitly optimized using the optimize() method.
iterator(Collection): Queries a collection and returns an iterator that yields the elements that match the query predicate.
iterator(Collection, FreeVariableBindings): Queries a collection and returns an iterator that yields the elements that match the query predicate.
optimize(IndexDescriptorSet): Optimize a query for a particular set of indexes.
pick(Collection): Queries a collection and returns an element that matches the query predicate.
pick(Collection, FreeVariableBindings): Queries a collection and returns an element that matches the query predicate.
select(Collection): Queries a collection and returns a newly-created Set containing the elements that match the query predicate.
select(Collection, FreeVariableBindings): Queries a collection and returns a newly-created Set containing the elements that match the query predicate.

Query

  public Query(Class elementType,
               String queryExpression,
               FreeVariables freeVariables)

Create a Query object. The query can be optimized later by running the optimize() method, and then used to query a collection using the select(), pick(), or iterator() method; or it can be applied directly to a collection using the select(), pick(), or iterator() method without any prior optimization, in which case it will be optimized on the fly against whatever indexes are available on that collection at runtime.

Parameters:: elementType - The class that provides the context in which the queryExpression is interpreted. The elementType class must be public. When the query is executed on a particular collection (using the Query.select(), Query.pick(), or Query.iterator() method), all elements of the collection must be of this type.; queryExpression - A predicate expression (that is, an expression that evaluates to a boolean result), which can be evaluated on objects of type elementType. When the query is run on a particular collection (using the Query.select(), Query.pick(), or Query.iterator() method) this expression is evaluated on the elements of that collection, and only those elements for which the expression returns true are returned in the query result. Note that a query expression should not side-effect data in a way that might alter the query results, or the query could return incorrect results.; freeVariables - A FreeVariables map containing key/value pairs that describe any free variables in the query expression. The keys are Strings (matching the free variable string as it appears in the query expression) and the values are classes, which specify the type of the corresponding free variable. All free variables must be bound when the query is executed, by passing a corresponding FreeVariableBindings map to the select(), pick(), or iterator() method.
Throws: IllegalArgumentException: If the elementType or queryExpression parameters are null.
Throws: QueryException: if the queryExpression is invalid, or the queryExpression attempts to access non-public members, or there are free variables in the queryExpression that are not listed in the freeVariables parameter, or there are free variables listed in the freeVariables parameter that are not in the queryExpression.

Query

  public Query(Class elementType,
               String queryExpression)

Parameters:: elementType - The class that provides the context in which the queryExpression is interpreted. The elementType class must be public. When the query is executed on a particular collection (using the Query.select(), Query.pick(), or Query.iterator() method), all elements of the collection must be of this type.; queryExpression - A predicate expression (that is, an expression that evaluates to a boolean result), which can be evaluated on objects of type elementType. When the query is run on a particular collection (using the Query.select(), Query.pick(), or Query.iterator() method) this expression is evaluated on the elements of that collection, and only those elements for which the expression returns true are returned in the query result. Note that a query expression should not side-effect data in a way that might alter the query results, or the query could return incorrect results.
Throws: IllegalArgumentException: If the elementType or queryExpression parameters are null.
Throws: QueryException: if the queryExpression is invalid, or the queryExpression attempts to access non-public members, or there are free variables in the queryExpression.

select

  public Set select(Collection coll,
                    FreeVariableBindings freeVariableBindings)

Queries a collection and returns a newly-created Set containing the elements that match the query predicate.

Parameters:: coll - The collection to be queried. If the query has been pre-optimized using the optimize() method, then any indexes that were specified in the optimization must be available on this collection. If the query was not explicitly pre-optimized using the optimize() method, then it will be optimized on the fly if necessary when select() is executed, based on the indexes that are available on the given collection.; freeVariableBindings - An instance of FreeVariableBindings that defines bindings for each free variable used by the query. For each entry, the key is a String that identifies the free variable, and the value is the value that should be associated with the free variable during the evaluation of the query. The value must be of the type specified by the corresponding entry in the FreeVariables argument passed to the Query constructor. Every free variable associated with the query when it was constructed must have a corresponding binding before the query can be evaluated, and every free variable binding must correspond to a free variable that was specified when the query was constructed.
Returns:: A Set that contains the elements that matched the query. If no elements are found to match the query, ObjectStore returns an empty collection.
Throws: IllegalArgumentException: If the coll parameter is null.
Throws: ClassCastException: If the collection contains elements that are not of the type specified by the query's elementType.
Throws: InvalidPatternException: If the query has an invalid pattern operand to the '~~' pattern matching operation, and the operand was the value of a free variable, a field, or the return value of a method.
Throws: QueryIndexMismatchException: If the optimize() method was called on the query with indexes that are not available on the specified collection.
Throws: QueryException: If the free variable bindings do not match the free variable definitions specified during the creation of the query.

select

  public Set select(Collection coll)

Queries a collection and returns a newly-created Set containing the elements that match the query predicate.

Parameters:: coll - The collection to be queried. If the query has been pre-optimized using the optimize() method, then any indexes that were specified in the optimization must be available on this collection. If the query was not explicitly pre-optimized using the optimize() method, then it will be optimized on the fly if necessary when select() is executed, based on the indexes that are available on the given collection.
Returns:: A Set that contains the elements that matched the query. If no elements are found to match the query, ObjectStore returns an empty collection.
Throws: IllegalArgumentException: If the coll parameter is null.
Throws: ClassCastException: If the collection contains elements that are not of the type specified by the query's elementType.
Throws: InvalidPatternException: If the query has an invalid pattern operand to the '~~' pattern matching operation, and the operand was the value of a free variable, a field, or the return value of a method.
Throws: QueryIndexMismatchException: If the optimize() method was called on the query with indexes that are not available on the specified collection.
Throws: QueryException: If any free variable definitions were specified during the creation of the query.

pick

  public Object pick(Collection coll,
                     FreeVariableBindings freeVariableBindings)

Queries a collection and returns an element that matches the query predicate. If no elements of the specified collection match the query predicate, ObjectStore throws NoSuchElementException.

Parameters:: coll - The collection to be queried. If the query has been pre-optimized using the optimize() method, then any indexes that were specified in the optimization must be available on this collection. If the query was not explicitly pre-optimized using the optimize() method, then it will be optimized on the fly if necessary when pick() is executed, based on the indexes that are available on the given collection.; freeVariableBindings - An instance of FreeVariableBindings that defines bindings for each free variable used by the query. For each entry, the key is a String that identifies the free variable, and the value is the value that should be associated with the free variable during the evaluation of the query. The value must be of the type specified by the corresponding entry in the FreeVariables argument passed to the Query constructor. Every free variable associated with the query when it was constructed must have a corresponding binding before the query can be evaluated, and every free variable binding must correspond to a free variable that was specified when the query was constructed.
Returns:: An element of the collection that matches the query.
Throws: NoSuchElementException: If no element of the collection matches the query.
Throws: ClassCastException: If the collection contains elements that are not of the type specified by the query's elementType.
Throws: IllegalArgumentException: If the coll parameter is null.
Throws: InvalidPatternException: If the query has an invalid pattern operand to the '~~' pattern matching operation, and the operand was the value of a free variable, a field, or the return value of a method.
Throws: QueryIndexMismatchException: If the optimize() method was called on the query with indexes that are not available on the specified collection.
Throws: QueryException: If the free variable bindings do not match the free variable definitions specified during the creation of the query.

pick

  public Object pick(Collection coll)

Queries a collection and returns an element that matches the query predicate. If no elements of the specified collection match the query predicate, ObjectStore throws NoSuchElementException.

Parameters:: coll - The collection to be queried. If the query has been pre-optimized using the optimize() method, then any indexes that were specified in the optimization must be available on this collection. If the query was not explicitly pre-optimized using the optimize() method, then it will be optimized on the fly if necessary when pick() is executed, based on the indexes that are available on the given collection.
Returns:: An element of the collection that matches the query.
Throws: NoSuchElementException: If no element of the collection matches the query.
Throws: ClassCastException: If the collection contains elements that are not of the type specified by the query's elementType.
Throws: IllegalArgumentException: If the coll parameter is null.
Throws: InvalidPatternException: If the query has an invalid pattern operand to the '~~' pattern matching operation, and the operand was the value of a free variable, a field, or the return value of a method.
Throws: QueryIndexMismatchException: If the optimize() method was called on the query with indexes that are not available on the specified collection.
Throws: QueryException: If any free variable definitions were specified during the creation of the query.

iterator

  public Iterator iterator(Collection coll,
                           FreeVariableBindings freeVariableBindings)

Queries a collection and returns an iterator that yields the elements that match the query predicate.

Parameters:: coll - The collection to be queried. If the query has been pre-optimized using the optimize() method, then any indexes that were specified in the optimization must be available on this collection. If the query was not explicitly pre-optimized using the optimize() method, then it will be optimized on the fly if necessary when iterator() is executed, based on the indexes that are available on the given collection.; freeVariableBindings - An instance of FreeVariableBindings that defines bindings for each free variable used by the query. For each entry, the key is a String that identifies the free variable, and the value is the value that should be associated with the free variable during the evaluation of the query. The value must be of the type specified by the corresponding entry in the FreeVariables argument passed to the Query constructor. Every free variable associated with the query when it was constructed must have a corresponding binding before the query can be evaluated, and every free variable binding must correspond to a free variable that was specified when the query was constructed.
Returns:: An iterator that yields the elements of the collection that match the query. The iterator throws StaleEnumeratorException if it is used after being used in a transaction that was aborted, or if it is used after an transaction committed with the default retain option or with ObjectStore.RETAIN_STALE. The iterator throws UnsupportedOperationException if the remove() method is called on it.
Throws: ClassCastException: If the collection contains elements that are not of the type specified by the query's elementType.
Throws: IllegalArgumentException: If the coll parameter is null.
Throws: InvalidPatternException: If the query has an invalid pattern operand to the '~~' pattern matching operation, and the operand was the value of a free variable, a field, or the return value of a method.
Throws: QueryException: If the free variable bindings do not match the free variable definitions specified during the creation of the query.
Throws: QueryIndexMismatchException: If the optimize() method was called on the query with indexes that are not available on the specified collection.

iterator

  public Iterator iterator(Collection coll)

Queries a collection and returns an iterator that yields the elements that match the query predicate.

Parameters:: coll - The collection to be queried. If the query has been pre-optimized using the optimize() method, then any indexes that were specified in the optimization must be available on this collection. If the query was not explicitly pre-optimized using the optimize() method, then it will be optimized on the fly if necessary when iterator() is executed, based on the indexes that are available on the given collection.
Returns:: An iterator that yields the elements of the collection that match the query. The iterator throws StaleEnumeratorException if it is used after being used in a transaction that was aborted, or if it is used after an transaction committed with the default retain option or with ObjectStore.RETAIN_STALE. The iterator throws UnsupportedOperationException if the remove() method is called on it.
Throws: ClassCastException: If the collection contains elements that are not of the type specified by the query's elementType.
Throws: IllegalArgumentException: If the coll parameter is null.
Throws: InvalidPatternException: If the query has an invalid pattern operand to the '~~' pattern matching operation, and the operand was the value of a free variable, a field, or the return value of a method.
Throws: QueryException: If any free variable definitions were specified during the creation of the query.
Throws: QueryIndexMismatchException: If the optimize() method was called on the query with indexes that are not available on the specified collection.

optimize

  public synchronized void optimize(IndexDescriptorSet indexes)

Optimize a query for a particular set of indexes. If a query is not explicitly optimized (using the optimize() method) before being run with select(), pick(), or iterator(), then it will be optimized on the fly using whatever indexes are available on the collection that is queried. If a query is explicitly optimized before it is run, and the collection that is queried does not have all of the indexes that were specified to the optimize() method, then select(), pick(), or iterator() will throw QueryIndexMismatchException.

Note that a query can be optimized for one set of indexes, then reoptimized later for another set of indexes, by merely calling the optimize() method again.

Parameters:: Indexes - An IndexDescriptorSet containing IndexDescriptor objects that describe the indexes against which to optimize (this is typically obtained by calling IndexedCollection.getIndexes() on a collection that has the appropriate set of indexes).

isOptimized

  public boolean isOptimized()

Check whether a query has been explicitly optimized using the optimize() method.