Class Query<T>

  • Type Parameters:
    T - Type of the candidate of this query
    All Implemented Interfaces:
    java.io.Serializable, ExecutionContextListener
    Direct Known Subclasses:
    AbstractJavaQuery, AbstractStoredProcedureQuery

    public abstract class Query<T>
    extends java.lang.Object
    implements java.io.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.
    • 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​(java.lang.String key, java.lang.Object value)
      Add a vendor-specific extension to 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 applyImplicitParameterValueToSubqueries​(java.lang.String name, java.lang.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 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 boolean cancelTaskObject​(java.lang.Object obj)
      Method to perform the cancellation of a query task.
      protected void checkForMissingParameters​(java.util.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​(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<java.lang.Object,​java.lang.Object> 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.
      protected Symbol deepFindSymbolForParameterInCompilation​(QueryCompilation compilation, java.lang.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​(java.lang.Object[] parameterValues)
      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.
      protected void deregisterTask()  
      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.
      protected java.lang.Object executeQuery​(java.util.Map<java.lang.Object,​java.lang.Object> 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<java.lang.Object,​java.lang.Object> 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​(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<T> getCandidateClass()
      Accessor for the class of the candidate instances of the query.
      protected AbstractClassMetaData getCandidateClassMetaData()  
      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).
      ExecutionContext getExecutionContext()
      Accessor for the Execution Context associated with this Query.
      java.lang.String getExplicitParametersDeclaration()
      Accessor for the explicit parameters declaration.
      java.lang.String getExplicitVariablesDeclaration()
      Accessor for the explicit variables declaration.
      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 getImportsDeclaration()
      Accessor for the imports declaration.
      java.util.Map<java.lang.Object,​java.lang.Object> getInputParameters()
      Accessor for the input parameters for this query.
      java.lang.String getInsertFields()
      Accessor for the INSERT fields of the query (if any).
      java.lang.String getInsertSelectQuery()
      Accessor for the INSERT select query (if any).
      java.lang.String getLanguage()
      Accessor for the query language.
      java.lang.Object getNativeQuery()
      Method returning the native query performed by this query (if the query has been compiled, and if the datastore plugin supports this).
      java.lang.String getOrdering()
      Accessor for the ordering string for the query.
      protected java.util.Map<java.lang.Object,​java.lang.Object> 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.
      java.lang.String getStringExtensionProperty​(java.lang.String name, java.lang.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​(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.
      private Symbol getSymbolForParameterInCompilation​(QueryCompilation compilation, java.lang.Object paramKey)
      Convenience method to find a symbol for the specified parameter in the provided compilation.
      Query.QueryType getType()
      Accessor for the query type.
      java.lang.String getUpdate()
      Accessor for the UPDATE clause of the query (if any).
      int hashCode()  
      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 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​(java.lang.Object taskObject)  
      java.lang.Class resolveClassDeclaration​(java.lang.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​(java.lang.Class<T> candidateClass)
      Mutator for the class of the candidate instances of the query.
      void setCandidateClassName​(java.lang.String candidateClassName)
      Convenience method to set the name of the candidate class.
      abstract void setCandidates​(java.util.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​(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<java.lang.String,​java.lang.Object> 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 setInsertFields​(java.lang.String insertFields)
      Set the INSERT fields of the query.
      void setInsertSelectQuery​(java.lang.String query)
      Set the INSERT select query.
      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​(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​(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

      • EXTENSION_FLUSH_BEFORE_EXECUTION

        public static final java.lang.String EXTENSION_FLUSH_BEFORE_EXECUTION
        See Also:
        Constant Field Values
      • EXTENSION_USE_FETCH_PLAN

        public static final java.lang.String EXTENSION_USE_FETCH_PLAN
        See Also:
        Constant Field Values
      • EXTENSION_RESULT_SIZE_METHOD

        public static final java.lang.String EXTENSION_RESULT_SIZE_METHOD
        See Also:
        Constant Field Values
      • EXTENSION_LOAD_RESULTS_AT_COMMIT

        public static final java.lang.String EXTENSION_LOAD_RESULTS_AT_COMMIT
        See Also:
        Constant Field Values
      • EXTENSION_RESULT_CACHE_TYPE

        public static final java.lang.String EXTENSION_RESULT_CACHE_TYPE
      • EXTENSION_RESULT_CACHE_VALIDATE_OBJECTS

        public static final java.lang.String EXTENSION_RESULT_CACHE_VALIDATE_OBJECTS
        See Also:
        Constant Field Values
      • EXTENSION_RESULTS_CACHED

        public static final java.lang.String EXTENSION_RESULTS_CACHED
        See Also:
        Constant Field Values
      • EXTENSION_COMPILATION_CACHED

        public static final java.lang.String EXTENSION_COMPILATION_CACHED
        See Also:
        Constant Field Values
      • EXTENSION_EVALUATE_IN_MEMORY

        public static final java.lang.String EXTENSION_EVALUATE_IN_MEMORY
        See Also:
        Constant Field Values
      • EXTENSION_CLOSE_RESULTS_AT_EC_CLOSE

        public static final java.lang.String EXTENSION_CLOSE_RESULTS_AT_EC_CLOSE
      • EXTENSION_CHECK_UNUSED_PARAMETERS

        public static final java.lang.String EXTENSION_CHECK_UNUSED_PARAMETERS
        See Also:
        Constant Field Values
      • EXTENSION_COMPILE_OPTIMISE_VAR_THIS

        public static final java.lang.String EXTENSION_COMPILE_OPTIMISE_VAR_THIS
        See Also:
        Constant Field Values
      • EXTENSION_UPDATE_ALL_CANDIDATE_FIELDS

        public static final java.lang.String EXTENSION_UPDATE_ALL_CANDIDATE_FIELDS
      • EXTENSION_JDOQL_ALLOW_ALL

        public static final java.lang.String EXTENSION_JDOQL_ALLOW_ALL
        See Also:
        Constant Field Values
      • EXTENSION_JDOQL_STRICT

        public static final java.lang.String EXTENSION_JDOQL_STRICT
        See Also:
        Constant Field Values
      • EXTENSION_JPQL_ALLOW_RANGE

        public static final java.lang.String EXTENSION_JPQL_ALLOW_RANGE
        See Also:
        Constant Field Values
      • EXTENSION_JPQL_STRICT

        public static final java.lang.String EXTENSION_JPQL_STRICT
        See Also:
        Constant Field Values
      • EXTENSION_SQL_ALLOW_ALL

        public static final java.lang.String EXTENSION_SQL_ALLOW_ALL
        See Also:
        Constant Field Values
      • EXTENSION_SQL_SYNTAX_CHECKS

        public static final java.lang.String EXTENSION_SQL_SYNTAX_CHECKS
        See Also:
        Constant Field Values
      • EXTENSION_EXCLUDE_SUBCLASSES

        public static final java.lang.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 java.lang.String EXTENSION_QUERY_TYPE
        See Also:
        Constant Field Values
      • candidateClass

        protected java.lang.Class<T> 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.
      • 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 (optional).
      • insertFields

        protected transient java.lang.String insertFields
        INSERT fields of a query (optional).
      • insertSelectQuery

        protected transient java.lang.String insertSelectQuery
        INSERT select query (optional).
      • 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.
      • unique

        protected boolean unique
        Whether to return single value, or collection from the query.
      • 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.
      • 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
      • 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.
      • 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.
      • fetchPlan

        private FetchPlan fetchPlan
        Fetch Plan to use for the query.
      • serializeRead

        private java.lang.Boolean serializeRead
        Whether to serialise (lock) any read objects from this query.
      • readTimeoutMillis

        private java.lang.Integer readTimeoutMillis
        Read timeout (milliseconds), if any.
      • writeTimeoutMillis

        private java.lang.Integer writeTimeoutMillis
        Write timeout (milliseconds), if any.
      • extensions

        protected java.util.Map<java.lang.String,​java.lang.Object> extensions
        Any extensions. These are stored with the key in lowercase.
      • 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.Map<java.lang.Object,​java.lang.Object> 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.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 java.util.Map<java.lang.Thread,​java.lang.Object> tasks
        Currently executing object for this query, keyed by the thread, to allow for cancellation.
      • inputParameters

        protected java.util.Map<java.lang.Object,​java.lang.Object> 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 query
        ec - 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 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()
        Overrides:
        hashCode in class java.lang.Object
      • 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
      • addExtension

        public void addExtension​(java.lang.String key,
                                 java.lang.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 key
        value - the extension value
      • setExtensions

        public void setExtensions​(java.util.Map<java.lang.String,​java.lang.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 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
      • getStringExtensionProperty

        public java.lang.String getStringExtensionProperty​(java.lang.String name,
                                                           java.lang.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 name
        resultIfNotSet - The value to return if there is neither an extension nor a persistence property of the same name
        Returns:
        The String 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 query (if any).
        Returns:
        Update clause
      • setInsertFields

        public void setInsertFields​(java.lang.String insertFields)
        Set the INSERT fields of the query.
        Parameters:
        insertFields - the fields to insert
      • getInsertFields

        public java.lang.String getInsertFields()
        Accessor for the INSERT fields of the query (if any).
        Returns:
        INSERT fields
      • setInsertSelectQuery

        public void setInsertSelectQuery​(java.lang.String query)
        Set the INSERT select query.
        Parameters:
        query - the query to use for inserting
      • getInsertSelectQuery

        public java.lang.String getInsertSelectQuery()
        Accessor for the INSERT select query (if any).
        Returns:
        INSERT select query
      • getCandidateClass

        public java.lang.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​(java.lang.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​(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
      • 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.
      • getImportsDeclaration

        public java.lang.String getImportsDeclaration()
        Accessor for the imports declaration.
        Returns:
        Imports declaration
      • declareExplicitParameters

        public void declareExplicitParameters​(java.lang.String parameters)
        Method to define the explicit parameters.
        Parameters:
        parameters - the list of parameters separated by commas
      • getExplicitParametersDeclaration

        public java.lang.String getExplicitParametersDeclaration()
        Accessor for the explicit parameters declaration.
        Returns:
        Explicit parameters declaration
      • declareExplicitVariables

        public void declareExplicitVariables​(java.lang.String variables)
        Method to define the explicit variables for the query.
        Parameters:
        variables - the variables separated by semicolons.
      • getExplicitVariablesDeclaration

        public java.lang.String getExplicitVariablesDeclaration()
        Accessor for the explicit variables declaration.
        Returns:
        Explicit variables declaration
      • 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
      • applyImplicitParameterValueToSubqueries

        protected boolean applyImplicitParameterValueToSubqueries​(java.lang.String name,
                                                                  java.lang.Object value,
                                                                  QueryCompilation comp)
      • 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
      • 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
      • 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​(java.util.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 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.
        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 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.
      • 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
      • 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 variable that represents this subquery in the outer query
        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<java.lang.Object,​java.lang.Object> 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<java.lang.Object,​java.lang.Object> 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<java.lang.Object,​java.lang.Object> 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 java.lang.Object executeQuery​(java.util.Map<java.lang.Object,​java.lang.Object> 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
      • registerTask

        protected void registerTask​(java.lang.Object taskObject)
      • deregisterTask

        protected void deregisterTask()
      • cancelTaskObject

        protected boolean cancelTaskObject​(java.lang.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 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
      • 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​(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 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​(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<java.lang.Object,​java.lang.Object> 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
      • 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. 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​(java.util.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,
                                                                 java.lang.Object paramKey)
      • getSymbolForParameterInCompilation

        private Symbol getSymbolForParameterInCompilation​(QueryCompilation compilation,
                                                          java.lang.Object paramKey)
        Convenience method to find a symbol for the specified parameter in the provided compilation.
        Parameters:
        compilation - The compilation
        paramKey - The parameter name/position
        Returns:
        The symbol (if present)
      • 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.
      • assertIsOpen

        protected void assertIsOpen()
      • getNativeQuery

        public java.lang.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).