org.datanucleus.store.query
Class Query

java.lang.Object
  extended by org.datanucleus.store.query.Query
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AbstractJavaQuery, AbstractSQLQuery

public abstract class Query
extends java.lang.Object
implements java.io.Serializable

Abstract implementation for all queries in DataNucleus. Implementations of JDOQL, SQL, JPQL, etc should extend this. Parameters can be implicit (defined in the query via syntaxes such as ":name", "?1") or explicit (defined via declareParameters). They can also be named or numbered. When passing a map of parameters with values, they are keyed by String (named parameters) or Integer (numbered parameters).

See Also:
Serialized Form

Nested Class Summary
 class Query.SubqueryDefinition
          Simple representation of a subquery, its candidate, params and variables.
 
Field Summary
static short BULK_DELETE
           
static short BULK_UPDATE
           
protected  java.lang.Class candidateClass
          The candidate class for this query.
protected  java.lang.String candidateClassName
          Name of the candidate class (used when specified via Single-String).
protected  ClassLoaderResolver clr
           
protected  QueryCompilation compilation
          Query compilation (when using the generic query compiler).
protected  ExecutionContext ec
          ExecutionContext.
protected  java.lang.String explicitParameters
          Any explicit parameters defined for this query, comma separated.
protected  java.lang.String explicitVariables
          Any explicit variables defined for this query, semicolon separated.
protected  java.util.Map<java.lang.String,java.lang.Object> extensions
          Any extensions
protected  java.lang.String filter
          The filter for the query.
protected  java.lang.String from
          From clause of the query (optional).
protected  long fromInclNo
          Query result range start position (inclusive).
protected  java.lang.String fromInclParam
          Query result range lower limit (inclusive) as a parameter name.
protected  java.lang.String grouping
          Grouping clause for the query, for use with aggregate expressions.
protected  java.lang.String having
          Having clause for the query
protected  boolean ignoreCache
          Whether to ignore dirty instances in the query.
protected  java.util.HashMap implicitParameters
          Map of implicit parameters, keyed by the name/number.
protected  java.lang.String imports
          Any import declarations for the types used in the query, semicolon separated.
protected static Localiser LOCALISER
          Localiser for messages.
protected  java.lang.String ordering
          Ordering clause for the query, governing the order objects are returned.
static short OTHER
           
protected  java.lang.String[] parameterNames
          Array of (explicit) parameter names.
protected  Imports parsedImports
          The imports definition.
protected  java.util.HashSet<QueryResult> queryResults
          All query results obtained from this query.
protected  java.lang.String range
          String form of the query result range.
protected  java.lang.String result
          Specification of the result of the query e.g aggregates etc.
protected  java.lang.Class resultClass
          User-defined class that best represents the results of a query.
protected  java.lang.String resultClassName
          Temporary variable for the name of the result class (may need resolving using imports).
protected  boolean resultDistinct
          Whether the results are marked as distinct.
static short SELECT
           
protected  boolean subclasses
          Whether to allow subclasses of the candidate class be returned.
protected  java.util.Map<java.lang.String,Query.SubqueryDefinition> subqueries
          Any subqueries, keyed by the variable name that they represent.
protected  java.util.HashMap<java.lang.Thread,java.util.concurrent.FutureTask> tasks
          Currently executing task for this query, keyed by the thread.
protected  long toExclNo
          Query result range end position (exclusive).
protected  java.lang.String toExclParam
          Query result range upper limit (exclusive) as a parameter name.
protected  short type
          Type of query.
protected  boolean unique
          Whether to return single value, or collection from the query.
protected  boolean unmodifiable
          Whether the query can be modified
protected  java.lang.String update
          UPDATE clause of a query.
 
Constructor Summary
Query(ExecutionContext ec)
          Constructs a new query instance that uses the given object manager.
 
Method Summary
 void addExtension(java.lang.String key, java.lang.Object value)
          Add a vendor-specific extension this query.
 void addSubquery(Query sub, java.lang.String variableDecl, java.lang.String candidateExpr, java.util.Map paramMap)
          Method to add a subquery to this query.
protected  void applyImplicitParameterValueToCompilation(java.lang.String name, java.lang.Object value)
          Convenience method to apply an implicit parameter value to the compilation symbol table.
protected  boolean applyRangeChecks()
          Method to return if the query results should have the range checked and unnecessary rows discarded.
protected  void assertIsModifiable()
          Method to throw an exception if the query is currently not modifiable.
protected  void assertSupportsCancel()
          Method that will throw an UnsupportedOperationException if the query implementation doesn't support cancelling queries.
 void cancel()
          Method to cancel any currently running queries.
 void cancel(java.lang.Thread thread)
          Method to cancel a running query in the specified Thread.
protected  void checkParameterTypesAgainstCompilation(java.util.Map parameterValues)
          Method to do checks of the input parameters with respect to their types being consistent with the types of the parameters in the compilation.
 boolean checkUnusedParameters()
          Whether the query compilation(s) should check for unused parameters.
 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.
