org.apache.jdo.impl.jdoql
Class QueryImpl

java.lang.Object
  extended by org.apache.jdo.impl.jdoql.QueryImpl
All Implemented Interfaces:
java.io.Serializable, javax.jdo.Query

public class QueryImpl
extends java.lang.Object
implements javax.jdo.Query

This class implements the JDO query interface (see Query).

Author:
Michael Bouschen
See Also:
Serialized Form

Field Summary
 
Fields inherited from interface javax.jdo.Query
JDOQL, SQL
 
Constructor Summary
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm)
          Create an empty query instance with no elements.
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm, java.lang.Class cls)
          Create a new Query specifying the Class of the candidate instances.
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm, java.lang.Class cls, java.util.Collection cln)
          Create a query instance with the candidate class and candidate collection specified.
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm, java.lang.Class cls, java.util.Collection cln, java.lang.String filter)
          Create a new Query with the Class of the candidate instances, candidate Collection, and filter.
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm, java.lang.Class cls, java.lang.String filter)
          Create a new Query with the Class of the candidate instances and Filter.
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm, javax.jdo.Extent cln)
          Create a new Query with the candidate Extent; the class is taken from the Extent.
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm, javax.jdo.Extent cln, java.lang.String filter)
          Create a new Query with the candidate Extent and filter; the class is taken from the Extent.
QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm, java.lang.Object compiled)
          Create a new Query using elements from another Query.
 
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.
 javax.jdo.FetchPlan getFetchPlan()
          Returns the FetchPlan used by this Query.
 boolean getIgnoreCache()
          Get the ignoreCache option setting.
 javax.jdo.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(javax.jdo.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 setRange(java.lang.String fromInclToExcl)
          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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm)
Create an empty query instance with no elements.


QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm,
                 java.lang.Object compiled)
Create a new Query using elements from another Query. The other Query must have been created by the same JDO implementation. It might be active in a different PersistenceManager or might have been serialized and restored.

All of the settings of the other Query are copied to this Query, except for the candidate Collection or Extent.

Parameters:
compiled - another Query from the same JDO implementation

QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm,
                 java.lang.Class cls)
Create a new Query specifying the Class of the candidate instances.

Parameters:
cls - the Class of the candidate instances

QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm,
                 javax.jdo.Extent cln)
Create a new Query with the candidate Extent; the class is taken from the Extent.

Parameters:
cln - the Extent of candidate instances

QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm,
                 java.lang.Class cls,
                 java.util.Collection cln)
Create a query instance with the candidate class and candidate collection specified.

Parameters:
cls - the Class of the candidate instances.
cln - the Collection of candidate instances.

QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm,
                 java.lang.Class cls,
                 java.lang.String filter)
Create a new Query with the Class of the candidate instances and Filter.

Parameters:
cls - the Class of results
filter - the filter for candidate instances

QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm,
                 java.lang.Class cls,
                 java.util.Collection cln,
                 java.lang.String filter)
Create a new Query with the Class of the candidate instances, candidate Collection, and filter.

Parameters:
cls - the Class of candidate instances
cln - the Collection of candidate instances
filter - the filter for candidate instances

QueryImpl

public QueryImpl(org.apache.jdo.pm.PersistenceManagerInternal pm,
                 javax.jdo.Extent cln,
                 java.lang.String filter)
Create a new Query with the candidate Extent and filter; the class is taken from the Extent.

Parameters:
cln - the Extent of candidate instances
filter - the filter for candidate instances
Method Detail

setClass

public void setClass(java.lang.Class cls)
Set the class of the candidate instances of the query.

The class specifies the class of the candidates of the query. Elements of the candidate collection that are of the specified class are filtered before being put into the result Collection.

Specified by:
setClass in interface javax.jdo.Query
Parameters:
cls - the Class of the candidate instances.

setCandidates

public void setCandidates(javax.jdo.Extent pcs)
Set the candidate Extent to query.

Specified by:
setCandidates in interface javax.jdo.Query
Parameters:
pcs - the Candidate Extent.

setCandidates

public void setCandidates(java.util.Collection pcs)
Set the candidate Collection to query.

Specified by:
setCandidates in interface javax.jdo.Query
Parameters:
pcs - the Candidate collection.

setFilter

public void setFilter(java.lang.String filter)
Set the filter for the query.

