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.
addExtension
public 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.
key
- the key of the extensionvalue
- the value of the extension
close
public 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()
.
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()
.
compile
public void compile()
Verify the elements of the query and provide a hint to the query to
prepare and optimize an execution plan.
declareImports
public 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.
imports
- import statements separated by semicolons.
declareParameters
public 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
- the list of parameters separated by commas.
declareVariables
public 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.
variables
- the variables separated by semicolons.
deletePersistentAll
public 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.
- the number of instances of the candidate class that were deleted
deletePersistentAll
public long deletePersistentAll(Map parameters)
Deletes all the instances of the candidate class that pass the
filter.
parameters
- for the query
- the number of instances of the candidate class that were deleted
deletePersistentAll
public long deletePersistentAll(Object[] parameters)
Deletes all the instances of the candidate class that pass the
filter.
parameters
- for the query
- the number of instances of the candidate class that were deleted
execute
public Object execute()
Execute the query and return the filtered Collection.
executeWithArray(Object[] parameters)
execute
public Object execute(Object p1)
Execute the query and return the filtered Collection
.
p1
- the value of the first parameter declared.
executeWithArray(Object[] parameters)
execute
public Object execute(Object p1,
Object p2)
Execute the query and return the filtered Collection
.
p1
- the value of the first parameter declared.p2
- the value of the second parameter declared.
executeWithArray(Object[] parameters)
execute
public Object execute(Object p1,
Object p2,
Object p3)
Execute the query and return the filtered Collection
.
p1
- the value of the first parameter declared.p2
- the value of the second parameter declared.p3
- the value of the third parameter declared.
executeWithArray(Object[] parameters)
executeWithArray
public Object executeWithArray(Object[] parameters)
Execute the query and return the filtered
Collection
.
The execution of the query obtains the values of the parameters and
matches them against the declared parameters in order. The names
of the declared parameters are ignored. The type of
the declared parameters must match the type of the passed parameters,
except that the passed parameters might need to be unwrapped to get
their primitive values.
The filter, import, declared parameters, declared variables, and
ordering statements are verified for consistency.
Each element in the candidate
Collection
is examined to
see that it is assignment compatible to the
Class
of the
query. It is then evaluated by the Boolean expression of the filter.
The element passes the filter if there exist unique values for all
variables for which the filter expression evaluates to
true
.
parameters
- the Object
array with all of the
parameters.
executeWithMap
public Object executeWithMap(Map parameters)
Execute the query and return the filtered Collection
. The
query is executed with the parameters set by the Map
values.
Each Map
entry consists of a key which is the name of the
parameter in the declareParameters
method, and a value which
is the value used in the execute
method. The keys in the
Map
and the declared parameters must exactly match or a
JDOUserException
is thrown.
parameters
- the Map
containing all of the parameters.
executeWithArray(Object[] parameters)
getFetchPlan
public 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.
- the fetch plan used by this query
getIgnoreCache
public boolean getIgnoreCache()
Get the ignoreCache option setting.
- the ignoreCache option setting.
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
.
- the
PersistenceManager
associated with this
Query
.
isUnmodifiable
public boolean isUnmodifiable()
The unmodifiable flag, when set, disallows further
modification of the query, except for specifying the range,
result class, and ignoreCache option.
- the current setting of the flag
setCandidates
public void setCandidates(Collection pcs)
Set the candidate Collection
to query.
pcs
- the candidate Collection
.
setCandidates
public void setCandidates(Extent pcs)
Set the candidate Extent
to query.
pcs
- the candidate Extent
.
setClass
public void setClass(Class cls)
Set the class of the candidate instances of the query.
The class specifies the class
of the candidates of the query. Elements of the candidate collection
that are of the specified class are filtered before being
put into the result
Collection
.
cls
- the Class
of the candidate instances.
setExtensions
public 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.
extensions
- the map of extensions
setFilter
public 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.
filter
- the query filter.
setGrouping
public 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.
group
- a comma-delimited list of expressions, optionally
followed by the "having" keyword and a boolean expression
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.
ignoreCache
- the setting of the ignoreCache option.
setOrdering
public 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
.
ordering
- the ordering specification.
setRange
public 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.
fromInclToExcl
- comma-separated fromIncl and toExcl values
setRange
public 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.
fromIncl
- 0-based inclusive start indextoExcl
- 0-based exclusive end index, or
Long.MAX_VALUE
for no limit.
setResult
public 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.
data
- a comma-delimited list of expressions
(fields, functions on fields, or aggregate functions)
to return from this query
setResultClass
public 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
- 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
setUnique
public 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.
unique
- if true, only one element is returned
setUnmodifiable
public 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.