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

Constructor Summary
QueryImpl(PersistenceManagerInternal pm)
          Create an empty query instance with no elements.
QueryImpl(PersistenceManagerInternal pm, java.lang.Class cls)
          Create a new Query specifying the Class of the candidate instances.
QueryImpl(PersistenceManagerInternal pm, java.lang.Class cls, java.util.Collection cln)
          Create a query instance with the candidate class and candidate collection specified.
QueryImpl(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(PersistenceManagerInternal pm, java.lang.Class cls, java.lang.String filter)
          Create a new Query with the Class of the candidate instances and Filter.
QueryImpl(PersistenceManagerInternal pm, javax.jdo.Extent cln)
          Create a new Query with the candidate Extent; the class is taken from the Extent.
QueryImpl(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(PersistenceManagerInternal pm, java.lang.Object compiled)
          Create a new Query using elements from another Query.
 
Method Summary
 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.
 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.
 boolean getIgnoreCache()
          Get the ignoreCache option setting.
 javax.jdo.PersistenceManager getPersistenceManager()
          Get the PersistenceManager associated with this Query.
 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 setFilter(java.lang.String filter)
          Set the filter for the query.
 void setIgnoreCache(boolean ignoreCache)
          Set the ignoreCache option.
 void setOrdering(java.lang.String ordering)
          Set the ordering specification for the result Collection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

QueryImpl

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


QueryImpl

public QueryImpl(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(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(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(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(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(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(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


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