Specified by:
setFilter in interface javax.jdo.Query
Parameters:
filter - the query filter.

declareImports

public void declareImports(java.lang.String imports)
Set the import statements to be used to identify the fully qualified name of variables or parameters. Parameters and unbound variables might come from a different class from the candidate class, and the names need to be declared in an import statement to eliminate ambiguity. Import statements are specified as a String with semicolon-separated statements.

The String parameter to this method follows the syntax of the import statement of the Java language.

Specified by:
declareImports in interface javax.jdo.Query
Parameters:
imports - import statements separated by semicolons.

declareParameters

public void declareParameters(java.lang.String parameters)
Declare the list of parameters query execution. The parameter declaration is a String containing one or more query parameter declarations separated with commas. Each parameter named in the parameter declaration must be bound to a value when the query is executed.

The String parameter to this method follows the syntax for formal parameters in the Java language.

Specified by:
declareParameters in interface javax.jdo.Query
Parameters:
parameters - the list of parameters separated by commas.

declareVariables

public void declareVariables(java.lang.String variables)
Declare the unbound variables to be used in the query. Variables might be used in the filter, and these variables must be declared with their type. The unbound variable declaration is a String containing one or more unbound variable declarations separated with semicolons. It follows the syntax for local variables in the Java language.

Specified by:
declareVariables in interface javax.jdo.Query
Parameters:
variables - the variables separated by semicolons.

setOrdering

public void setOrdering(java.lang.String ordering)
Set the ordering specification for the result Collection. The ordering specification is a String containing one or more ordering declarations separated by commas.

Each ordering declaration is the name of the field on which to order the results followed by one of the following words: "ascending" or "descending".

The field must be declared in the candidate class or must be a navigation expression starting with a field in the candidate class.

Valid field types are primitive types except boolean; wrapper types except Boolean; BigDecimal; BigInteger; String; and Date.

Specified by:
setOrdering in interface javax.jdo.Query
Parameters:
ordering - the ordering specification.

setIgnoreCache

public void setIgnoreCache(boolean ignoreCache)
Set the ignoreCache option. The default value for this option was set by the PersistenceManagerFactory or the PersistenceManager used to create this Query. The ignoreCache option setting specifies whether the query should execute entirely in the back end, instead of in the cache. If this flag is set to true, an implementation might be able to optimize the query execution by ignoring changed values in the cache. For optimistic transactions, this can dramatically improve query response times.

Specified by:
setIgnoreCache in interface javax.jdo.Query
Parameters:
ignoreCache - the setting of the ignoreCache option.

getIgnoreCache

public boolean getIgnoreCache()
Get the ignoreCache option setting.

Specified by:
getIgnoreCache in interface javax.jdo.Query
Returns:
the ignoreCache option setting.
See Also:
setIgnoreCache(boolean)

compile

public void compile()
Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.

Specified by:
compile in interface javax.jdo.Query

execute

public java.lang.Object execute()
Execute the query and return the filtered Collection.

Specified by:
execute in interface javax.jdo.Query
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)

execute

public java.lang.Object execute(java.lang.Object p1)
Execute the query and return the filtered Collection.

Specified by:
execute in interface javax.jdo.Query
Parameters:
p1 - the value of the first parameter declared.
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)

execute

public java.lang.Object execute(java.lang.Object p1,
                                java.lang.Object p2)
Execute the query and return the filtered Collection.

Specified by:
execute in interface javax.jdo.Query
Parameters:
p1 - the value of the first parameter declared.
p2 - the value of the second parameter declared.
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)

execute

public java.lang.Object execute(java.lang.Object p1,
                                java.lang.Object p2,
                                java.lang.Object p3)
Execute the query and return the filtered Collection.

Specified by:
execute in interface javax.jdo.Query
Parameters:
p1 - the value of the first parameter declared.
p2 - the value of the second parameter declared.
p3 - the value of the third parameter declared.
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)

executeWithMap

public java.lang.Object executeWithMap(java.util.Map parameters)
Execute the query and return the filtered Collection.

Specified by:
executeWithMap in interface javax.jdo.Query
Parameters:
parameters - the Map containing all of the parameters.
Returns:
the filtered Collection.
See Also:
executeWithArray(Object[] parameters)

executeWithArray

public java.lang.Object executeWithArray(java.lang.Object[] parameters)
Execute the query and return the filtered Collection.

