org.springframework.jdbc.object

Class RdbmsOperation

  • java.lang.Object
    • org.springframework.jdbc.object.RdbmsOperation
  • All Implemented Interfaces:
    InitializingBean
    Direct Known Subclasses:
    SqlCall, SqlOperation


    public abstract class RdbmsOperation
    extends java.lang.Object
    implements InitializingBean
    An "RDBMS operation" is a multi-threaded, reusable object representing a query, update, or stored procedure call. An RDBMS operation is not a command, as a command is not reusable. However, execute methods may take commands as arguments. Subclasses should be JavaBeans, allowing easy configuration.

    This class and subclasses throw runtime exceptions, defined in the org.springframework.dao package (and as thrown by the org.springframework.jdbc.core package, which the classes in this package use under the hood to perform raw JDBC operations).

    Subclasses should set SQL and add parameters before invoking the compile() method. The order in which parameters are added is significant. The appropriate execute or update method can then be invoked.

    Author:
    Rod Johnson, Juergen Hoeller
    See Also:
    SqlQuery, SqlUpdate, StoredProcedure, JdbcTemplate
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      protected Log logger
      Logger available to subclasses.
    • Constructor Summary

      Constructors 
      Constructor and Description
      RdbmsOperation() 
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method and Description
      void afterPropertiesSet()
      Ensures compilation if used in a bean factory.
      protected boolean allowsUnusedParameters()
      Return whether this operation accepts additional parameters that are given but not actually used.
      protected void checkCompiled()
      Check whether this operation has been compiled already; lazily compile it if not already compiled.
      void compile()
      Compile this query.
      protected abstract void compileInternal()
      Subclasses must implement this template method to perform their own compilation.
      void declareParameter(SqlParameter param)
      Declare a parameter for this operation.
      protected java.util.List<SqlParameter> getDeclaredParameters()
      Return a list of the declared SqlParameter objects.
      java.lang.String[] getGeneratedKeysColumnNames()
      Return the column names of the auto generated keys.
      JdbcTemplate getJdbcTemplate()
      Return the JdbcTemplate used by this operation object.
      int getResultSetType()
      Return whether statements will return a specific type of ResultSet.
      java.lang.String getSql()
      Subclasses can override this to supply dynamic SQL if they wish, but SQL is normally set by calling the setSql(java.lang.String) method or in a subclass constructor.
      boolean isCompiled()
      Is this operation "compiled"? Compilation, as in JDO, means that the operation is fully configured, and ready to use.
      boolean isReturnGeneratedKeys()
      Return whether statements should be capable of returning auto-generated keys.
      boolean isUpdatableResults()
      Return whether statements will return updatable ResultSets.
      protected java.lang.String resolveSql()
      Resolve the configured SQL for actual use.
      void setDataSource(javax.sql.DataSource dataSource)
      Set the JDBC DataSource to obtain connections from.
      void setFetchSize(int fetchSize)
      Set the fetch size for this RDBMS operation.
      void setGeneratedKeysColumnNames(java.lang.String... names)
      Set the column names of the auto-generated keys.
      void setJdbcTemplate(JdbcTemplate jdbcTemplate)
      An alternative to the more commonly used setDataSource(javax.sql.DataSource) when you want to use the same JdbcTemplate in multiple RdbmsOperations.
      void setMaxRows(int maxRows)
      Set the maximum number of rows for this RDBMS operation.
      void setParameters(SqlParameter... parameters)
      Add one or more declared parameters.
      void setQueryTimeout(int queryTimeout)
      Set the query timeout for statements that this RDBMS operation executes.
      void setResultSetType(int resultSetType)
      Set whether to use statements that return a specific type of ResultSet.
      void setReturnGeneratedKeys(boolean returnGeneratedKeys)
      Set whether prepared statements should be capable of returning auto-generated keys.
      void setSql(java.lang.String sql)
      Set the SQL executed by this operation.
      void setTypes(int[] types)
      Add anonymous parameters, specifying only their SQL types as defined in the java.sql.Types class.
      void setUpdatableResults(boolean updatableResults)
      Set whether to use statements that are capable of returning updatable ResultSets.
      protected boolean supportsLobParameters()
      Return whether BLOB/CLOB parameters are supported for this kind of operation.
      protected void validateNamedParameters(java.util.Map<java.lang.String,?> parameters)
      Validate the named parameters passed to an execute method based on declared parameters.
      protected void validateParameters(java.lang.Object[] parameters)
      Validate the parameters passed to an execute method based on declared parameters.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • logger

        protected final Log logger
        Logger available to subclasses.
    • Constructor Detail

      • RdbmsOperation

        public RdbmsOperation()
    • Method Detail

      • setFetchSize

        public void setFetchSize(int fetchSize)
        Set the fetch size for this RDBMS operation. This is important for processing large result sets: Setting this higher than the default value will increase processing speed at the cost of memory consumption; setting this lower can avoid transferring row data that will never be read by the application.

        Default is 0, indicating to use the driver's default.

        See Also:
        JdbcTemplate.setFetchSize(int)
      • setMaxRows

        public void setMaxRows(int maxRows)
        Set the maximum number of rows for this RDBMS operation. This is important for processing subsets of large result sets, avoiding to read and hold the entire result set in the database or in the JDBC driver.

        Default is 0, indicating to use the driver's default.

        See Also:
        JdbcTemplate.setMaxRows(int)
      • setQueryTimeout

        public void setQueryTimeout(int queryTimeout)
        Set the query timeout for statements that this RDBMS operation executes.

        Default is 0, indicating to use the JDBC driver's default.

        Note: Any timeout specified here will be overridden by the remaining transaction timeout when executing within a transaction that has a timeout specified at the transaction level.

      • setResultSetType

        public void setResultSetType(int resultSetType)
        Set whether to use statements that return a specific type of ResultSet.
        Parameters:
        resultSetType - the ResultSet type
        See Also:
        ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.TYPE_SCROLL_SENSITIVE, Connection.prepareStatement(String, int, int)
      • getResultSetType

        public int getResultSetType()
        Return whether statements will return a specific type of ResultSet.
      • setUpdatableResults

        public void setUpdatableResults(boolean updatableResults)
        Set whether to use statements that are capable of returning updatable ResultSets.
        See Also:
        Connection.prepareStatement(String, int, int)
      • isUpdatableResults

        public boolean isUpdatableResults()
        Return whether statements will return updatable ResultSets.
      • setReturnGeneratedKeys

        public void setReturnGeneratedKeys(boolean returnGeneratedKeys)
        Set whether prepared statements should be capable of returning auto-generated keys.
        See Also:
        Connection.prepareStatement(String, int)
      • isReturnGeneratedKeys

        public boolean isReturnGeneratedKeys()
        Return whether statements should be capable of returning auto-generated keys.
      • setGeneratedKeysColumnNames

        public void setGeneratedKeysColumnNames(java.lang.String... names)
        Set the column names of the auto-generated keys.
        See Also:
        Connection.prepareStatement(String, String[])
      • getGeneratedKeysColumnNames

        @Nullable
        public java.lang.String[] getGeneratedKeysColumnNames()
        Return the column names of the auto generated keys.
      • setSql

        public void setSql(java.lang.String sql)
        Set the SQL executed by this operation.
      • getSql

        @Nullable
        public java.lang.String getSql()
        Subclasses can override this to supply dynamic SQL if they wish, but SQL is normally set by calling the setSql(java.lang.String) method or in a subclass constructor.
      • resolveSql

        protected java.lang.String resolveSql()
        Resolve the configured SQL for actual use.
        Returns:
        the SQL (never null)
        Since:
        5.0
      • declareParameter

        public void declareParameter(SqlParameter param)
                              throws InvalidDataAccessApiUsageException
        Declare a parameter for this operation.

        The order in which this method is called is significant when using positional parameters. It is not significant when using named parameters with named SqlParameter objects here; it remains significant when using named parameters in combination with unnamed SqlParameter objects here.

        Parameters:
        param - the SqlParameter to add. This will specify SQL type and (optionally) the parameter's name. Note that you typically use the SqlParameter class itself here, not any of its subclasses.
        Throws:
        InvalidDataAccessApiUsageException - if the operation is already compiled, and hence cannot be configured further
      • setParameters

        public void setParameters(SqlParameter... parameters)
        Add one or more declared parameters. Used for configuring this operation when used in a bean factory. Each parameter will specify SQL type and (optionally) the parameter's name.
        Parameters:
        parameters - an array containing the declared SqlParameter objects
        See Also:
        declaredParameters
      • getDeclaredParameters

        protected java.util.List<SqlParameter> getDeclaredParameters()
        Return a list of the declared SqlParameter objects.
      • isCompiled

        public boolean isCompiled()
        Is this operation "compiled"? Compilation, as in JDO, means that the operation is fully configured, and ready to use. The exact meaning of compilation will vary between subclasses.
        Returns:
        whether this operation is compiled and ready to use
      • checkCompiled

        protected void checkCompiled()
        Check whether this operation has been compiled already; lazily compile it if not already compiled.

        Automatically called by validateParameters.

        See Also:
        validateParameters(java.lang.Object[])
      • validateParameters

        protected void validateParameters(@Nullable
                                          java.lang.Object[] parameters)
                                   throws InvalidDataAccessApiUsageException
        Validate the parameters passed to an execute method based on declared parameters. Subclasses should invoke this method before every executeQuery() or update() method.
        Parameters:
        parameters - parameters supplied (may be null)
        Throws:
        InvalidDataAccessApiUsageException - if the parameters are invalid
      • validateNamedParameters

        protected void validateNamedParameters(@Nullable
                                               java.util.Map<java.lang.String,?> parameters)
                                        throws InvalidDataAccessApiUsageException
        Validate the named parameters passed to an execute method based on declared parameters. Subclasses should invoke this method before every executeQuery() or update() method.
        Parameters:
        parameters - parameter Map supplied (may be null)
        Throws:
        InvalidDataAccessApiUsageException - if the parameters are invalid
      • compileInternal

        protected abstract void compileInternal()
                                         throws InvalidDataAccessApiUsageException
        Subclasses must implement this template method to perform their own compilation. Invoked after this base class's compilation is complete.

        Subclasses can assume that SQL and a DataSource have been supplied.

        Throws:
        InvalidDataAccessApiUsageException - if the subclass hasn't been properly configured
      • supportsLobParameters

        protected boolean supportsLobParameters()
        Return whether BLOB/CLOB parameters are supported for this kind of operation.

        The default is true.

      • allowsUnusedParameters

        protected boolean allowsUnusedParameters()
        Return whether this operation accepts additional parameters that are given but not actually used. Applies in particular to parameter Maps.

        The default is false.

        See Also:
        StoredProcedure