protected abstract  void compileInternal(java.util.Map parameterValues)
          Method to compile the query.
 void declareExplicitParameters(java.lang.String parameters)
          Method to define the explicit parameters.
 void declareExplicitVariables(java.lang.String variables)
          Method to define the explicit variables for the query.
 void declareImports(java.lang.String imports)
          Set the import statements to be used to identify the fully qualified name of variables or parameters.
 long deletePersistentAll()
          Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.
 long deletePersistentAll(java.util.Map parameters)
          Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.
 long deletePersistentAll(java.lang.Object[] parameterValues)
          Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.
protected  void discardCompiled()
          Utility to remove any previous compilation of this Query.
 boolean equals(java.lang.Object obj)
          Equality operator.
 java.lang.Object execute()
          Execute the query and return the filtered results.
 boolean executeInSeparateThread()
          Accessor for whether the execute the query in a separate thread.
protected  java.lang.Object executeQuery(java.util.Map parameters)
          Method to execute the actual query.
 java.lang.Object executeWithArray(java.lang.Object[] parameterValues)
          Execute the query and return the filtered results using the array of parameters.
 java.lang.Object executeWithMap(java.util.Map parameters)
          Execute the query and return the filtered results using the map of parameters.
 boolean getBooleanExtensionProperty(java.lang.String name, boolean resultIfNotSet)
          Convenience accessor to return whether an extension is set (or whether the persistence property of the same name is set), and what is its boolean value.
 java.lang.Class getCandidateClass()
          Accessor for the class of the candidate instances of the query.
 java.lang.String getCandidateClassName()
          Accessor for the candidate class name.
 QueryCompilation getCompilation()
          Accessor for the query compilation.
 java.lang.Integer getDatastoreReadTimeoutMillis()
          Convenience accessor for the datastore read timeout (milliseconds).
 java.lang.Integer getDatastoreWriteTimeoutMillis()
          Convenience accessor for the datastore write timeout (milliseconds).
 java.lang.String getExplicitParameters()
          Accessor for the explicit parameters specification.
 java.lang.String getExplicitVariables()
          Accessor for the explicit variables specification.
 java.lang.Object getExtension(java.lang.String key)
          Accessor for the value of an extension for this query.
 java.util.Map<java.lang.String,java.lang.Object> getExtensions()
          Accessor for the extensions defined for this query.
 FetchPlan getFetchPlan()
          This method retrieves the fetch plan associated with the Query.
 java.lang.String getFilter()
          Accessor for the filter specification.
 java.lang.String getFrom()
          Accessor for the FROM clause of the query.
 java.lang.String getGrouping()
          Accessor for the grouping string for the query.
 java.lang.String getHaving()
          Accessor for the having string for the query.
 boolean getIgnoreCache()
          Accessor for the ignoreCache option setting.
 java.util.Map getImplicitParameters()
          Accessor for the implicit parameters.
 java.lang.String getImports()
          Accessor for the imports specification.
 java.util.Map getInputParameters()
          Accessor for the input parameters for this query.
 java.lang.String getLanguage()
          Accessor for the query language.
 ExecutionContext getObjectManager()
          Accessor for the ObjectManager associated with this Query.
 java.lang.String getOrdering()
          Accessor for the ordering string for the query.
protected  java.util.Map getParameterMapForValues(java.lang.Object[] parameterValues)
          Convenience method to convert the input parameters into a parameter map keyed by the parameter name.
 Imports getParsedImports()
          Accessor for the parsed imports.
 QueryManager getQueryManager()
           
 java.lang.String getRange()
          Accessor for the range specification string.
 long getRangeFromIncl()
          Accessor for the range lower limit (inclusive).
 java.lang.String getRangeFromInclParam()
          Accessor for the range lower limit parameter (inclusive).
 long getRangeToExcl()
          Accessor for the range upper limit (exclusive).
 java.lang.String getRangeToExclParam()
          Accessor for the range upper limit parameter (exclusive).
 java.lang.String getResult()
          Accessor for the result specification string.
 java.lang.Class getResultClass()
          Accessor for the result class.
 java.lang.String getResultClassName()
           
 boolean getResultDistinct()
          Accessor for whether the results are distinct.
 java.lang.Boolean getSerializeRead()
          Accessor for whether to serialise (lock) any read objects retrieved from this query.
 StoreManager getStoreManager()
          Accessor for the StoreManager associated with this Query.
 Query.SubqueryDefinition getSubqueryForVariable(java.lang.String variableName)
          Accessor for the subquery for the supplied variable.
 java.util.Set<java.lang.String> getSupportedExtensions()
          Method to return the names of the extensions supported by this query.
 short getType()
          Accessor for the query type.
 java.lang.String getUpdate()
          Accessor for the UPDATE clause of the JPQL query.
 int hashCode()
          Hashcode generator.
 boolean hasSubqueryForVariable(java.lang.String variableName)
          Accessor for whether there is a subquery for the specified variable name.
