org.springframework.jdbc.object
Class SqlFunction

java.lang.Object
  org.springframework.jdbc.object.RdbmsOperation
      org.springframework.jdbc.object.SqlOperation
          org.springframework.jdbc.object.SqlQuery
              org.springframework.jdbc.object.MappingSqlQueryWithParameters
                  org.springframework.jdbc.object.MappingSqlQuery
                      org.springframework.jdbc.object.SqlFunction

All Implemented Interfaces:

InitializingBean

public class SqlFunction

extends MappingSqlQuery

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 methods 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 normally 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.

Like all RdbmsOperation objects, SqlFunction objects are threadsafe.

Author:

Rod Johnson, Isabelle Muszynski, Jean-Pierre Pawlak

See Also:

StoredProcedure

Nested Class Summary

Nested classes inherited from class org.springframework.jdbc.object.MappingSqlQueryWithParameters

MappingSqlQueryWithParameters.ResultReaderImpl

Field Summary

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

logger

Constructor Summary

SqlFunction()
Constructor to allow use as a JavaBean.

SqlFunction(javax.sql.DataSource ds, java.lang.String sql)
Create a new SQLFunction object with SQL, but without parameters.

SqlFunction(javax.sql.DataSource ds, java.lang.String sql, int retType)
Create a new SQLFunction object with SQL and return type, but without parameters.

SqlFunction(javax.sql.DataSource ds, java.lang.String sql, int[] types)
Create a new SQLFunction object with SQL and parameters.

SqlFunction(javax.sql.DataSource ds, java.lang.String sql, int[] types, int retType)
Create a new SQLFunction object with SQL, parameters and a return type

Method Summary

protected java.lang.Object	mapRow(java.sql.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 p) Convenient method to run the function with a single int argument.
int	run(java.lang.Object[] args) Analogous to the SqlQuery.execute([]) method.
java.lang.Object	runGeneric() Convenient method to run the function without arguments, returning the value as an object
java.lang.Object	runGeneric(int p) Convenient method to run the function with a single int argument.
java.lang.Object	runGeneric(java.lang.Object[] args) Analogous to the SqlQuery.execute([]) method.

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

mapRow

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

newResultReader

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

execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, findObject, findObject, findObject, findObject, findObject, findObject, findObject, findObject, findObject, findObject, getRowsExpected, onCompileInternal, setRowsExpected

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

compileInternal, getResultSetType, isUpdatableResults, newPreparedStatementCreator, setResultSetType, setUpdatableResults

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

afterPropertiesSet, compile, declareParameter, getDeclaredParameters, getJdbcTemplate, getSql, isCompiled, setDataSource, setJdbcTemplate, setSql, setTypes, 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.

SqlFunction

public SqlFunction(javax.sql.DataSource ds,
                   java.lang.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

SqlFunction

public SqlFunction(javax.sql.DataSource ds,
                   java.lang.String sql,
                   int[] types,
                   int retType)
            throws InvalidDataAccessApiUsageException

Create a new SQLFunction object with SQL, parameters and a return 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

retType - SQL type of the return value, as defined in the java.sql.Types class

Throws:

InvalidDataAccessApiUsageException - is thrown if the return type is not numeric or char

SqlFunction

public SqlFunction(javax.sql.DataSource ds,
                   java.lang.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(javax.sql.DataSource ds,
                   java.lang.String sql,
                   int retType)

Create a new SQLFunction object with SQL and return type, but without parameters. Must add parameters or settle with none.

Parameters:

ds - DataSource to obtain connections from

sql - SQL to execute

retType - SQL type of the return value, as defined in the java.sql.Types class

Method Detail

mapRow

protected java.lang.Object mapRow(java.sql.ResultSet rs,
                                  int rowNum)
                           throws java.sql.SQLException,
                                  InvalidDataAccessApiUsageException

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

Parameters:

rs - ResultSet we're working through

rowNum - row number (from 0) we're up to

Returns:

an object of the result type

Throws:

java.sql.SQLException - if there's an error extracting data. Subclasses can simply fail to catch SQLExceptions.

InvalidDataAccessApiUsageException

run

public int run()

Convenient method to run the function without arguments.

Returns:

the value of the function

run

public int run(int p)

Convenient method to run the function with a single int argument.

Parameters:

p - single int argument

Returns:

the value of the function

run

public int run(java.lang.Object[] args)

Analogous to the SqlQuery.execute([]) method. This is a generic method to execute a query, taken a number of arguments.

Parameters:

args - array of arguments. These will be objects or object wrapper types for primitives.

Returns:

the value of the function

runGeneric

public java.lang.Object runGeneric()

Convenient method to run the function without arguments, returning the value as an object

Returns:

the value of the function

runGeneric

public java.lang.Object runGeneric(int p)

Convenient method to run the function with a single int argument.

Parameters:

p - single int argument

Returns:

the value of the function as an Object

runGeneric

public java.lang.Object runGeneric(java.lang.Object[] args)

Analogous to the SqlQuery.execute([]) method. This is a generic method to execute a query, taken a number of arguments.

Parameters:

args - array of arguments. These will be objects or object wrapper types for primitives.

Returns:

the value of the function, as an Object