The execution of the query obtains the values of the parameters and matches them against the declared parameters in order. The names of the declared parameters are ignored. The type of the declared parameters must match the type of the passed parameters, except that the passed parameters might need to be unwrapped to get their primitive values.

The filter, import, declared parameters, declared variables, and ordering statements are verified for consisten1cy.

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.

Specified by:
executeWithArray in interface javax.jdo.Query
Parameters:
parameters - the Object array with all of the parameters.
Returns:
the filtered Collection.

getPersistenceManager

public javax.jdo.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.

Specified by:
getPersistenceManager in interface javax.jdo.Query
Returns:
the PersistenceManager associated with this Query.

close

public void close(java.lang.Object queryResult)
Close a query result and release any resources associated with it. The parameter is the return from execute(...) and might have iterators open on it. Iterators associated with the query result are invalidated: they return false to hasNext() and throw NoSuchElementException to next().

Specified by:
close in interface javax.jdo.Query
Parameters:
queryResult - the result of execute(...) on this Query instance.

closeAll

public void closeAll()
Close all query results associated with this Query instance, and release all resources associated with them. The query results might have iterators open on them. Iterators associated with the query results are invalidated: they return false to hasNext() and throw NoSuchElementException to next().

Specified by:
closeAll in interface javax.jdo.Query

setGrouping

public void setGrouping(java.lang.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.

Specified by:
setGrouping in interface javax.jdo.Query
Parameters:
group - a comma-delimited list of expressions, optionally followed by the "having" keyword and a boolean expression
Since:
2.0

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.

Specified by:
setUnique in interface javax.jdo.Query
Parameters:
unique - if true, only one element is returned
Since:
2.0

setResult

public void setResult(java.lang.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.

Specified by:
setResult in interface javax.jdo.Query
Parameters:
data - a comma-delimited list of expressions (fields, functions on fields, or aggregate functions) to return from this query
Since:
2.0

setResultClass

public 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. 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:

Portable result classes do not invoke any persistence behavior during their no-args constructor or set
Specified by:
setResultClass in interface javax.jdo.Query
Parameters:
cls - the result class
Since:
2.0

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.

Specified by:
setRange in interface javax.jdo.Query
Parameters:
fromIncl - 0-based inclusive start index
toExcl - 0-based exclusive end index, or Long.MAX_VALUE for no limit.
Since:
2.0

setRange

public void setRange(java.lang.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.

Specified by:
setRange in interface javax.jdo.Query
Parameters:
fromInclToExcl - comma-separated fromIncl and toExcl values
Since:
2.0
See Also:
setRange(long, long)

addExtension

public void addExtension(java.lang.String key,
                         java.lang.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.

Specified by:
addExtension in interface javax.jdo.Query
Parameters:
key - the key of the extension
value - the value of the extension
Since:
2.0

setExtensions

public void setExtensions(java.util.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.

Specified by:
setExtensions in interface javax.jdo.Query
Parameters:
extensions - the map of extensions
Since:
2.0
See Also:
addExtension(java.lang.String, java.lang.Object)

getFetchPlan

public javax.jdo.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.

Specified by:
getFetchPlan in interface javax.jdo.Query
Returns:
the fetch plan used by this query
Since:
2.0

deletePersistentAll

public long deletePersistentAll(java.lang.Object[] parameters)
Deletes all the instances of the candidate class that pass the filter.

Specified by:
deletePersistentAll in interface javax.jdo.Query
Parameters:
parameters - for the query
Returns:
the number of instances of the candidate class that were deleted
Since:
2.0
See Also:
deletePersistentAll()

deletePersistentAll

public long deletePersistentAll(java.util.Map parameters)
Deletes all the instances of the candidate class that pass the filter.

Specified by:
deletePersistentAll in interface javax.jdo.Query
Parameters:
parameters - for the query
Returns:
the number of instances of the candidate class that were deleted
Since:
2.0
See Also:
deletePersistentAll()

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.

Specified by:
deletePersistentAll in interface javax.jdo.Query
Returns:
the number of instances of the candidate class that were deleted
Since:
2.0

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.

Specified by:
setUnmodifiable in interface javax.jdo.Query
Since:
2.0

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.

Specified by:
isUnmodifiable in interface javax.jdo.Query
Returns:
the current setting of the flag
Since:
2.0


Copyright © 2005-2011 Apache Software Foundation. All Rights Reserved.