protected  boolean isCompiled()
          Method to return if the query is compiled.
 boolean isSubclasses()
          Accessor for whether this query includes subclasses
 boolean isUnique()
          Accessor for whether the query results are unique.
 boolean isUnmodifiable()
          Accessor for unmodifiable.
protected  long performDeletePersistentAll(java.util.Map parameters)
          Execute the query to delete persistent objects.
protected abstract  java.lang.Object performExecute(java.util.Map parameters)
          Method to actually execute the query.
protected  java.lang.Object performExecuteInternal(java.lang.Object... args)
          Method executing the query in the destination environment.
protected  java.lang.Object performExecuteTask(java.lang.Object... args)
          Method to execute the query action as a separate task.
protected  void prepareDatastore()
          Convenience method that will flush any outstanding updates to the datastore.
 java.lang.Class resolveClassDeclaration(java.lang.String classDecl)
          Utility to resolve the declaration to a particular class.
 void setCandidateClassName(java.lang.String candidateClassName)
          Convenience method to set the name of the candidate class.
abstract  void setCandidates(java.util.Collection pcs)
          Set the candidate Collection to query.
abstract  void setCandidates(Extent pcs)
          Set the candidate Extent to query.
 void setClass(java.lang.Class candidateClass)
          Mutator for the class of the candidate instances of the query.
 void setCompilation(QueryCompilation compilation)
          Method to set the generic compilation for this query.
 void setDatastoreReadTimeoutMillis(java.lang.Integer timeout)
          Mutator to set the datastore read timeout for this query.
 void setDatastoreWriteTimeoutMillis(java.lang.Integer timeout)
          Mutator to set the datastore write timeout for this query.
 void setExtensions(java.util.Map extensions)
          Set multiple extensions, or use null to clear extensions.
 void setFetchPlan(FetchPlan fp)
          Mutator for the FetchPlan of the query.
 void setFilter(java.lang.String filter)
          Set the filter for the query.
 void setFrom(java.lang.String from)
          Set the candidates to the query.
 void setGrouping(java.lang.String grouping)
          Set the grouping specification for the result Collection.
 void setHaving(java.lang.String having)
          Set the having specification for the result Collection.
 void setIgnoreCache(boolean ignoreCache)
          Set the ignoreCache option.
 void setImplicitParameter(int position, java.lang.Object value)
          Method to set the value of a numbered implicit parameter where known before execution.
 void setImplicitParameter(java.lang.String name, java.lang.Object value)
          Method to set the value of a named implicit parameter where known before execution.
 void setOrdering(java.lang.String ordering)
          Set the ordering specification for the result Collection.
 void setRange(long fromIncl, long toExcl)
          Set the range of the results.
 void setRange(java.lang.String range)
          Set the range of the results.
 void setResult(java.lang.String result)
          Set the result for the results.
 void setResultClass(java.lang.Class result_cls)
          Set the result class for the results.
 void setResultClassName(java.lang.String resultClassName)
          Method to set the result class name, direct from a single-string query.
 void setResultDistinct(boolean distinct)
          Mark the result as distinct (or not).
 void setResultMetaData(QueryResultMetaData qrmd)
          Method to set the MetaData defining the result.
 void setSerializeRead(java.lang.Boolean serialize)
          Mutator for whether to serialise (lock) any read objects in this query.
 void setSubclasses(boolean subclasses)
          Mutator for whether this query includes subclasses
 void setType(short type)
          Mutator to set the query type.
 void setUnique(boolean unique)
          Set the uniqueness of the results.
 void setUnmodifiable()
          Mutator for unmodifiable.
 void setUpdate(java.lang.String update)
          Set the UPDATE clause of the query.
protected  boolean shouldReturnSingleRow()
          Convenience method to return whether the query should return a single row.
protected  boolean supportsTimeout()
          Convenience method for whether this query supports timeouts.
 boolean useCaching()
          Whether the query compilation(s) should be cached.
protected  boolean useFetchPlan()
          Convenience accessor for whether to use the fetch plan with this query.
 boolean useResultsCaching()
          Whether the results of the query should be cached.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOCALISER

protected static final Localiser LOCALISER
Localiser for messages.


ec

protected final transient ExecutionContext ec
ExecutionContext.


clr

protected final transient ClassLoaderResolver clr

SELECT

public static final short SELECT
See Also:
Constant Field Values

BULK_UPDATE

public static final short BULK_UPDATE
See Also:
Constant Field Values

BULK_DELETE

public static final short BULK_DELETE
See Also:
Constant Field Values

OTHER

public static final short OTHER
See Also:
Constant Field Values

type

protected short type
Type of query.


candidateClass

protected java.lang.Class candidateClass
The candidate class for this query.


candidateClassName

protected java.lang.String candidateClassName
Name of the candidate class (used when specified via Single-String).


subclasses

protected boolean subclasses
Whether to allow subclasses of the candidate class be returned.


unique

protected boolean unique
Whether to return single value, or collection from the query.


