|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
Field Summary | |
static java.lang.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 java.lang.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 | |
void |
addExtension(java.lang.String key,
java.lang.Object value)
Add a vendor-specific extension to this query. |
void |
close(java.lang.Object queryResult)
Close a query result and release any resources associated with it. |
void |
closeAll()
Close all query results associated with this Query instance, and release all
resources associated with them. |
void |
compile()
Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan. |
void |
declareImports(java.lang.String imports)
Set the import statements to be used to identify the fully qualified name of variables or parameters. |
void |
declareParameters(java.lang.String parameters)
Declare the list of parameters query execution. |
void |
declareVariables(java.lang.String variables)
Declare the unbound variables to be used in the query. |
long |
deletePersistentAll()
Deletes all the instances of the candidate class that pass the filter. |
long |
deletePersistentAll(java.util.Map parameters)
Deletes all the instances of the candidate class that pass the filter. |
long |
deletePersistentAll(java.lang.Object[] parameters)
Deletes all the instances of the candidate class that pass the filter. |
java.lang.Object |
execute()
Execute the query and return the filtered Collection. |
java.lang.Object |
execute(java.lang.Object p1)
Execute the query and return the filtered Collection . |
java.lang.Object |
execute(java.lang.Object p1,
java.lang.Object p2)
Execute the query and return the filtered Collection . |
java.lang.Object |
execute(java.lang.Object p1,
java.lang.Object p2,
java.lang.Object p3)
Execute the query and return the filtered Collection . |
java.lang.Object |
executeWithArray(java.lang.Object[] parameters)
Execute the query and return the filtered Collection .
|
java.lang.Object |
executeWithMap(java.util.Map parameters)
Execute the query and return the filtered Collection . |
FetchPlan |
getFetchPlan()
Returns the FetchPlan used by this
Query . |
boolean |
getIgnoreCache()
Get the ignoreCache option setting. |
PersistenceManager |
getPersistenceManager()
Get the PersistenceManager associated with this Query .
|
boolean |
isUnmodifiable()
The unmodifiable flag, when set, disallows further modification of the query, except for specifying the range, result class, and ignoreCache option. |
void |
setCandidates(java.util.Collection pcs)
Set the candidate Collection to query. |
void |
setCandidates(Extent pcs)
Set the candidate Extent to query. |
void |
setClass(java.lang.Class cls)
Set the class of the candidate instances of the query. |
void |
setExtensions(java.util.Map extensions)
Set multiple extensions, or use null to clear all extensions. |
void |
setFilter(java.lang.String filter)
Set the filter for the query. |
void |
setGrouping(java.lang.String group)
Set the grouping expressions, optionally including a "having" clause. |
void |
setIgnoreCache(boolean ignoreCache)
Set the ignoreCache option. |
void |
setOrdering(java.lang.String ordering)
Set the ordering specification for the result Collection . |
void |
setRange(long fromIncl,
long toExcl)
Set the range of results to return. |
void |
setResult(java.lang.String data)
Specifies what type of data this query should return. |
void |
setResultClass(java.lang.Class cls)
Specify the type of object in which to return each element of the result of invoking execute() or one of its siblings.
|
void |
setUnique(boolean unique)
Specify that only the first result of the query should be returned, rather than a collection. |
void |
setUnmodifiable()
The unmodifiable flag, when set, disallows further modification of the query, except for specifying the range, result class, and ignoreCache option. |
Field Detail |
public static final java.lang.String JDOQL
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.
public static final java.lang.String SQL
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.
Method Detail |
public void setClass(java.lang.Class cls)
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.public void setCandidates(Extent pcs)
Extent
to query.
pcs
- the candidate Extent
.public void setCandidates(java.util.Collection pcs)
Collection
to query.
pcs
- the candidate Collection
.public void setFilter(java.lang.String filter)
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:
Class
of the Query
; and
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:
Date
fields and Date
parameters are valid.
=
, +=
, etc. and pre- and post-increment
and -decrement are not supported. Therefore, there are no side
effects from evaluation of any expressions.
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.
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.
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.public void declareImports(java.lang.String imports)
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.public void declareParameters(java.lang.String parameters)
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.public void declareVariables(java.lang.String variables)
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.public void setOrdering(java.lang.String ordering)
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.public void setIgnoreCache(boolean ignoreCache)
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.public boolean getIgnoreCache()
setIgnoreCache(boolean)
public void compile()
public java.lang.Object execute()
Collection
.executeWithArray(Object[] parameters)
public java.lang.Object execute(java.lang.Object p1)
Collection
.
p1
- the value of the first parameter declared.
Collection
.executeWithArray(Object[] parameters)
public java.lang.Object execute(java.lang.Object p1, java.lang.Object p2)
Collection
.
p1
- the value of the first parameter declared.p2
- the value of the second parameter declared.
Collection
.executeWithArray(Object[] parameters)
public java.lang.Object execute(java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)
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.
Collection
.executeWithArray(Object[] parameters)
public java.lang.Object executeWithMap(java.util.Map parameters)
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.
Collection
.executeWithArray(Object[] parameters)
public java.lang.Object executeWithArray(java.lang.Object[] parameters)
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.
Collection
.public PersistenceManager getPersistenceManager()
PersistenceManager
associated with this Query
.
If this Query
was restored from a serialized form, it has no
PersistenceManager
, and this method returns null
.
PersistenceManager
associated with this Query
.public void close(java.lang.Object queryResult)
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.public void closeAll()
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()
.
public void setGrouping(java.lang.String group)
group
- a comma-delimited list of expressions, optionally
followed by the "having" keyword and a boolean expressionpublic void setUnique(boolean unique)
unique
- if true, only one element is returnedpublic void setResult(java.lang.String data)
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 querypublic void setResultClass(java.lang.Class cls)
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:
set
or put
methods or fields.
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.
set
cls
- the result classpublic void setRange(long fromIncl, long toExcl)
fromIncl
- 0-based inclusive start indextoExcl
- 0-based exclusive end index, or
Long.MAX_VALUE
for no limit.public void addExtension(java.lang.String key, java.lang.Object value)
key
- the key of the extensionvalue
- the value of the extensionpublic void setExtensions(java.util.Map extensions)
extensions
- the map of extensionsaddExtension(java.lang.String, java.lang.Object)
public FetchPlan getFetchPlan()
FetchPlan
used by this
Query
. Modifications of the returned fetch plan will not
cause this query's owning PersistenceManager
's
FetchPlan
to be modified.
public long deletePersistentAll(java.lang.Object[] parameters)
parameters
- for the query
deletePersistentAll()
public long deletePersistentAll(java.util.Map parameters)
parameters
- for the query
deletePersistentAll()
public long deletePersistentAll()
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.
public void setUnmodifiable()
public boolean isUnmodifiable()
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |