org.apache.jdo.impl.jdoql
Class QueryImpl

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

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
private  java.lang.Class candidateClass
          The candidate class as specified by setClass.
private  java.lang.String candidateClassName
          The name of the candidate class (Needed for serialization support).
private  java.lang.Object candidates
          The candidates as specified by setCandidates.
private  Tree compiledTree
          The internal query representation as compilation result.
private  java.lang.String filterExpression
          The filter expression string as specified by setFilter.
private  boolean ignoreCache
          The ignoreCache flag as specified by setIgnoreCache.
private  java.lang.String importDeclarations
          The import declaration string as specified by declareImports.
private static I18NHelper msg
          I18N support
private  java.util.Set openQueryResults
          Set of open query result instances.
private  java.lang.String orderingSpecification
          The ordering specification string as specified by setOrdering.
private  java.lang.String parameterDeclarations
          The parameter declaration string as specified by declareParameters.
private  ParameterTable paramtab
          Represents parameter values.
private  PersistenceManagerInternal pm
          The pm for this query instance.
private  Tree queryTree
          The internal query representation set by the constructor taking a compiled query.
private  java.lang.String variableDeclarations
          The variable declaration string as specified by declareVariables.
private  VariableTable vartab
          Represents variable values.
 
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
private  void checkCandidates()
          This method checks a valid candidates setting for this query.
private  void checkQueryTreeCandidateClass()
          This method checks the candidate class of the underlying query tree.
private  void checkTransaction()
          This method verifies that if there is no transaction in progress then the NontransactionalRead flag must be set to true.
 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.
private  void readObject(java.io.ObjectInputStream in)
          Serialization support.
 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.
private  void writeObject(java.io.ObjectOutputStream out)
          Deserialization support.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

pm

private transient PersistenceManagerInternal pm
The pm for this query instance.


candidateClass

private transient java.lang.Class candidateClass
The candidate class as specified by setClass.


candidateClassName

private java.lang.String candidateClassName
The name of the candidate class (Needed for serialization support).


candidates

private transient java.lang.Object candidates
The candidates as specified by setCandidates.


importDeclarations

private java.lang.String importDeclarations
The import declaration string as specified by declareImports.


parameterDeclarations

private java.lang.String parameterDeclarations
The parameter declaration string as specified by declareParameters.


variableDeclarations

private java.lang.String variableDeclarations
The variable declaration string as specified by declareVariables.


orderingSpecification

private java.lang.String orderingSpecification
The ordering specification string as specified by setOrdering.


filterExpression

private java.lang.String filterExpression
The filter expression string as specified by setFilter.


ignoreCache

private boolean ignoreCache
The ignoreCache flag as specified by setIgnoreCache. The constructor defaults it to the PM setting.


compiledTree

private transient Tree compiledTree
The internal query representation as compilation result.


queryTree

private Tree queryTree
The internal query representation set by the constructor taking a compiled query.


paramtab

private ParameterTable paramtab
Represents parameter values.


vartab

private VariableTable vartab
Represents variable values.


openQueryResults

private transient java.util.Set openQueryResults
Set of open query result instances.


msg

private static final I18NHelper msg
I18N support

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

checkTransaction

private void checkTransaction()
This method verifies that if there is no transaction in progress then the NontransactionalRead flag must be set to true.


checkCandidates

private void checkCandidates()
This method checks a valid candidates setting for this query.


checkQueryTreeCandidateClass

private void checkQueryTreeCandidateClass()
This method checks the candidate class of the underlying query tree. If this query instance was created from a query tree, and subsequently serialized and deserialized then The class instance of the candidate class is not set. The class instance of the candidate class is not part of the serialized state of a querty tree; only the name gets stored. In this case the method uses the PM algorithm to calculate the class instance of the candidate class and stores it in the query tree.


readObject

private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Serialization support.

Throws:
java.io.IOException
java.lang.ClassNotFoundException

writeObject

private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException
Deserialization support.

Throws:
java.io.IOException