from

protected transient java.lang.String from
From clause of the query (optional).


update

protected transient java.lang.String update
UPDATE clause of a query.


result

protected java.lang.String result
Specification of the result of the query e.g aggregates etc. Doesn't include any "distinct".


resultDistinct

protected boolean resultDistinct
Whether the results are marked as distinct. This is extracted out of the result for clarity.


resultClass

protected java.lang.Class resultClass
User-defined class that best represents the results of a query. Populated if specified via setResultClass().


resultClassName

protected java.lang.String resultClassName
Temporary variable for the name of the result class (may need resolving using imports).


filter

protected java.lang.String filter
The filter for the query.


imports

protected java.lang.String imports
Any import declarations for the types used in the query, semicolon separated.


explicitVariables

protected java.lang.String explicitVariables
Any explicit variables defined for this query, semicolon separated.


explicitParameters

protected java.lang.String explicitParameters
Any explicit parameters defined for this query, comma separated.


ordering

protected java.lang.String ordering
Ordering clause for the query, governing the order objects are returned.


grouping

protected java.lang.String grouping
Grouping clause for the query, for use with aggregate expressions.


having

protected java.lang.String having
Having clause for the query


range

protected java.lang.String range
String form of the query result range. For convenience only.


fromInclNo

protected long fromInclNo
Query result range start position (inclusive).


toExclNo

protected long toExclNo
Query result range end position (exclusive).


fromInclParam

protected java.lang.String fromInclParam
Query result range lower limit (inclusive) as a parameter name.


toExclParam

protected java.lang.String toExclParam
Query result range upper limit (exclusive) as a parameter name.


unmodifiable

protected boolean unmodifiable
Whether the query can be modified


ignoreCache

protected boolean ignoreCache
Whether to ignore dirty instances in the query.


extensions

protected java.util.Map<java.lang.String,java.lang.Object> extensions
Any extensions


subqueries

protected java.util.Map<java.lang.String,Query.SubqueryDefinition> subqueries
Any subqueries, keyed by the variable name that they represent.


implicitParameters

protected transient java.util.HashMap implicitParameters
Map of implicit parameters, keyed by the name/number. Named parameters are keyed by String form of the name. Numbered parameters are keyed by the position (Integer).


parsedImports

protected transient Imports parsedImports
The imports definition.


parameterNames

protected transient java.lang.String[] parameterNames
Array of (explicit) parameter names.


compilation

protected transient QueryCompilation compilation
Query compilation (when using the generic query compiler).


queryResults

protected transient java.util.HashSet<QueryResult> queryResults
All query results obtained from this query. This is required because the query can be executed multiple times changing the input slightly each time for example.


tasks

protected transient java.util.HashMap<java.lang.Thread,java.util.concurrent.FutureTask> tasks
Currently executing task for this query, keyed by the thread.

Constructor Detail

Query

public Query(ExecutionContext ec)
Constructs a new query instance that uses the given object manager.

Parameters:
ec - execution context
Method Detail

getLanguage

public java.lang.String getLanguage()
Accessor for the query language.

Returns:
Query language

discardCompiled

protected void discardCompiled()
Utility to remove any previous compilation of this Query.


setCompilation

public void setCompilation(QueryCompilation compilation)
Method to set the generic compilation for this query. This is used where we are generating the query via a criteria API, and so have the single-string form and the compilation ready when we create the query itself.

Parameters:
compilation - The compilation

equals

public boolean equals(java.lang.Object obj)
Equality operator.

Overrides:
equals in class java.lang.Object
Parameters:
obj - Object to compare against
Returns:
Whether this and the other object are equal.

hashCode

public int hashCode()
Hashcode generator.

Overrides:
hashCode in class java.lang.Object
Returns:
The Hashcode for this object.

getType

public short getType()
Accessor for the query type.

Returns:
The query type

setType

public void setType(short type)
Mutator to set the query type.

Parameters:
type - The query type

getStoreManager

public StoreManager getStoreManager()
Accessor for the StoreManager associated with this Query.

Returns:
the StoreManager associated with this Query.

getObjectManager

public ExecutionContext getObjectManager()
Accessor for the ObjectManager associated with this Query.

Returns:
the ObjectManager associated with this Query.

addExtension

public void addExtension(java.lang.String key,
                         java.lang.Object value)
Add a vendor-specific extension this query. The key and value are not standard. An implementation must ignore keys that are not recognized.

Parameters:
key - the extension key
value - the extension value

setExtensions

public void setExtensions(java.util.Map extensions)
Set multiple extensions, or use null to clear extensions. Map keys and values are not standard. An implementation must ignore entries that are not recognized.

Parameters:
extensions -
See Also:
addExtension(java.lang.String, java.lang.Object)

getExtension

public java.lang.Object getExtension(java.lang.String key)
Accessor for the value of an extension for this query.

Parameters:
key - The key
Returns:
The value (if this extension is specified)

getExtensions

