Package org.datanucleus.store.query
Class Query<T>
- java.lang.Object
-
- org.datanucleus.store.query.Query<T>
-
- Type Parameters:
T
- Type of the candidate of this query
- All Implemented Interfaces:
Serializable
,ExecutionContextListener
- Direct Known Subclasses:
AbstractJavaQuery
,AbstractStoredProcedureQuery
public abstract class Query<T> extends Object implements Serializable, ExecutionContextListener
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
Nested Classes Modifier and Type Class Description static class
Query.QueryType
static class
Query.SubqueryDefinition
Simple representation of a subquery, its candidate, params and variables.
-
Field Summary
Fields Modifier and Type Field Description protected Class<T>
candidateClass
The candidate class for this query.protected 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
protected String
explicitParameters
Any explicit parameters defined for this query, comma separated.protected String
explicitVariables
Any explicit variables defined for this query, semicolon separated.static String
EXTENSION_CHECK_UNUSED_PARAMETERS
static String
EXTENSION_CLOSE_RESULTS_AT_EC_CLOSE
static String
EXTENSION_COMPILATION_CACHED
static String
EXTENSION_COMPILE_OPTIMISE_VAR_THIS
static String
EXTENSION_EVALUATE_IN_MEMORY
static String
EXTENSION_EXCLUDE_SUBCLASSES
Extension for the benefit of JPQL so that we can exclude subclasses (not possible with JPA API).static String
EXTENSION_FLUSH_BEFORE_EXECUTION
static String
EXTENSION_JDOQL_ALLOW_ALL
static String
EXTENSION_JDOQL_STRICT
static String
EXTENSION_JPQL_ALLOW_RANGE
static String
EXTENSION_JPQL_STRICT
static String
EXTENSION_LOAD_RESULTS_AT_COMMIT
static String
EXTENSION_QUERY_TYPE
static String
EXTENSION_RESULT_CACHE_TYPE
static String
EXTENSION_RESULT_CACHE_VALIDATE_OBJECTS
static String
EXTENSION_RESULT_SIZE_METHOD
static String
EXTENSION_RESULTS_CACHED
static String
EXTENSION_SQL_ALLOW_ALL
static String
EXTENSION_SQL_SYNTAX_CHECKS
static String
EXTENSION_UPDATE_ALL_CANDIDATE_FIELDS
static String
EXTENSION_USE_FETCH_PLAN
protected Map<String,Object>
extensions
Any extensions.protected String
filter
The filter for the query.protected String
from
From clause of the query (optional).protected long
fromInclNo
Query result range start position (inclusive).protected String
fromInclParam
Query result range lower limit (inclusive) as a parameter name.protected String
grouping
Grouping clause for the query, for use with aggregate expressions.protected String
having
Having clause for the queryprotected boolean
ignoreCache
Whether to ignore dirty instances in the query.protected Map
implicitParameters
Map of implicit parameters, keyed by the name/number.protected String
imports
Any import declarations for the types used in the query, semicolon separated.protected Map
inputParameters
protected String
insertFields
INSERT fields of a query (optional).protected String
insertSelectQuery
INSERT select query (optional).protected String
ordering
Ordering clause for the query, governing the order objects are returned.protected String[]
parameterNames
Array of (explicit) parameter names.protected Imports
parsedImports
The imports definition.protected Set<QueryResult>
queryResults
All query results obtained from this query.protected String
range
String form of the query result range.protected String
result
Specification of the result of the query e.g aggregates etc.protected Class
resultClass
User-defined class that best represents the results of a query.protected 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.protected StoreManager
storeMgr
protected boolean
subclasses
Whether to allow subclasses of the candidate class be returned.protected Map<String,Query.SubqueryDefinition>
subqueries
Any subqueries, keyed by the variable name that they represent.protected Map<Thread,Object>
tasks
Currently executing object for this query, keyed by the thread, to allow for cancellation.protected long
toExclNo
Query result range end position (exclusive).protected String
toExclParam
Query result range upper limit (exclusive) as a parameter name.protected Query.QueryType
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 modifiedprotected String
update
UPDATE clause of a query (optional).
-
Constructor Summary
Constructors Constructor Description Query(StoreManager storeMgr, ExecutionContext ec)
Constructs a new query instance that uses the given ExecutionContext.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
addExtension(String key, Object value)
Add a vendor-specific extension to this query.void
addSubquery(Query sub, String variableDecl, String candidateExpr, Map paramMap)
Method to add a subquery to this query.protected void
applyImplicitParameterValueToCompilation(String name, Object value)
Convenience method to apply an implicit parameter value to the compilation symbol table.protected boolean
applyImplicitParameterValueToSubqueries(String name, Object value, QueryCompilation comp)
protected void
assertIsModifiable()
Method to throw an exception if the query is currently not modifiable.protected void
assertIsOpen()
protected void
assertSupportsCancel()
Method that will throw anUnsupportedOperationException
if the query implementation doesn't support cancelling queries.void
cancel()
Method to cancel any currently running queries.void
cancel(Thread thread)
Method to cancel a running query in the specified Thread.protected boolean
cancelTaskObject(Object obj)
Method to perform the cancellation of a query task.protected void
checkForMissingParameters(Map parameterValues)
Method to check for any missing parameters that the query compilation is expecting but which aren't supplied to execute().protected void
checkParameterTypesAgainstCompilation(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(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(Map parameterValues)
Method to compile the query.void
declareExplicitParameters(String parameters)
Method to define the explicit parameters.void
declareExplicitVariables(String variables)
Method to define the explicit variables for the query.void
declareImports(String imports)
Set the import statements to be used to identify the fully qualified name of variables or parameters.protected Symbol
deepFindSymbolForParameterInCompilation(QueryCompilation compilation, Object paramKey)
long
deletePersistentAll()
Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.long
deletePersistentAll(Object[] parameterValues)
Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.long
deletePersistentAll(Map parameters)
Method to delete all objects found by this query, catering for cascade changes and updates to in-memory objects.protected void
deregisterTask()
protected void
discardCompiled()
Utility to remove any previous compilation of this Query.boolean
equals(Object obj)
Equality operator.Object
execute()
Execute the query and return the filtered results.protected Object
executeQuery(Map parameters)
Method to execute the actual query.Object
executeWithArray(Object[] parameterValues)
Execute the query and return the filtered results using the array of parameters.Object
executeWithMap(Map parameters)
Execute the query and return the filtered results using the map of parameters.void
executionContextClosing(ExecutionContext ec)
Method called when the specified ExecutionContext is closing.boolean
getBooleanExtensionProperty(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.Class<T>
getCandidateClass()
Accessor for the class of the candidate instances of the query.protected AbstractClassMetaData
getCandidateClassMetaData()
String
getCandidateClassName()
Accessor for the candidate class name.QueryCompilation
getCompilation()
Accessor for the query compilation.Integer
getDatastoreReadTimeoutMillis()
Convenience accessor for the datastore read timeout (milliseconds).Integer
getDatastoreWriteTimeoutMillis()
Convenience accessor for the datastore write timeout (milliseconds).ExecutionContext
getExecutionContext()
Accessor for the Execution Context associated with this Query.String
getExplicitParametersDeclaration()
Accessor for the explicit parameters declaration.String
getExplicitVariablesDeclaration()
Accessor for the explicit variables declaration.Object
getExtension(String key)
Accessor for the value of an extension for this query.Map<String,Object>
getExtensions()
Accessor for the extensions defined for this query.FetchPlan
getFetchPlan()
This method retrieves the fetch plan associated with the Query.String
getFilter()
Accessor for the filter specification.String
getFrom()
Accessor for the FROM clause of the query.String
getGrouping()
Accessor for the grouping string for the query.String
getHaving()
Accessor for the having string for the query.boolean
getIgnoreCache()
Accessor for the ignoreCache option setting.Map
getImplicitParameters()
Accessor for the implicit parameters.String
getImportsDeclaration()
Accessor for the imports declaration.Map
getInputParameters()
Accessor for the input parameters for this query.String
getInsertFields()
Accessor for the INSERT fields of the query (if any).String
getInsertSelectQuery()
Accessor for the INSERT select query (if any).String
getLanguage()
Accessor for the query language.Object
getNativeQuery()
Method returning the native query performed by this query (if the query has been compiled, and if the datastore plugin supports this).String
getOrdering()
Accessor for the ordering string for the query.protected Map
getParameterMapForValues(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()
String
getRange()
Accessor for the range specification string.long
getRangeFromIncl()
Accessor for the range lower limit (inclusive).String
getRangeFromInclParam()
Accessor for the range lower limit parameter (inclusive).long
getRangeToExcl()
Accessor for the range upper limit (exclusive).String
getRangeToExclParam()
Accessor for the range upper limit parameter (exclusive).String
getResult()
Accessor for the result specification string.Class
getResultClass()
Accessor for the result class.String
getResultClassName()
boolean
getResultDistinct()
Accessor for whether the results are distinct.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.String
getStringExtensionProperty(String name, String 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 String value.Query.SubqueryDefinition
getSubqueryForVariable(String variableName)
Accessor for the subquery for the supplied variable.Set<String>
getSupportedExtensions()
Method to return the names of the extensions supported by this query.Query.QueryType
getType()
Accessor for the query type.String
getUpdate()
Accessor for the UPDATE clause of the query (if any).int
hashCode()
boolean
hasSubqueryForVariable(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 subclassesboolean
isUnique()
Accessor for whether the query results are unique.boolean
isUnmodifiable()
Accessor for unmodifiable.protected long
performDeletePersistentAll(Map parameters)
Execute the query to delete persistent objects.protected abstract Object
performExecute(Map parameters)
Method to actually execute the query.protected void
prepareDatastore()
Convenience method that will flush any outstanding updates to the datastore.boolean
processesRangeInDatastoreQuery()
Method to return if the datastore query will check any range constraints of this query.protected void
registerTask(Object taskObject)
Class
resolveClassDeclaration(String classDecl)
Utility to resolve the declaration to a particular class.void
setCacheResults(boolean cache)
Whether this query should cache the results from the times it is ran.void
setCandidateClass(Class<T> candidateClass)
Mutator for the class of the candidate instances of the query.void
setCandidateClassName(String candidateClassName)
Convenience method to set the name of the candidate class.abstract void
setCandidates(Collection<T> pcs)
Set the candidate Collection to query.abstract void
setCandidates(Extent<T> pcs)
Set the candidate Extent to query.void
setCompilation(QueryCompilation compilation)
Method to set the generic compilation for this query.void
setDatastoreReadTimeoutMillis(Integer timeout)
Mutator to set the datastore read timeout for this query.void
setDatastoreWriteTimeoutMillis(Integer timeout)
Mutator to set the datastore write timeout for this query.void
setExtensions(Map<String,Object> extensions)
Set multiple extensions, or use null to clear extensions.void
setFetchPlan(FetchPlan fp)
Mutator for the FetchPlan of the query.void
setFilter(String filter)
Set the filter for the query.void
setFrom(String from)
Set the candidates to the query.void
setGrouping(String grouping)
Set the grouping specification for the result Collection.void
setHaving(String having)
Set the having specification for the result Collection.void
setIgnoreCache(boolean ignoreCache)
Set the ignoreCache option.void
setImplicitParameter(int position, Object value)
Method to set the value of a numbered implicit parameter where known before execution.void
setImplicitParameter(String name, Object value)
Method to set the value of a named implicit parameter where known before execution.void
setInsertFields(String insertFields)
Set the INSERT fields of the query.void
setInsertSelectQuery(String query)
Set the INSERT select query.void
setOrdering(String ordering)
Set the ordering specification for the result Collection.void
setRange(long fromIncl, long toExcl)
Set the range of the results.void
setRange(String range)
Set the range of the results.void
setResult(String result)
Set the result for the results.void
setResultClass(Class result_cls)
Set the result class for the results.void
setResultClassName(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(Boolean serialize)
Mutator for whether to serialise (lock) any read objects in this query.void
setSubclasses(boolean subclasses)
Mutator for whether this query includes subclassesvoid
setType(Query.QueryType type)
Mutator to set the query type.void
setUnique(boolean unique)
Set the uniqueness of the results.void
setUnmodifiable()
Mutator for unmodifiable.void
setUpdate(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.
-
-
-
Field Detail
-
EXTENSION_FLUSH_BEFORE_EXECUTION
public static final String EXTENSION_FLUSH_BEFORE_EXECUTION
- See Also:
- Constant Field Values
-
EXTENSION_USE_FETCH_PLAN
public static final String EXTENSION_USE_FETCH_PLAN
- See Also:
- Constant Field Values
-
EXTENSION_RESULT_SIZE_METHOD
public static final String EXTENSION_RESULT_SIZE_METHOD
- See Also:
- Constant Field Values
-
EXTENSION_LOAD_RESULTS_AT_COMMIT
public static final String EXTENSION_LOAD_RESULTS_AT_COMMIT
- See Also:
- Constant Field Values
-
EXTENSION_RESULT_CACHE_TYPE
public static final String EXTENSION_RESULT_CACHE_TYPE
-
EXTENSION_RESULT_CACHE_VALIDATE_OBJECTS
public static final String EXTENSION_RESULT_CACHE_VALIDATE_OBJECTS
- See Also:
- Constant Field Values
-
EXTENSION_RESULTS_CACHED
public static final String EXTENSION_RESULTS_CACHED
- See Also:
- Constant Field Values
-
EXTENSION_COMPILATION_CACHED
public static final String EXTENSION_COMPILATION_CACHED
- See Also:
- Constant Field Values
-
EXTENSION_EVALUATE_IN_MEMORY
public static final String EXTENSION_EVALUATE_IN_MEMORY
- See Also:
- Constant Field Values
-
EXTENSION_CLOSE_RESULTS_AT_EC_CLOSE
public static final String EXTENSION_CLOSE_RESULTS_AT_EC_CLOSE
-
EXTENSION_CHECK_UNUSED_PARAMETERS
public static final String EXTENSION_CHECK_UNUSED_PARAMETERS
- See Also:
- Constant Field Values
-
EXTENSION_COMPILE_OPTIMISE_VAR_THIS
public static final String EXTENSION_COMPILE_OPTIMISE_VAR_THIS
- See Also:
- Constant Field Values
-
EXTENSION_UPDATE_ALL_CANDIDATE_FIELDS
public static final String EXTENSION_UPDATE_ALL_CANDIDATE_FIELDS
-
EXTENSION_JDOQL_ALLOW_ALL
public static final String EXTENSION_JDOQL_ALLOW_ALL
- See Also:
- Constant Field Values
-
EXTENSION_JDOQL_STRICT
public static final String EXTENSION_JDOQL_STRICT
- See Also:
- Constant Field Values
-
EXTENSION_JPQL_ALLOW_RANGE
public static final String EXTENSION_JPQL_ALLOW_RANGE
- See Also:
- Constant Field Values
-
EXTENSION_JPQL_STRICT
public static final String EXTENSION_JPQL_STRICT
- See Also:
- Constant Field Values
-
EXTENSION_SQL_ALLOW_ALL
public static final String EXTENSION_SQL_ALLOW_ALL
- See Also:
- Constant Field Values
-
EXTENSION_SQL_SYNTAX_CHECKS
public static final String EXTENSION_SQL_SYNTAX_CHECKS
- See Also:
- Constant Field Values
-
EXTENSION_EXCLUDE_SUBCLASSES
public static final String EXTENSION_EXCLUDE_SUBCLASSES
Extension for the benefit of JPQL so that we can exclude subclasses (not possible with JPA API).
-
EXTENSION_QUERY_TYPE
public static final String EXTENSION_QUERY_TYPE
- See Also:
- Constant Field Values
-
storeMgr
protected final transient StoreManager storeMgr
-
ec
protected transient ExecutionContext ec
-
clr
protected final transient ClassLoaderResolver clr
-
type
protected Query.QueryType type
Type of query.
-
candidateClassName
protected 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.
-
from
protected transient String from
From clause of the query (optional).
-
update
protected transient String update
UPDATE clause of a query (optional).
-
insertFields
protected transient String insertFields
INSERT fields of a query (optional).
-
insertSelectQuery
protected transient String insertSelectQuery
INSERT select query (optional).
-
result
protected 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.
-
unique
protected boolean unique
Whether to return single value, or collection from the query.
-
resultClass
protected Class resultClass
User-defined class that best represents the results of a query. Populated if specified via setResultClass().
-
resultClassName
protected String resultClassName
Temporary variable for the name of the result class (may need resolving using imports).
-
filter
protected String filter
The filter for the query.
-
ordering
protected String ordering
Ordering clause for the query, governing the order objects are returned.
-
grouping
protected String grouping
Grouping clause for the query, for use with aggregate expressions.
-
having
protected String having
Having clause for the query
-
imports
protected String imports
Any import declarations for the types used in the query, semicolon separated.
-
explicitVariables
protected String explicitVariables
Any explicit variables defined for this query, semicolon separated.
-
explicitParameters
protected String explicitParameters
Any explicit parameters defined for this query, comma separated.
-
range
protected 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 String fromInclParam
Query result range lower limit (inclusive) as a parameter name.
-
toExclParam
protected 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 Map<String,Object> extensions
Any extensions. These are stored with the key in lowercase.
-
subqueries
protected Map<String,Query.SubqueryDefinition> subqueries
Any subqueries, keyed by the variable name that they represent.
-
implicitParameters
protected transient Map 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 String[] parameterNames
Array of (explicit) parameter names.
-
compilation
protected transient QueryCompilation compilation
Query compilation (when using the generic query compiler).
-
queryResults
protected transient Set<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 Map<Thread,Object> tasks
Currently executing object for this query, keyed by the thread, to allow for cancellation.
-
inputParameters
protected Map inputParameters
-
-
Constructor Detail
-
Query
public Query(StoreManager storeMgr, ExecutionContext ec)
Constructs a new query instance that uses the given ExecutionContext.- Parameters:
storeMgr
- Store Manager used for this queryec
- execution context
-
-
Method Detail
-
setCacheResults
public void setCacheResults(boolean cache)
Whether this query should cache the results from the times it is ran. With JDO we would do this since it has a close() method to clear them out. With JPA we typically would not do this since there is no close() capability.- Parameters:
cache
- Whether to cache the query results obtained by an execute() call.
-
getLanguage
public 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(Object obj)
Equality operator.
-
getType
public Query.QueryType getType()
Accessor for the query type.- Returns:
- The query type
-
setType
public void setType(Query.QueryType 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.
-
getExecutionContext
public ExecutionContext getExecutionContext()
Accessor for the Execution Context associated with this Query.- Returns:
- Execution Context for the query
-
executionContextClosing
public void executionContextClosing(ExecutionContext ec)
Description copied from interface:ExecutionContextListener
Method called when the specified ExecutionContext is closing.- Specified by:
executionContextClosing
in interfaceExecutionContextListener
- Parameters:
ec
- The ExecutionContext
-
addExtension
public void addExtension(String key, 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 recognised.- Parameters:
key
- the extension keyvalue
- the extension value
-
setExtensions
public void setExtensions(Map<String,Object> 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 recognised.- Parameters:
extensions
- Any extensions- See Also:
addExtension(java.lang.String, java.lang.Object)
-
getExtension
public Object getExtension(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 Map<String,Object> getExtensions()
Accessor for the extensions defined for this query.- Returns:
- Extensions
-
getBooleanExtensionProperty
public boolean getBooleanExtensionProperty(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 nameresultIfNotSet
- The value to return if there is neither an extension nor a persistence property of the same name- Returns:
- The boolean value
-
getStringExtensionProperty
public String getStringExtensionProperty(String name, String 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 String value. Returns "resultIfNotSet" if not set.- Parameters:
name
- The extension/property nameresultIfNotSet
- The value to return if there is neither an extension nor a persistence property of the same name- Returns:
- The String value
-
getSupportedExtensions
public Set<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(String update)
Set the UPDATE clause of the query.- Parameters:
update
- the update clause
-
getUpdate
public String getUpdate()
Accessor for the UPDATE clause of the query (if any).- Returns:
- Update clause
-
setInsertFields
public void setInsertFields(String insertFields)
Set the INSERT fields of the query.- Parameters:
insertFields
- the fields to insert
-
getInsertFields
public String getInsertFields()
Accessor for the INSERT fields of the query (if any).- Returns:
- INSERT fields
-
setInsertSelectQuery
public void setInsertSelectQuery(String query)
Set the INSERT select query.- Parameters:
query
- the query to use for inserting
-
getInsertSelectQuery
public String getInsertSelectQuery()
Accessor for the INSERT select query (if any).- Returns:
- INSERT select query
-
getCandidateClass
public Class<T> getCandidateClass()
Accessor for the class of the candidate instances of the query.- Returns:
- the Class of the candidate instances.
-
setCandidateClass
public void setCandidateClass(Class<T> candidateClass)
Mutator for the class of the candidate instances of the query.- Parameters:
candidateClass
- the Class of the candidate instances.
-
setCandidateClassName
public void setCandidateClassName(String candidateClassName)
Convenience method to set the name of the candidate class.- Parameters:
candidateClassName
- Name of the candidate class
-
getCandidateClassName
public String getCandidateClassName()
Accessor for the candidate class name.- Returns:
- Name of the candidate class (if any)
-
getCandidateClassMetaData
protected AbstractClassMetaData getCandidateClassMetaData()
-
setFrom
public void setFrom(String from)
Set the candidates to the query.- Parameters:
from
- the candidates
-
getFrom
public String getFrom()
Accessor for the FROM clause of the query.- Returns:
- From clause
-
setFilter
public void setFilter(String filter)
Set the filter for the query.- Parameters:
filter
- the query filter.
-
getFilter
public String getFilter()
Accessor for the filter specification.- Returns:
- Filter specification
-
declareImports
public void declareImports(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.
-
getImportsDeclaration
public String getImportsDeclaration()
Accessor for the imports declaration.- Returns:
- Imports declaration
-
declareExplicitParameters
public void declareExplicitParameters(String parameters)
Method to define the explicit parameters.- Parameters:
parameters
- the list of parameters separated by commas
-
getExplicitParametersDeclaration
public String getExplicitParametersDeclaration()
Accessor for the explicit parameters declaration.- Returns:
- Explicit parameters declaration
-
declareExplicitVariables
public void declareExplicitVariables(String variables)
Method to define the explicit variables for the query.- Parameters:
variables
- the variables separated by semicolons.
-
getExplicitVariablesDeclaration
public String getExplicitVariablesDeclaration()
Accessor for the explicit variables declaration.- Returns:
- Explicit variables declaration
-
setImplicitParameter
public void setImplicitParameter(String name, Object value)
Method to set the value of a named implicit parameter where known before execution.- Parameters:
name
- Name of the parametervalue
- Value of the parameter- Throws:
QueryInvalidParametersException
- if the parameter is invalid
-
setImplicitParameter
public void setImplicitParameter(int position, Object value)
Method to set the value of a numbered implicit parameter where known before execution.- Parameters:
position
- Position of the parametervalue
- Value of the parameter- Throws:
QueryInvalidParametersException
- if the parameter is invalid
-
applyImplicitParameterValueToCompilation
protected void applyImplicitParameterValueToCompilation(String name, 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 parametervalue
- 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
-
applyImplicitParameterValueToSubqueries
protected boolean applyImplicitParameterValueToSubqueries(String name, Object value, QueryCompilation comp)
-
getImplicitParameters
public 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
-
setOrdering
public void setOrdering(String ordering)
Set the ordering specification for the result Collection.- Parameters:
ordering
- the ordering specification.
-
getOrdering
public String getOrdering()
Accessor for the ordering string for the query.- Returns:
- Ordering specification
-
setGrouping
public void setGrouping(String grouping)
Set the grouping specification for the result Collection.- Parameters:
grouping
- the grouping specification.
-
getGrouping
public String getGrouping()
Accessor for the grouping string for the query.- Returns:
- Grouping specification
-
setHaving
public void setHaving(String having)
Set the having specification for the result Collection.- Parameters:
having
- the having specification.
-
getHaving
public String getHaving()
Accessor for the having string for the query.- Returns:
- Having specification
-
setCandidates
public abstract void setCandidates(Extent<T> pcs)
Set the candidate Extent to query. To be implemented by extensions.- Parameters:
pcs
- the Candidate Extent.
-
setCandidates
public abstract void setCandidates(Collection<T> pcs)
Set the candidate Collection to query. To be implemented by extensions.- Parameters:
pcs
- the Candidate collection.
-
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.- 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 returntoExcl
- To element no (exclusive) to return
-
setRange
public void setRange(String range)
Set the range of the results. By default all results are returned but this allows specification of a range of elements required.- Parameters:
range
- Range string
-
getRange
public 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 String getRangeFromInclParam()
Accessor for the range lower limit parameter (inclusive).- Returns:
- Range lower limit
-
getRangeToExclParam
public String getRangeToExclParam()
Accessor for the range upper limit parameter (exclusive).- Returns:
- Range upper limit
-
setResult
public void setResult(String result)
Set the result for the results.- Parameters:
result
- Comma-separated result expressions
-
getResult
public 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 String getResultClassName()
-
setResultClassName
public void setResultClassName(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(Class result_cls)
Set the result class for the results. The result class must obey various things as per the JDO spec 14.6.12.- Parameters:
result_cls
- The result class
-
getResultClass
public 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 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(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.
-
setDatastoreReadTimeoutMillis
public void setDatastoreReadTimeoutMillis(Integer timeout)
Mutator to set the datastore read timeout for this query.- Parameters:
timeout
- The timeout
-
getDatastoreReadTimeoutMillis
public Integer getDatastoreReadTimeoutMillis()
Convenience accessor for the datastore read timeout (milliseconds). Returns null if not defined.- Returns:
- the timeout
-
setDatastoreWriteTimeoutMillis
public void setDatastoreWriteTimeoutMillis(Integer timeout)
Mutator to set the datastore write timeout for this query.- Parameters:
timeout
- The timeout
-
getDatastoreWriteTimeoutMillis
public Integer getDatastoreWriteTimeoutMillis()
Convenience accessor for the datastore write timeout (milliseconds). Returns null if not defined.- Returns:
- the timeout
-
getQueryManager
public QueryManager getQueryManager()
-
addSubquery
public void addSubquery(Query sub, String variableDecl, String candidateExpr, Map paramMap)
Method to add a subquery to this query.- Parameters:
sub
- The subqueryvariableDecl
- Declaration of variable that represents this subquery in the outer querycandidateExpr
- Candidate expressionparamMap
- Map of parameters for this subquery
-
getSubqueryForVariable
public Query.SubqueryDefinition getSubqueryForVariable(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(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(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 Object execute()
Execute the query and return the filtered results.- Returns:
- the filtered results (List, or Object).
- See Also:
executeWithArray(Object[] parameters)
-
executeWithArray
public Object executeWithArray(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 Object executeWithMap(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 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.
-
executeQuery
protected Object executeQuery(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 anUnsupportedOperationException
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 methodassertSupportsCancel()
-
cancel
public void cancel(Thread thread)
Method to cancel a running query in the specified Thread. Operates if the implementation supports cancelling of queries via the methodassertSupportsCancel()
- Parameters:
thread
- The thread
-
registerTask
protected void registerTask(Object taskObject)
-
deregisterTask
protected void deregisterTask()
-
cancelTaskObject
protected boolean cancelTaskObject(Object obj)
Method to perform the cancellation of a query task. This implementation does nothing. Override if you- Parameters:
obj
- The task- Returns:
- Whether the task was cancelled
-
performExecute
protected abstract Object performExecute(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
-
processesRangeInDatastoreQuery
public boolean processesRangeInDatastoreQuery()
Method to return if the datastore query will check any range constraints of this query. If this returns false and a range is specified then the range has to be managed using post-processing. This implementation assumes false and should be overridden if the datastore query can handle range processing.- Returns:
- Whether the query processes range in the datastore
-
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(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(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(Map parameters)
Execute the query to delete persistent objects. Provides a default implementation that executes the query to find the objects, and then calls ExecutionContext.deleteObjects() on the returned objects.- Parameters:
parameters
- the Map containing all of the parameters.- Returns:
- the number of deleted objects.
-
close
public void close(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 Map getParameterMapForValues(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
-
checkParameterTypesAgainstCompilation
protected void checkParameterTypesAgainstCompilation(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. Checks for unused input parameters. Doesn't check for missing parameters.- Parameters:
parameterValues
- The input parameter values keyed by their name (or position)
-
checkForMissingParameters
protected void checkForMissingParameters(Map parameterValues)
Method to check for any missing parameters that the query compilation is expecting but which aren't supplied to execute().- Parameters:
parameterValues
- The input parameter values keyed by their name (or position)
-
deepFindSymbolForParameterInCompilation
protected Symbol deepFindSymbolForParameterInCompilation(QueryCompilation compilation, Object paramKey)
-
resolveClassDeclaration
public Class resolveClassDeclaration(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.
-
assertIsOpen
protected void assertIsOpen()
-
getNativeQuery
public Object getNativeQuery()
Method returning the native query performed by this query (if the query has been compiled, and if the datastore plugin supports this).- Returns:
- The native query (e.g for RDBMS this is the SQL).
-
-