Package org.datanucleus.store.rdbms.query

Class SQLQuery

  • All Implemented Interfaces:
    Serializable, org.datanucleus.ExecutionContextListener
    public final class SQLQuery
extends org.datanucleus.store.query.Query
    A Query using SQL. The majority of this has to be specified in the query filter itself. There are no variables/imports. Ordering/grouping is explicit in the query.

    Results

    Results from this type of query will be :-
    • resultClass - each row of the ResultSet is converted into an instance of the result class
    • candidateClass - each row of the ResultSet is converted into an instance of the candidate
    • Object[] - when no candidate or result class specified
    • Long - when the query is an INSERT/UPDATE/DELETE/MERGE

    Parameters

    Parameters to this type of query can be :-
    • Positional : The SQL statement includes "?" and the parameters are positional starting at 1 (just like in JDBC).
    • Numbered : The SQL statement includes "?1", "?2" etc (with numbers starting at 1) and the users input of parameters at execute is of the numbered parameters.
    • Named : The SQL statement includes ":myParam1", ":myOtherParam" etc and the users input of parameters via "executeWithMap" includes values for all specified names.
    See Also:
    Serialized Form

    • Nested Class Summary

      • Nested classes/interfaces inherited from class org.datanucleus.store.query.Query

        org.datanucleus.store.query.Query.QueryType, org.datanucleus.store.query.Query.SubqueryDefinition

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected String compiledSQL
      The actual SQL issued at execution time.
      protected String inputSQL
      The statement that the user specified to the Query.
      protected boolean isCompiled
      State variable for the compilation state
      protected org.datanucleus.metadata.QueryResultMetaData resultMetaData
      MetaData defining the results of the query.
      protected StatementMappingIndex[] stmtMappings
      Mappings for the result of the query.

      • Fields inherited from class org.datanucleus.store.query.Query

        candidateClass, candidateClassName, clr, compilation, ec, explicitParameters, explicitVariables, EXTENSION_CHECK_UNUSED_PARAMETERS, EXTENSION_CLOSE_RESULTS_AT_EC_CLOSE, EXTENSION_COMPILATION_CACHED, EXTENSION_COMPILE_OPTIMISE_VAR_THIS, EXTENSION_EVALUATE_IN_MEMORY, EXTENSION_EXCLUDE_SUBCLASSES, EXTENSION_FLUSH_BEFORE_EXECUTION, EXTENSION_JDOQL_ALLOW_ALL, EXTENSION_JDOQL_STRICT, EXTENSION_JPQL_ALLOW_RANGE, EXTENSION_JPQL_STRICT, EXTENSION_LOAD_RESULTS_AT_COMMIT, EXTENSION_QUERY_TYPE, EXTENSION_RESULT_CACHE_TYPE, EXTENSION_RESULT_CACHE_VALIDATE_OBJECTS, EXTENSION_RESULT_SIZE_METHOD, EXTENSION_RESULTS_CACHED, EXTENSION_SQL_ALLOW_ALL, EXTENSION_SQL_SYNTAX_CHECKS, EXTENSION_UPDATE_ALL_CANDIDATE_FIELDS, EXTENSION_USE_FETCH_PLAN, extensions, filter, from, fromInclNo, fromInclParam, grouping, having, ignoreCache, implicitParameters, imports, inputParameters, insertFields, insertSelectQuery, ordering, parameterNames, parsedImports, queryResults, range, result, resultClass, resultClassName, resultDistinct, storeMgr, subclasses, subqueries, tasks, toExclNo, toExclParam, type, unique, unmodifiable, update

    • Constructor Summary

      Constructors 
      Constructor Description
      SQLQuery​(org.datanucleus.store.StoreManager storeMgr, org.datanucleus.ExecutionContext ec)
      Constructs a new query instance.
      SQLQuery​(org.datanucleus.store.StoreManager storeMgr, org.datanucleus.ExecutionContext ec, String queryString)
      Constructs a new query instance for the provided SQL query.
      SQLQuery​(org.datanucleus.store.StoreManager storeMgr, org.datanucleus.ExecutionContext ec, SQLQuery query)
      Constructor for a new query using the existing query as start point.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void assertSupportsCancel()
      Method that will throw an UnsupportedOperationException if the query implementation doesn't support cancelling queries.
      static boolean columnNamesAreTheSame​(DatastoreAdapter dba, String name1, String name2)
      Convenience method to compare two column names.
      void compileInternal​(Map parameterValues)
      Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.
      void declareExplicitParameters​(String parameters)
      Declare the explicit parameters to be used in the query.
      void declareExplicitVariables​(String variables)
      Declare the unbound variables to be used in the query.
      void declareImports​(String imports)
      Set the import statements to be used to identify the fully qualified name of variables or parameters.
      protected void discardCompiled()
      Utility to remove any previous compilation of this Query.
      boolean equals​(Object obj)  
      Object executeWithArray​(Object[] parameters)
      Execute the query and return the filtered List.
      Object executeWithMap​(Map executeParameters)
      Execute the query using the input Map of parameters.
      String getLanguage()  
      protected ResultObjectFactory getResultObjectFactoryForCandidateClass​(ResultSet rs)
      Method to generate a ResultObjectFactory for converting rows of the provided ResultSet into instances of the candidate class.
      Set<String> getSupportedExtensions()
      Method to return the names of the extensions supported by this query.
      int hashCode()  
      protected boolean isCompiled()
      Method to return if the query is compiled.
      protected long performDeletePersistentAll​(Map parameters)
      Execute the query to delete persistent objects.
      protected Object performExecute​(Map parameters)
      Execute the query and return the result.
      protected Map prepareForExecution​(Map executeParameters)
      Method to process the input parameters preparing the statement and parameters for execution.
      boolean processesRangeInDatastoreQuery()  
      void setCandidates​(Collection pcs)
      Set the candidate Collection to query.
      void setCandidates​(org.datanucleus.store.query.Extent pcs)
      Set the candidate Extent to query.
      void setFilter​(String filter)
      Set the filter for the query.
      void setGrouping​(String grouping)
      Set the grouping specification for the result Collection.
      void setOrdering​(String ordering)
      Set the ordering specification for the result Collection.
      void setRange​(int fromIncl, int toExcl)
      Set the range of the results.
      void setResult​(String result)
      Set the result for the results.
      void setResultClass​(Class result_cls)
      Set the result class for the results.
      void setResultMetaData​(org.datanucleus.metadata.QueryResultMetaData qrmd)
      Method to set the MetaData defining the result.
      void setSubclasses​(boolean subclasses)
      Method to set whether to use subclasses.
      protected boolean shouldReturnSingleRow()
      Convenience method to return whether the query should return a single row.
      protected boolean supportsTimeout()  

      • Methods inherited from class org.datanucleus.store.query.Query

        addExtension, addSubquery, applyImplicitParameterValueToCompilation, applyImplicitParameterValueToSubqueries, assertIsModifiable, assertIsOpen, cancel, cancel, cancelTaskObject, checkForMissingParameters, checkParameterTypesAgainstCompilation, checkUnusedParameters, close, closeAll, compile, deepFindSymbolForParameterInCompilation, deletePersistentAll, deletePersistentAll, deletePersistentAll, deregisterTask, execute, executeQuery, executionContextClosing, getBooleanExtensionProperty, getCandidateClass, getCandidateClassMetaData, getCandidateClassName, getCompilation, getDatastoreReadTimeoutMillis, getDatastoreWriteTimeoutMillis, getExecutionContext, getExplicitParametersDeclaration, getExplicitVariablesDeclaration, getExtension, getExtensions, getFetchPlan, getFilter, getFrom, getGrouping, getHaving, getIgnoreCache, getImplicitParameters, getImportsDeclaration, getInputParameters, getInsertFields, getInsertSelectQuery, getNativeQuery, getOrdering, getParameterMapForValues, getParsedImports, getQueryManager, getRange, getRangeFromIncl, getRangeFromInclParam, getRangeToExcl, getRangeToExclParam, getResult, getResultClass, getResultClassName, getResultDistinct, getSerializeRead, getStoreManager, getStringExtensionProperty, getSubqueryForVariable, getType, getUpdate, hasSubqueryForVariable, isSubclasses, isUnique, isUnmodifiable, prepareDatastore, registerTask, resolveClassDeclaration, setCacheResults, setCandidateClass, setCandidateClassName, setCompilation, setDatastoreReadTimeoutMillis, setDatastoreWriteTimeoutMillis, setExtensions, setFetchPlan, setFrom, setHaving, setIgnoreCache, setImplicitParameter, setImplicitParameter, setInsertFields, setInsertSelectQuery, setRange, setRange, setResultClassName, setResultDistinct, setSerializeRead, setType, setUnique, setUnmodifiable, setUpdate, useCaching, useFetchPlan, useResultsCaching

    • Field Detail

      • inputSQL

        protected final transient String inputSQL
        The statement that the user specified to the Query.

      • compiledSQL

        protected transient String compiledSQL
        The actual SQL issued at execution time.

      • resultMetaData

        protected org.datanucleus.metadata.QueryResultMetaData resultMetaData
        MetaData defining the results of the query.

      • isCompiled

        protected transient boolean isCompiled
        State variable for the compilation state

      • stmtMappings

        protected transient StatementMappingIndex[] stmtMappings
        Mappings for the result of the query.

    • Constructor Detail

      • SQLQuery

        public SQLQuery​(org.datanucleus.store.StoreManager storeMgr,
                org.datanucleus.ExecutionContext ec,
                SQLQuery query)
        Constructor for a new query using the existing query as start point.
        Parameters:
        storeMgr - StoreManager for this query
        ec - execution context
        query - The existing query

      • SQLQuery

        public SQLQuery​(org.datanucleus.store.StoreManager storeMgr,
                org.datanucleus.ExecutionContext ec)
        Constructs a new query instance.
        Parameters:
        storeMgr - StoreManager for this query
        ec - execution context

      • SQLQuery

        public SQLQuery​(org.datanucleus.store.StoreManager storeMgr,
                org.datanucleus.ExecutionContext ec,
                String queryString)
        Constructs a new query instance for the provided SQL query.
        Parameters:
        storeMgr - StoreManager for this query
        ec - execution context
        queryString - The SQL query string

    • Method Detail

      • getSupportedExtensions

        public Set<String> getSupportedExtensions()
        Method to return the names of the extensions supported by this query. To be overridden by subclasses where they support additional extensions.
        Overrides:
        getSupportedExtensions in class org.datanucleus.store.query.Query
        Returns:
        The supported extension names

      • getLanguage

        public String getLanguage()
        Overrides:
        getLanguage in class org.datanucleus.store.query.Query

      • setCandidates

        public void setCandidates​(org.datanucleus.store.query.Extent pcs)
        Set the candidate Extent to query. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Specified by:
        setCandidates in class org.datanucleus.store.query.Query
        Parameters:
        pcs - the Candidate Extent.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown since method not applicable

      • setCandidates

        public void setCandidates​(Collection pcs)
        Set the candidate Collection to query. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Specified by:
        setCandidates in class org.datanucleus.store.query.Query
        Parameters:
        pcs - the Candidate collection.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown since method not applicable

      • setResult

        public void setResult​(String result)
        Set the result for the results. The application might want to get results from a query that are not instances of the candidate class. The results might be fields of persistent instances, instances of classes other than the candidate class, or aggregates of fields. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        setResult in class org.datanucleus.store.query.Query
        Parameters:
        result - The result parameter consists of the optional keyword distinct followed by a commaseparated list of named result expressions or a result class specification.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown.

      • setResultMetaData

        public void setResultMetaData​(org.datanucleus.metadata.QueryResultMetaData qrmd)
        Method to set the MetaData defining the result. Setting this will unset the resultClass.
        Overrides:
        setResultMetaData in class org.datanucleus.store.query.Query
        Parameters:
        qrmd - Query Result MetaData

      • setResultClass

        public void setResultClass​(Class result_cls)
        Set the result class for the results. Setting this will unset the resultMetaData.
        Overrides:
        setResultClass in class org.datanucleus.store.query.Query
        Parameters:
        result_cls - The result class

      • setRange

        public void setRange​(int fromIncl,
                     int toExcl)
        Set the range of the results. Not applicable for SQL. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Parameters:
        fromIncl - From element no (inclusive) to return
        toExcl - To element no (exclusive) to return
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown.

      • setSubclasses

        public void setSubclasses​(boolean subclasses)
        Method to set whether to use subclasses. Not applicable for SQL. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        setSubclasses in class org.datanucleus.store.query.Query
        Parameters:
        subclasses - Whether to use subclasses
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown.

      • setFilter

        public void setFilter​(String filter)
        Set the filter for the query. Not applicable for SQL. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        setFilter in class org.datanucleus.store.query.Query
        Parameters:
        filter - the query filter.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown since method not applicable

      • declareExplicitVariables

        public void declareExplicitVariables​(String variables)
        Declare the unbound variables to be used in the query. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        declareExplicitVariables in class org.datanucleus.store.query.Query
        Parameters:
        variables - the variables separated by semicolons.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown since method not applicable

      • declareExplicitParameters

        public void declareExplicitParameters​(String parameters)
        Declare the explicit parameters to be used in the query. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        declareExplicitParameters in class org.datanucleus.store.query.Query
        Parameters:
        parameters - the parameters separated by semicolons.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown.

      • declareImports

        public void declareImports​(String imports)
        Set the import statements to be used to identify the fully qualified name of variables or parameters. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        declareImports in class org.datanucleus.store.query.Query
        Parameters:
        imports - import statements separated by semicolons.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown.

      • setGrouping

        public void setGrouping​(String grouping)
        Set the grouping specification for the result Collection. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        setGrouping in class org.datanucleus.store.query.Query
        Parameters:
        grouping - the grouping specification.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown.

      • setOrdering

        public void setOrdering​(String ordering)
        Set the ordering specification for the result Collection. This implementation always throws a NucleusUserException since this concept doesn't apply to SQL queries.
        Overrides:
        setOrdering in class org.datanucleus.store.query.Query
        Parameters:
        ordering - the ordering specification.
        Throws:
        org.datanucleus.exceptions.NucleusUserException - Always thrown.

      • performDeletePersistentAll

        protected long performDeletePersistentAll​(Map parameters)
        Execute the query to delete persistent objects.
        Overrides:
        performDeletePersistentAll in class org.datanucleus.store.query.Query
        Parameters:
        parameters - the Map containing all of the parameters.
        Returns:
        the filtered QueryResult of the deleted objects.

      • shouldReturnSingleRow

        protected boolean shouldReturnSingleRow()
        Convenience method to return whether the query should return a single row.
        Overrides:
        shouldReturnSingleRow in class org.datanucleus.store.query.Query
        Returns:
        Whether it represents a unique row

      • processesRangeInDatastoreQuery

        public boolean processesRangeInDatastoreQuery()
        Overrides:
        processesRangeInDatastoreQuery in class org.datanucleus.store.query.Query

      • equals

        public boolean equals​(Object obj)
        Overrides:
        equals in class org.datanucleus.store.query.Query

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class org.datanucleus.store.query.Query

      • discardCompiled

        protected void discardCompiled()
        Utility to remove any previous compilation of this Query.
        Overrides:
        discardCompiled in class org.datanucleus.store.query.Query

      • isCompiled

        protected boolean isCompiled()
        Method to return if the query is compiled.
        Overrides:
        isCompiled in class org.datanucleus.store.query.Query
        Returns:
        Whether it is compiled

      • compileInternal

        public void compileInternal​(Map parameterValues)
        Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.
        Specified by:
        compileInternal in class org.datanucleus.store.query.Query

      • performExecute

        protected Object performExecute​(Map parameters)
        Execute the query and return the result. For a SELECT query this will be the QueryResult. For an UPDATE/DELETE it will be the row count for the update statement.
        Specified by:
        performExecute in class org.datanucleus.store.query.Query
        Parameters:
        parameters - the Map containing all of the parameters (positional parameters) (not null)
        Returns:
        the result of the query

      • executeWithArray

        public Object executeWithArray​(Object[] parameters)
        Execute the query and return the filtered List. Override the method in Query since we want the parameter names to be Integer based here.
        Overrides:
        executeWithArray in class org.datanucleus.store.query.Query
        Parameters:
        parameters - the Object array with all of the parameters.
        Returns:
        The query results

      • executeWithMap

        public Object executeWithMap​(Map executeParameters)
        Execute the query using the input Map of parameters.
        Overrides:
        executeWithMap in class org.datanucleus.store.query.Query
        Parameters:
        executeParameters - the Map of the parameters passed in to execute().
        Returns:
        The query results

      • prepareForExecution

        protected Map prepareForExecution​(Map executeParameters)
        Method to process the input parameters preparing the statement and parameters for execution. The parameters returned are ready for execution. Compiles the query, and updates the "compiledSQL" and "parameterNames". Supports positional parameters, numbered parameters (?1, ?2), and named parameters (:p1, :p3). If using named parameters then the keys of the Map must align to the names in the SQL. If using numbered/positional parameters then the keys of the Map must be Integer and align with the parameter numbers/positions.
        Parameters:
        executeParameters - The input parameters map
        Returns:
        Map of parameters for execution

      • assertSupportsCancel

        protected void assertSupportsCancel()
        Method that will throw an UnsupportedOperationException if the query implementation doesn't support cancelling queries.
        Overrides:
        assertSupportsCancel in class org.datanucleus.store.query.Query

      • supportsTimeout

        protected boolean supportsTimeout()
        Overrides:
        supportsTimeout in class org.datanucleus.store.query.Query

      • getResultObjectFactoryForCandidateClass

        protected ResultObjectFactory getResultObjectFactoryForCandidateClass​(ResultSet rs)
                                                               throws SQLException
        Method to generate a ResultObjectFactory for converting rows of the provided ResultSet into instances of the candidate class. Populates "stmtMappings".
        Parameters:
        rs - The ResultSet
        Returns:
        The ResultObjectFactory
        Throws:
        SQLException - Thrown if an error occurs processing the ResultSet

      • columnNamesAreTheSame

        public static boolean columnNamesAreTheSame​(DatastoreAdapter dba,
                                            String name1,
                                            String name2)
        Convenience method to compare two column names. Allows for case sensitivity issues, and for database added quoting.
        Parameters:
        dba - Datastore adapter
        name1 - The first name (from the datastore)
        name2 - The second name (from the user SQL statement)
        Returns:
        Whether they are the same