public java.util.Map<java.lang.String,java.lang.Object> getExtensions()
Accessor for the extensions defined for this query.

Returns:
Extensions

getBooleanExtensionProperty

public boolean getBooleanExtensionProperty(java.lang.String name,
                                           boolean resultIfNotSet)
Convenience accessor to return whether an extension is set (or whether the persistence property of the same name is set), and what is its boolean value. Returns "resultIfNotSet" if not set.

Parameters:
name - The extension/property name
resultIfNotSet - The value to return if there is neither an extension nor a persistence property of the same name
Returns:
The boolean value

getSupportedExtensions

public java.util.Set<java.lang.String> getSupportedExtensions()
Method to return the names of the extensions supported by this query. To be overridden by subclasses where they support additional extensions.

Returns:
The supported extension names

getFetchPlan

public FetchPlan getFetchPlan()
This method retrieves the fetch plan associated with the Query. It always returns the identical instance for the same Query instance. Any change made to the fetch plan affects subsequent query execution. Fetch plan is described in JDO2 $12.7

Returns:
the FetchPlan

setFetchPlan

public void setFetchPlan(FetchPlan fp)
Mutator for the FetchPlan of the query. This is called when applying a named FetchPlan.

Parameters:
fp - The FetchPlan

setUpdate

public void setUpdate(java.lang.String update)
Set the UPDATE clause of the query.

Parameters:
update - the update clause

getUpdate

public java.lang.String getUpdate()
Accessor for the UPDATE clause of the JPQL query.

Returns:
Update clause

getCandidateClass

public java.lang.Class getCandidateClass()
Accessor for the class of the candidate instances of the query.

Returns:
the Class of the candidate instances.

setClass

public void setClass(java.lang.Class candidateClass)
Mutator for the class of the candidate instances of the query.

Parameters:
candidateClass - the Class of the candidate instances.

setCandidateClassName

public void setCandidateClassName(java.lang.String candidateClassName)
Convenience method to set the name of the candidate class.

Parameters:
candidateClassName - Name of the candidate class

getCandidateClassName

public java.lang.String getCandidateClassName()
Accessor for the candidate class name.

Returns:
Name of the candidate class (if any)

setFrom

public void setFrom(java.lang.String from)
Set the candidates to the query.

Parameters:
from - the candidates

getFrom

public java.lang.String getFrom()
Accessor for the FROM clause of the query.

Returns:
From clause

setCandidates

public abstract void setCandidates(Extent pcs)
Set the candidate Extent to query. To be implemented by extensions.

Parameters:
pcs - the Candidate Extent.

setCandidates

public abstract void setCandidates(java.util.Collection pcs)
Set the candidate Collection to query. To be implemented by extensions.

Parameters:
pcs - the Candidate collection.

setFilter

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

Parameters:
filter - the query filter.

getFilter

public java.lang.String getFilter()
Accessor for the filter specification.

Returns:
Filter specification

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:
imports - import statements separated by semicolons.

getImports

public java.lang.String getImports()
Accessor for the imports specification.

Returns:
Imports specification

declareExplicitParameters

public void declareExplicitParameters(java.lang.String parameters)
Method to define the explicit parameters.

Parameters:
parameters - the list of parameters separated by commas

getExplicitParameters

public java.lang.String getExplicitParameters()
Accessor for the explicit parameters specification.

Returns:
Explicit parameters specification

setImplicitParameter

public void setImplicitParameter(java.lang.String name,
                                 java.lang.Object value)
Method to set the value of a named implicit parameter where known before execution.

Parameters:
name - Name of the parameter
value - Value of the parameter
Throws:
QueryInvalidParametersException - if the parameter is invalid

setImplicitParameter

public void setImplicitParameter(int position,
                                 java.lang.Object value)
Method to set the value of a numbered implicit parameter where known before execution.

Parameters:
position - Position of the parameter
value - Value of the parameter
Throws:
QueryInvalidParametersException - if the parameter is invalid

applyImplicitParameterValueToCompilation

protected void applyImplicitParameterValueToCompilation(java.lang.String name,
                                                        java.lang.Object value)
Convenience method to apply an implicit parameter value to the compilation symbol table. If the (generic) compilation doesn't exist then does nothing. If the parameter doesn't exist in the symbol table then an exception is thrown (since no point providing a parameter if not in the query).

Parameters:
name - Name of the parameter
value - Value of the parameter
Throws:
QueryInvalidParametersException - if the parameter doesn't exist in the query or if the type of the parameter provided is inconsistent with the query

getImplicitParameters

public java.util.Map getImplicitParameters()
Accessor for the implicit parameters. Named params are keyed by the name. Positional params are keyed by the Integer(position).

Returns:
Implicit params

declareExplicitVariables

public void declareExplicitVariables(java.lang.String variables)
Method to define the explicit variables for the query.

Parameters:
variables - the variables separated by semicolons.

getExplicitVariables

public java.lang.String getExplicitVariables()
Accessor for the explicit variables specification.

Returns:
Explicit variables specification

