SqlFunction (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jdbc.object

## Class SqlFunction<T>

- java.lang.Object
- - org.springframework.jdbc.object.RdbmsOperation
  - - org.springframework.jdbc.object.SqlOperation
    - - org.springframework.jdbc.object.SqlQuery<T>
      - - org.springframework.jdbc.object.MappingSqlQueryWithParameters<T>
        - - org.springframework.jdbc.object.MappingSqlQuery<T>
          - - org.springframework.jdbc.object.SqlFunction<T>

- All Implemented Interfaces:
    InitializingBean

      public class SqlFunction<T>
      extends MappingSqlQuery<T>

  SQL "function" wrapper for a query that returns a single row of results. The default behavior is to return an int, but that can be overridden by using the constructor with an extra return type parameter.

  Intended to use to call SQL functions that return a single result using a query like "select user()" or "select sysdate from dual". It is not intended for calling more complex stored functions or for using a CallableStatement to invoke a stored procedure or stored function. Use StoredProcedure or SqlCall for this type of processing.

  This is a concrete class, which there is often no need to subclass. Code using this package can create an object of this type, declaring SQL and parameters, and then invoke the appropriate `run` method repeatedly to execute the function. Subclasses are only supposed to add specialized `run` methods for specific parameter and return types.

  Like all RdbmsOperation objects, SqlFunction objects are thread-safe.

  Author:
    Rod Johnson, Juergen Hoeller, Jean-Pierre Pawlak
  See Also:
    `StoredProcedure`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.springframework.jdbc.object.MappingSqlQueryWithParameters

      `MappingSqlQueryWithParameters.RowMapperImpl`

  - ### Field Summary

    - ### Fields inherited from class org.springframework.jdbc.object.RdbmsOperation

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SqlFunction()` Constructor to allow use as a JavaBean.
    `SqlFunction(DataSource ds, String sql)` Create a new SqlFunction object with SQL, but without parameters.
    `SqlFunction(DataSource ds, String sql, int[] types)` Create a new SqlFunction object with SQL and parameters.
    `SqlFunction(DataSource ds, String sql, int[] types, Class<T> resultType)` Create a new SqlFunction object with SQL, parameters and a result type.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected T` | `mapRow(ResultSet rs, int rowNum)` This implementation of this method extracts a single value from the single row returned by the function.
    `int` | `run()` Convenient method to run the function without arguments.
    `int` | `run(int parameter)` Convenient method to run the function with a single int argument.
    `int` | `run(Object... parameters)` Analogous to the SqlQuery.execute([]) method.
    `Object` | `runGeneric()` Convenient method to run the function without arguments, returning the value as an object.
    `Object` | `runGeneric(int parameter)` Convenient method to run the function with a single int argument.
    `Object` | `runGeneric(Object[] parameters)` Analogous to the `SqlQuery.findObject(Object[])` method.
    `void` | `setResultType(Class<T> resultType)` Specify the type that the result object is required to match.

    - ### Methods inherited from class org.springframework.jdbc.object.MappingSqlQuery

      `mapRow`

    - ### Methods inherited from class org.springframework.jdbc.object.MappingSqlQueryWithParameters

      `newRowMapper`

    - ### Methods inherited from class org.springframework.jdbc.object.SqlQuery

      `execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, executeByNamedParam, executeByNamedParam, findObject, findObject, findObject, findObject, findObject, findObject, findObject, findObject, findObject, findObject, findObjectByNamedParam, findObjectByNamedParam, getRowsExpected, setRowsExpected`

    - ### Methods inherited from class org.springframework.jdbc.object.SqlOperation

      `compileInternal, getParsedSql, newPreparedStatementCreator, newPreparedStatementCreator, newPreparedStatementSetter, onCompileInternal`

    - ### Methods inherited from class org.springframework.jdbc.object.RdbmsOperation

      `afterPropertiesSet, allowsUnusedParameters, checkCompiled, compile, declareParameter, getDeclaredParameters, getGeneratedKeysColumnNames, getJdbcTemplate, getResultSetType, getSql, isCompiled, isReturnGeneratedKeys, isUpdatableResults, setDataSource, setFetchSize, setGeneratedKeysColumnNames, setJdbcTemplate, setMaxRows, setParameters, setQueryTimeout, setResultSetType, setReturnGeneratedKeys, setSql, setTypes, setUpdatableResults, supportsLobParameters, validateNamedParameters, validateParameters`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SqlFunction

          public SqlFunction()

      Constructor to allow use as a JavaBean. A DataSource, SQL and any parameters must be supplied before invoking the `compile` method and using this object.
      See Also:
        `RdbmsOperation.setDataSource(javax.sql.DataSource)`, `RdbmsOperation.setSql(java.lang.String)`, `RdbmsOperation.compile()`

    - #### SqlFunction

          public SqlFunction(DataSource ds,
                     String sql)

      Create a new SqlFunction object with SQL, but without parameters. Must add parameters or settle with none.
      Parameters:
        `ds` - DataSource to obtain connections from
        `sql` - SQL to execute

    - #### SqlFunction

          public SqlFunction(DataSource ds,
                     String sql,
                     int[] types)

      Create a new SqlFunction object with SQL and parameters.
      Parameters:
        `ds` - DataSource to obtain connections from
        `sql` - SQL to execute
        `types` - SQL types of the parameters, as defined in the `java.sql.Types` class
      See Also:
        `Types`

    - #### SqlFunction

          public SqlFunction(DataSource ds,
                     String sql,
                     int[] types,
                     Class<T> resultType)

      Create a new SqlFunction object with SQL, parameters and a result type.
      Parameters:
        `ds` - DataSource to obtain connections from
        `sql` - SQL to execute
        `types` - SQL types of the parameters, as defined in the `java.sql.Types` class
        `resultType` - the type that the result object is required to match
      See Also:
        `setResultType(Class)`, `Types`

  - ### Method Detail

    - #### setResultType

          public void setResultType(Class<T> resultType)

      Specify the type that the result object is required to match.

      If not specified, the result value will be exposed as returned by the JDBC driver.

    - #### mapRow

          protected T mapRow(ResultSet rs,
                 int rowNum)
                      throws SQLException

      This implementation of this method extracts a single value from the single row returned by the function. If there are a different number of rows returned, this is treated as an error.
      Specified by:
        `mapRow` in class `MappingSqlQuery<T>`
      Parameters:
        `rs` - ResultSet we're working through
        `rowNum` - row number (from 0) we're up to
      Returns:
        an object of the result type
      Throws:
        `SQLException` - if there's an error extracting data. Subclasses can simply not catch SQLExceptions, relying on the framework to clean up.

    - #### run

          public int run()

      Convenient method to run the function without arguments.
      Returns:
        the value of the function

    - #### run

          public int run(int parameter)

      Convenient method to run the function with a single int argument.
      Parameters:
        `parameter` - single int parameter
      Returns:
        the value of the function

    - #### run

          public int run(Object... parameters)

      Analogous to the SqlQuery.execute([]) method. This is a generic method to execute a query, taken a number of arguments.
      Parameters:
        `parameters` - array of parameters. These will be objects or object wrapper types for primitives.
      Returns:
        the value of the function

    - #### runGeneric

          public Object runGeneric()

      Convenient method to run the function without arguments, returning the value as an object.
      Returns:
        the value of the function

    - #### runGeneric

          public Object runGeneric(int parameter)

      Convenient method to run the function with a single int argument.
      Parameters:
        `parameter` - single int parameter
      Returns:
        the value of the function as an Object

    - #### runGeneric

          public Object runGeneric(Object[] parameters)

      Analogous to the `SqlQuery.findObject(Object[])` method. This is a generic method to execute a query, taken a number of arguments.
      Parameters:
        `parameters` - array of parameters. These will be objects or object wrapper types for primitives.
      Returns:
        the value of the function, as an Object
      See Also:
        `SqlQuery.execute(Object[])`