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
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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
static class
Simple representation of a subquery, its candidate, params and variables. -
Field Summary
FieldsModifier and TypeFieldDescriptionThe candidate class for this query.protected String
Name of the candidate class (used when specified via Single-String).protected final ClassLoaderResolver
protected QueryCompilation
Query compilation (when using the generic query compiler).protected ExecutionContext
protected String
Any explicit parameters defined for this query, comma separated.protected String
Any explicit variables defined for this query, semicolon separated.static final String
static final String
static final String
static final String
static final String
static final String
Extension for the benefit of JPQL so that we can exclude subclasses (not possible with JPA API).static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
static final String
Any extensions.private FetchPlan
Fetch Plan to use for the query.protected String
The filter for the query.protected String
From clause of the query (optional).protected long
Query result range start position (inclusive).protected String
Query result range lower limit (inclusive) as a parameter name.protected String
Grouping clause for the query, for use with aggregate expressions.protected String
Having clause for the queryprotected boolean
Whether to ignore dirty instances in the query.Map of implicit parameters, keyed by the name/number.protected String
Any import declarations for the types used in the query, semicolon separated.protected String
INSERT fields of a query (optional).protected String
INSERT select query (optional).protected String
Ordering clause for the query, governing the order objects are returned.protected String[]
Array of (explicit) parameter names.protected Imports
The imports definition.protected Set
<QueryResult> All query results obtained from this query.protected String
String form of the query result range.private Integer
Read timeout (milliseconds), if any.protected String
Specification of the result of the query e.g aggregates etc.protected Class
User-defined class that best represents the results of a query.protected String
Temporary variable for the name of the result class (may need resolving using imports).protected boolean
Whether the results are marked as distinct.private Boolean
Whether to serialise (lock) any read objects from this query.private static final long
protected final StoreManager
protected boolean
Whether to allow subclasses of the candidate class be returned.protected Map
<String, Query.SubqueryDefinition> Any subqueries, keyed by the variable name that they represent.Currently executing object for this query, keyed by the thread, to allow for cancellation.protected long
Query result range end position (exclusive).protected String
Query result range upper limit (exclusive) as a parameter name.protected Query.QueryType
Type of query.protected boolean
Whether to return single value, or collection from the query.protected boolean
Whether the query can be modifiedprotected String
UPDATE clause of a query (optional).private Integer
Write timeout (milliseconds), if any. -
Constructor Summary
ConstructorsConstructorDescriptionQuery
(StoreManager storeMgr, ExecutionContext ec) Constructs a new query instance that uses the given ExecutionContext. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
Method to throw an exception if the query is currently not modifiable.protected void
protected void
Method that will throw anUnsupportedOperationException
if the query implementation doesn't support cancelling queries.void
cancel()
Method to cancel any currently running queries.void
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
Whether the query compilation(s) should check for unused parameters.void
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<Object, Object> 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
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
protected void
Utility to remove any previous compilation of this Query.boolean
Equality operator.execute()
Execute the query and return the filtered results.protected Object
executeQuery
(Map<Object, Object> parameters) Method to execute the actual query.executeWithArray
(Object[] parameterValues) Execute the query and return the filtered results using the array of parameters.executeWithMap
(Map<Object, Object> parameters) Execute the query and return the filtered results using the map of parameters.void
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.Accessor for the class of the candidate instances of the query.protected AbstractClassMetaData
Accessor for the candidate class name.Accessor for the query compilation.Convenience accessor for the datastore read timeout (milliseconds).Convenience accessor for the datastore write timeout (milliseconds).Accessor for the Execution Context associated with this Query.Accessor for the explicit parameters declaration.Accessor for the explicit variables declaration.getExtension
(String key) Accessor for the value of an extension for this query.Accessor for the extensions defined for this query.This method retrieves the fetch plan associated with the Query.Accessor for the filter specification.getFrom()
Accessor for the FROM clause of the query.Accessor for the grouping string for the query.Accessor for the having string for the query.boolean
Accessor for the ignoreCache option setting.Accessor for the implicit parameters.Accessor for the imports declaration.Accessor for the input parameters for this query.Accessor for the INSERT fields of the query (if any).Accessor for the INSERT select query (if any).Accessor for the query language.Method returning the native query performed by this query (if the query has been compiled, and if the datastore plugin supports this).Accessor for the ordering string for the query.getParameterMapForValues
(Object[] parameterValues) Convenience method to convert the input parameters into a parameter map keyed by the parameter name.Accessor for the parsed imports.getRange()
Accessor for the range specification string.long
Accessor for the range lower limit (inclusive).Accessor for the range lower limit parameter (inclusive).long
Accessor for the range upper limit (exclusive).Accessor for the range upper limit parameter (exclusive).Accessor for the result specification string.Accessor for the result class.boolean
Accessor for whether the results are distinct.Accessor for whether to serialise (lock) any read objects retrieved from this query.Accessor for the StoreManager associated with this Query.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.getSubqueryForVariable
(String variableName) Accessor for the subquery for the supplied variable.Method to return the names of the extensions supported by this query.private Symbol
getSymbolForParameterInCompilation
(QueryCompilation compilation, Object paramKey) Convenience method to find a symbol for the specified parameter in the provided compilation.getType()
Accessor for the query type.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
Method to return if the query is compiled.boolean
Accessor for whether this query includes subclassesboolean
isUnique()
Accessor for whether the query results are unique.boolean
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
Convenience method that will flush any outstanding updates to the datastore.boolean
Method to return if the datastore query will check any range constraints of this query.protected void
registerTask
(Object taskObject) 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
Mutator for the FetchPlan of the query.void
Set the filter for the query.void
Set the candidates to the query.void
setGrouping
(String grouping) Set the grouping specification for the result Collection.void
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
Set the range of the results.void
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
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
Mutator for unmodifiable.void
Set the UPDATE clause of the query.protected boolean
Convenience method to return whether the query should return a single row.protected boolean
Convenience method for whether this query supports timeouts.boolean
Whether the query compilation(s) should be cached.protected boolean
Convenience accessor for whether to use the fetch plan with this query.boolean
Whether the results of the query should be cached.
-
Field Details
-
serialVersionUID
private static final long serialVersionUID- See Also:
-
EXTENSION_FLUSH_BEFORE_EXECUTION
- See Also:
-
EXTENSION_USE_FETCH_PLAN
- See Also:
-
EXTENSION_RESULT_SIZE_METHOD
- See Also:
-
EXTENSION_LOAD_RESULTS_AT_COMMIT
- See Also:
-
EXTENSION_RESULT_CACHE_TYPE
-
EXTENSION_RESULT_CACHE_VALIDATE_OBJECTS
- See Also:
-
EXTENSION_RESULTS_CACHED
- See Also:
-
EXTENSION_COMPILATION_CACHED
- See Also:
-
EXTENSION_EVALUATE_IN_MEMORY
- See Also:
-
EXTENSION_CLOSE_RESULTS_AT_EC_CLOSE
-
EXTENSION_CHECK_UNUSED_PARAMETERS
- See Also:
-
EXTENSION_COMPILE_OPTIMISE_VAR_THIS
- See Also:
-
EXTENSION_UPDATE_ALL_CANDIDATE_FIELDS
-
EXTENSION_JDOQL_ALLOW_ALL
- See Also:
-
EXTENSION_JDOQL_STRICT
- See Also:
-
EXTENSION_JPQL_ALLOW_RANGE
- See Also:
-
EXTENSION_JPQL_STRICT
- See Also:
-
EXTENSION_SQL_ALLOW_ALL
- See Also:
-
EXTENSION_SQL_SYNTAX_CHECKS
- See Also:
-
EXTENSION_EXCLUDE_SUBCLASSES
Extension for the benefit of JPQL so that we can exclude subclasses (not possible with JPA API). -
EXTENSION_QUERY_TYPE
- See Also:
-
storeMgr
-
ec
-
clr
-
type
Type of query. -
candidateClass
The candidate class for this query. -
candidateClassName
Name of the candidate class (used when specified via Single-String). -
subclasses
protected boolean subclassesWhether to allow subclasses of the candidate class be returned. -
from
From clause of the query (optional). -
update
UPDATE clause of a query (optional). -
insertFields
INSERT fields of a query (optional). -
insertSelectQuery
INSERT select query (optional). -
result
Specification of the result of the query e.g aggregates etc. Doesn't include any "distinct". -
resultDistinct
protected boolean resultDistinctWhether the results are marked as distinct. This is extracted out of the result for clarity. -
unique
protected boolean uniqueWhether to return single value, or collection from the query. -
resultClass
User-defined class that best represents the results of a query. Populated if specified via setResultClass(). -
resultClassName
Temporary variable for the name of the result class (may need resolving using imports). -
filter
The filter for the query. -
ordering
Ordering clause for the query, governing the order objects are returned. -
grouping
Grouping clause for the query, for use with aggregate expressions. -
having
Having clause for the query -
imports
Any import declarations for the types used in the query, semicolon separated. -
explicitVariables
Any explicit variables defined for this query, semicolon separated. -
explicitParameters
Any explicit parameters defined for this query, comma separated. -
range
String form of the query result range. For convenience only. -
fromInclNo
protected long fromInclNoQuery result range start position (inclusive). -
toExclNo
protected long toExclNoQuery result range end position (exclusive). -
fromInclParam
Query result range lower limit (inclusive) as a parameter name. -
toExclParam
Query result range upper limit (exclusive) as a parameter name. -
unmodifiable
protected boolean unmodifiableWhether the query can be modified -
ignoreCache
protected boolean ignoreCacheWhether to ignore dirty instances in the query. -
fetchPlan
Fetch Plan to use for the query. -
serializeRead
Whether to serialise (lock) any read objects from this query. -
readTimeoutMillis
Read timeout (milliseconds), if any. -
writeTimeoutMillis
Write timeout (milliseconds), if any. -
extensions
Any extensions. These are stored with the key in lowercase. -
subqueries
Any subqueries, keyed by the variable name that they represent. -
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
The imports definition. -
parameterNames
Array of (explicit) parameter names. -
compilation
Query compilation (when using the generic query compiler). -
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
Currently executing object for this query, keyed by the thread, to allow for cancellation. -
inputParameters
-
-
Constructor Details
-
Query
Constructs a new query instance that uses the given ExecutionContext.- Parameters:
storeMgr
- Store Manager used for this queryec
- execution context
-
-
Method Details
-
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
Accessor for the query language.- Returns:
- Query language
-
discardCompiled
protected void discardCompiled()Utility to remove any previous compilation of this Query. -
setCompilation
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
Equality operator. -
hashCode
public int hashCode() -
getType
Accessor for the query type.- Returns:
- The query type
-
setType
Mutator to set the query type.- Parameters:
type
- The query type
-
getStoreManager
Accessor for the StoreManager associated with this Query.- Returns:
- the StoreManager associated with this Query.
-
getExecutionContext
Accessor for the Execution Context associated with this Query.- Returns:
- Execution Context for the query
-
executionContextClosing
Description copied from interface:ExecutionContextListener
Method called when the specified ExecutionContext is closing.- Specified by:
executionContextClosing
in interfaceExecutionContextListener
- Parameters:
ec
- The ExecutionContext
-
addExtension
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
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:
-
getExtension
Accessor for the value of an extension for this query.- Parameters:
key
- The key- Returns:
- The value (if this extension is specified)
-
getExtensions
Accessor for the extensions defined for this query.- Returns:
- Extensions
-
getBooleanExtensionProperty
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
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
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
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
Mutator for the FetchPlan of the query. This is called when applying a named FetchPlan.- Parameters:
fp
- The FetchPlan
-
setUpdate
Set the UPDATE clause of the query.- Parameters:
update
- the update clause
-
getUpdate
Accessor for the UPDATE clause of the query (if any).- Returns:
- Update clause
-
setInsertFields
Set the INSERT fields of the query.- Parameters:
insertFields
- the fields to insert
-
getInsertFields
Accessor for the INSERT fields of the query (if any).- Returns:
- INSERT fields
-
setInsertSelectQuery
Set the INSERT select query.- Parameters:
query
- the query to use for inserting
-
getInsertSelectQuery
Accessor for the INSERT select query (if any).- Returns:
- INSERT select query
-
getCandidateClass
Accessor for the class of the candidate instances of the query.- Returns:
- the Class of the candidate instances.
-
setCandidateClass
Mutator for the class of the candidate instances of the query.- Parameters:
candidateClass
- the Class of the candidate instances.
-
setCandidateClassName
Convenience method to set the name of the candidate class.- Parameters:
candidateClassName
- Name of the candidate class
-
getCandidateClassName
Accessor for the candidate class name.- Returns:
- Name of the candidate class (if any)
-
getCandidateClassMetaData
-
setFrom
Set the candidates to the query.- Parameters:
from
- the candidates
-
getFrom
Accessor for the FROM clause of the query.- Returns:
- From clause
-
setFilter
Set the filter for the query.- Parameters:
filter
- the query filter.
-
getFilter
Accessor for the filter specification.- Returns:
- Filter specification
-
declareImports
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
Accessor for the imports declaration.- Returns:
- Imports declaration
-
declareExplicitParameters
Method to define the explicit parameters.- Parameters:
parameters
- the list of parameters separated by commas
-
getExplicitParametersDeclaration
Accessor for the explicit parameters declaration.- Returns:
- Explicit parameters declaration
-
declareExplicitVariables
Method to define the explicit variables for the query.- Parameters:
variables
- the variables separated by semicolons.
-
getExplicitVariablesDeclaration
Accessor for the explicit variables declaration.- Returns:
- Explicit variables declaration
-
setImplicitParameter
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
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
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
Accessor for the implicit parameters. Named params are keyed by the name. Positional params are keyed by the Integer(position).- Returns:
- Implicit params
-
setOrdering
Set the ordering specification for the result Collection.- Parameters:
ordering
- the ordering specification.
-
getOrdering
Accessor for the ordering string for the query.- Returns:
- Ordering specification
-
setGrouping
Set the grouping specification for the result Collection.- Parameters:
grouping
- the grouping specification.
-
getGrouping
Accessor for the grouping string for the query.- Returns:
- Grouping specification
-
setHaving
Set the having specification for the result Collection.- Parameters:
having
- the having specification.
-
getHaving
Accessor for the having string for the query.- Returns:
- Having specification
-
setCandidates
Set the candidate Extent to query. To be implemented by extensions.- Parameters:
pcs
- the Candidate Extent.
-
setCandidates
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
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
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
Accessor for the range lower limit parameter (inclusive).- Returns:
- Range lower limit
-
getRangeToExclParam
Accessor for the range upper limit parameter (exclusive).- Returns:
- Range upper limit
-
setResult
Set the result for the results.- Parameters:
result
- Comma-separated result expressions
-
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
-
setResultClassName
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
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
Accessor for the result class.- Returns:
- Result class
-
setResultMetaData
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:
-
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
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
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
Mutator to set the datastore read timeout for this query.- Parameters:
timeout
- The timeout
-
getDatastoreReadTimeoutMillis
Convenience accessor for the datastore read timeout (milliseconds). Returns null if not defined.- Returns:
- the timeout
-
setDatastoreWriteTimeoutMillis
Mutator to set the datastore write timeout for this query.- Parameters:
timeout
- The timeout
-
getDatastoreWriteTimeoutMillis
Convenience accessor for the datastore write timeout (milliseconds). Returns null if not defined.- Returns:
- the timeout
-
getQueryManager
-
addSubquery
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
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
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
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
Method to compile the query. To be implemented by the query implementation.- Parameters:
parameterValues
- Parameter values keyed by name (when compiling for execution)
-
getParsedImports
Accessor for the parsed imports. If no imports are set then adds candidate class and user imports.- Returns:
- Parsed imports
-
execute
Execute the query and return the filtered results.- Returns:
- the filtered results (List, or Object).
- See Also:
-
executeWithArray
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:
-
executeWithMap
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:
-
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
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
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
-
deregisterTask
protected void deregisterTask() -
cancelTaskObject
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
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
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
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
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
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
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
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
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) -
getSymbolForParameterInCompilation
Convenience method to find a symbol for the specified parameter in the provided compilation.- Parameters:
compilation
- The compilationparamKey
- The parameter name/position- Returns:
- The symbol (if present)
-
resolveClassDeclaration
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
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).
-