setOrdering

public void setOrdering(java.lang.String ordering)
Set the ordering specification for the result Collection.

Parameters:
ordering - the ordering specification.

getOrdering

public java.lang.String getOrdering()
Accessor for the ordering string for the query.

Returns:
Ordering specification

setGrouping

public void setGrouping(java.lang.String grouping)
Set the grouping specification for the result Collection.

Parameters:
grouping - the grouping specification.

getGrouping

public java.lang.String getGrouping()
Accessor for the grouping string for the query.

Returns:
Grouping specification

setHaving

public void setHaving(java.lang.String having)
Set the having specification for the result Collection.

Parameters:
having - the having specification.

getHaving

public java.lang.String getHaving()
Accessor for the having string for the query.

Returns:
Having specification

setUnique

public void setUnique(boolean unique)
Set the uniqueness of the results. A value of true will return a single value (or null) where the application knows that there are 0 or 1 objects to be returned. See JDO 2.0 specification $14.6

Parameters:
unique - whether the result is unique

isUnique

public boolean isUnique()
Accessor for whether the query results are unique.

Returns:
Whether it is unique

setRange

public void setRange(long fromIncl,
                     long toExcl)
Set the range of the results. By default all results are returned but this allows specification of a range of elements required. See JDO 2.0 specification section 14.6.8

Parameters:
fromIncl - From element no (inclusive) to return
toExcl - To element no (exclusive) to return

setRange

public void setRange(java.lang.String range)
Set the range of the results. By default all results are returned but this allows specification of a range of elements required. See JDO 2.0 specification section 14.6.8

Parameters:
range - Range string

getRange

public java.lang.String getRange()
Accessor for the range specification string.

Returns:
Range specification

getRangeFromIncl

public long getRangeFromIncl()
Accessor for the range lower limit (inclusive).

Returns:
Range lower limit

getRangeToExcl

public long getRangeToExcl()
Accessor for the range upper limit (exclusive).

Returns:
Range upper limit

getRangeFromInclParam

public java.lang.String getRangeFromInclParam()
Accessor for the range lower limit parameter (inclusive).

Returns:
Range lower limit

getRangeToExclParam

public java.lang.String getRangeToExclParam()
Accessor for the range upper limit parameter (exclusive).

Returns:
Range upper limit

setResult

public void setResult(java.lang.String result)
Set the result for the results.

Parameters:
result - Comma-separated result expressions

getResult

public java.lang.String getResult()
Accessor for the result specification string.

Returns:
Result specification

setResultDistinct

public void setResultDistinct(boolean distinct)
Mark the result as distinct (or not). This is not part of JDOQL/JPQL but provided for convenience.

Parameters:
distinct - Whether to treat as distinct

getResultDistinct

public boolean getResultDistinct()
Accessor for whether the results are distinct. By default this is extracted from the "result" clause.

Returns:
Whether distinct

getResultClassName

public java.lang.String getResultClassName()

setResultClassName

public void setResultClassName(java.lang.String resultClassName)
Method to set the result class name, direct from a single-string query. The name could be a shortened form, allowing for imports to resolve it.

Parameters:
resultClassName - Name of the result class

setResultClass

public void setResultClass(java.lang.Class result_cls)
Set the result class for the results. The result class must obey various things as per the JDO 2.0 spec 14.6.12.

Parameters:
result_cls - The result class

getResultClass

public java.lang.Class getResultClass()
Accessor for the result class.

Returns:
Result class

setResultMetaData

public void setResultMetaData(QueryResultMetaData qrmd)
Method to set the MetaData defining the result. If the query doesn't support such a setting will throw a NucleusException.

Parameters:
qrmd - QueryResultMetaData

setIgnoreCache

public void setIgnoreCache(boolean ignoreCache)
Set the ignoreCache option. Currently this simply stores the ignoreCache value, and doesn't necessarily use it. The parameter is a "hint" to the query engine.

Parameters:
ignoreCache - the setting of the ignoreCache option.

getIgnoreCache

public boolean getIgnoreCache()
Accessor for the ignoreCache option setting.

Returns:
the ignoreCache option setting
See Also:
setIgnoreCache(boolean)

isSubclasses

public boolean isSubclasses()
Accessor for whether this query includes subclasses

Returns:
Returns whether the query includes subclasses.

setSubclasses

public void setSubclasses(boolean subclasses)
Mutator for whether this query includes subclasses

Parameters:
subclasses - Where subclasses of the candidate class are to be included.

getSerializeRead

public java.lang.Boolean getSerializeRead()
Accessor for whether to serialise (lock) any read objects retrieved from this query. True means that we will lock them, False means don't lock them, and null implies it is left to the implementation.

Returns:
Whether to lock

setSerializeRead

public void setSerializeRead(java.lang.Boolean serialize)
Mutator for whether to serialise (lock) any read objects in this query.

Parameters:
serialize - Whether to serialise (lock) the query objects

isUnmodifiable

public boolean isUnmodifiable()
Accessor for unmodifiable.

Returns:
Returns the unmodifiable.

assertIsModifiable

protected void assertIsModifiable()
Method to throw an exception if the query is currently not modifiable.

Throws:
NucleusUserException - Thrown when it is unmodifiable

setUnmodifiable

public void setUnmodifiable()
Mutator for unmodifiable.


addSubquery

public void addSubquery(Query sub,
                        java.lang.String variableDecl,
                        java.lang.String candidateExpr,
                        java.util.Map paramMap)
Method to add a subquery to this query.

Parameters:
sub - The subquery
variableDecl - Declaration of variables
candidateExpr - Candidate expression
paramMap - Map of parameters for this subquery

getSubqueryForVariable

public Query.SubqueryDefinition getSubqueryForVariable(java.lang.String variableName)
Accessor for the subquery for the supplied variable.

Parameters:
variableName - Name of the variable
Returns:
Subquery for the variable (if a subquery exists for this variable)

hasSubqueryForVariable

public boolean hasSubqueryForVariable(java.lang.String variableName)
Accessor for whether there is a subquery for the specified variable name.

Parameters:
variableName - Name of the variable
Returns:
Whether there is a subquery defined

prepareDatastore

protected void prepareDatastore()
Convenience method that will flush any outstanding updates to the datastore. This is intended to be used before execution so that the datastore has all relevant data present for what the query needs.


getCompilation

public QueryCompilation getCompilation()
Accessor for the query compilation. Will be null if the query doesn't use the "generic" query mechanism.

Returns:
The query compilation

isCompiled

protected boolean isCompiled()
Method to return if the query is compiled.

Returns:
Whether it is compiled

compile

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


compileInternal

protected abstract void compileInternal(java.util.Map parameterValues)
Method to compile the query. To be implemented by the query implementation.

Parameters:
parameterValues - Parameter values keyed by name (when compiling for execution)

getParsedImports

public Imports getParsedImports()
Accessor for the parsed imports. If no imports are set then adds candidate class and user imports.

Returns:
Parsed imports

execute

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

Returns:
the filtered results (List, or Object).
See Also:
executeWithArray(Object[] parameters)

executeWithArray

public java.lang.Object executeWithArray(java.lang.Object[] parameterValues)
Execute the query and return the filtered results using the array of parameters.

Parameters:
parameterValues - the Object array with all of the parameters.
Returns:
the filtered results (List, or Object).
Throws:
NoQueryResultsException - Thrown if no results were returned from the query.
See Also:
executeQuery(Map parameters)

executeWithMap

public java.lang.Object executeWithMap(java.util.Map parameters)
Execute the query and return the filtered results using the map of parameters.

Parameters:
parameters - the Map containing all of the parameters.
Returns:
the filtered results (List, or Object)
Throws:
NoQueryResultsException - Thrown if no results were returned from the query.
See Also:
executeQuery(Map parameters)

getInputParameters

public java.util.Map getInputParameters()
Accessor for the input parameters for this query.

Returns:
The input parameters map, with param values keyed by param name

supportsTimeout

protected boolean supportsTimeout()
Convenience method for whether this query supports timeouts. Defaults to false, so override if supporting a timeout in the concrete implementation

Returns:
Whether timeouts are supported.

setDatastoreReadTimeoutMillis

public void setDatastoreReadTimeoutMillis(java.lang.Integer timeout)
Mutator to set the datastore read timeout for this query.

Parameters:
timeout - The timeout

getDatastoreReadTimeoutMillis

public java.lang.Integer getDatastoreReadTimeoutMillis()
Convenience accessor for the datastore read timeout (milliseconds). Returns null if not defined.

Returns:
the timeout

setDatastoreWriteTimeoutMillis

public void setDatastoreWriteTimeoutMillis(java.lang.Integer timeout)
Mutator to set the datastore write timeout for this query.

Parameters:
timeout - The timeout

getDatastoreWriteTimeoutMillis

public java.lang.Integer getDatastoreWriteTimeoutMillis()
Convenience accessor for the datastore write timeout (milliseconds). Returns null if not defined.

Returns:
the timeout

getQueryManager

public QueryManager getQueryManager()

executeQuery

protected java.lang.Object executeQuery(java.util.Map parameters)
Method to execute the actual query. Calls performExecute() allowing individual implementations to do what they require for execution (in-memory, in-datastore, etc). Applies result checking.

Parameters:
parameters - Map of parameter values keyed by parameter name
Returns:
Result. Will be List for SELECT queries, and Long for BULK_UPDATE/BULK_DELETE
Throws:
NoQueryResultsException - Thrown if no results were returned from the query.
QueryNotUniqueException - Thrown if multiple results, yet expected one

assertSupportsCancel

protected void assertSupportsCancel()
Method that will throw an UnsupportedOperationException if the query implementation doesn't support cancelling queries. Implementations that support the cancel operation should override this.


cancel

public void cancel()
Method to cancel any currently running queries. Operates if the implementation supports cancelling of queries via the method
assertSupportsCancel()


cancel

public void cancel(java.lang.Thread thread)
Method to cancel a running query in the specified Thread. Operates if the implementation supports cancelling of queries via the method
assertSupportsCancel()

Parameters:
thread - The thread

performExecuteTask

protected java.lang.Object performExecuteTask(java.lang.Object... args)
Method to execute the query action as a separate task. Handles timeout checking and cancel detection. Executes the method "performExecuteInternal()" in its own thread.

Parameters:
args - Arguments for execution of performExecuteInternal(), defined by each implementation
Returns:
The result
Throws:
QueryTimeoutException - if the operation times out
QueryInterruptedException - if the operation is cancelled (by the user in another thread)

performExecuteInternal

protected java.lang.Object performExecuteInternal(java.lang.Object... args)
Method executing the query in the destination environment. Used when the query implementation supports timeout and cancel operations. For RDBMS this will call PreparedStatement.execute() (i.e the operation that we want to apply the timeout and cancel control to).

Parameters:
args - Arguments to the execution (defined by each implementation).
Returns:
The result
See Also:
performExecuteTask

performExecute

protected abstract java.lang.Object performExecute(java.util.Map parameters)
Method to actually execute the query. To be implemented by extending classes for the particular query language.

Parameters:
parameters - Map containing the parameters.
Returns:
Query result - QueryResult if SELECT, or Long if BULK_UPDATE, BULK_DELETE

applyRangeChecks

protected boolean applyRangeChecks()
Method to return if the query results should have the range checked and unnecessary rows discarded. This is for where the query language has specified a range but the datastore doesn't allow removal of unnecessary results in the query itself (so has to be done in post-processing). This implementation returns false and so should be overridden by query languages to match their capabilities.

Returns:
Whether to apply range checks in post-processing of results.

deletePersistentAll

public long deletePersistentAll()
Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.

Returns:
The number of deleted objects.

deletePersistentAll

public long deletePersistentAll(java.lang.Object[] parameterValues)
Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.

Parameters:
parameterValues - the Object array with values of the parameters.
Returns:
the filtered Collection.

deletePersistentAll

public long deletePersistentAll(java.util.Map parameters)
Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.

Parameters:
parameters - Map of parameters for the query
Returns:
the number of deleted objects

performDeletePersistentAll

protected long performDeletePersistentAll(java.util.Map parameters)
Execute the query to delete persistent objects. Provides a default implementation that executes the query to find the objects, and then calls ObjectManager.deleteObjects() on the returned objects.

Parameters:
parameters - the Map containing all of the parameters.
Returns:
the number of deleted objects.

close

public void close(java.lang.Object queryResult)
Close a query result and release any resources associated with it.

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.


shouldReturnSingleRow

protected boolean shouldReturnSingleRow()
Convenience method to return whether the query should return a single row.

Returns:
Whether it represents a unique row

getParameterMapForValues

protected java.util.Map getParameterMapForValues(java.lang.Object[] parameterValues)
Convenience method to convert the input parameters into a parameter map keyed by the parameter name. If the parameters for this query are explicit then they are keyed by the names defined as input via "declareParameters()".

Parameters:
parameterValues - Parameter values
Returns:
The parameter map.

useFetchPlan

protected boolean useFetchPlan()
Convenience accessor for whether to use the fetch plan with this query. Defaults to true but can be turned off by the user for performance reasons.

Returns:
Whether to use the fetch plan

useCaching

public boolean useCaching()
Whether the query compilation(s) should be cached.

Returns:
Should we cache the compilation of the query

useResultsCaching

public boolean useResultsCaching()
Whether the results of the query should be cached.

Returns:
Should we cache the results of the query

checkUnusedParameters

public boolean checkUnusedParameters()
Whether the query compilation(s) should check for unused parameters.

Returns:
Should we check for unused parameters and throw an exception if found

executeInSeparateThread

public boolean executeInSeparateThread()
Accessor for whether the execute the query in a separate thread. For datastores that support cancellation of queries (e.g RDBMS) we default to execution in a separate thread so then we have the ability to cancel the query. For all other datastores we default to execution in the current thread. There is a persistence property and query extension to set this behaviour.

Returns:
Whether to execute in a separate thread.

checkParameterTypesAgainstCompilation

protected void checkParameterTypesAgainstCompilation(java.util.Map parameterValues)
Method to do checks of the input parameters with respect to their types being consistent with the types of the parameters in the compilation.

Parameters:
parameterValues - The input parameter values keyed by their name (or position)

resolveClassDeclaration

public java.lang.Class resolveClassDeclaration(java.lang.String classDecl)
Utility to resolve the declaration to a particular class. Takes the passed in name, together with the defined import declarations and returns the class represented by the declaration.

Parameters:
classDecl - The declaration
Returns:
The class it resolves to (if any)
Throws:
NucleusUserException - Thrown if the class cannot be resolved.


Copyright © 2011. All Rights Reserved.