org.soulwing.jdbc

Interface JdbcCall

All Superinterfaces:

AutoCloseable

public interface JdbcCall
extends AutoCloseable

A SQL call operation.

The execute(Parameter...) method be invoked repeatedly with different parameter values. When the call operation is no longer needed, it must be closed by either calling the close() method or by nesting it within a try-with-resources construct.

The call operation supports stored procedures that return values through any combination of

• zero or more implicitly returned ResultSet objects,
• an optional update count, and
• zero or more parameters configured for OUT or INOUT semantics.

While this API supports all of the possible return value mechanisms that are inherent with JDBC, the actual support provided for stored procedures varies greatly between JDBC vendors, with each vendor choosing which mechanisms to support. It is important to understand the capabilities of the specific JDBC vendor in order to effectively use this API.

For maximum portability, on return from execute(org.soulwing.jdbc.Parameter...) the caller should first process all results sets and update counts, before retrieving the values of registered OUT/INOUT parameters.

Author:

Carl Harris

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes the JDBC resources associated with this call operation.
boolean	execute(Parameter... parameters) Executes this call operation.
boolean	getMoreResults() Gets a flag indicating the next result type available.
<T> T	getOutParameter(int parameterIndex, Class<T> type) Gets the value of an OUT or INOUT parameter.
<T> T	getOutParameter(String parameterName, Class<T> type) Gets the value of an OUT or INOUT parameter.
ResultSet	getResultSet() Gets the current result set.
int	getUpdateCount() Gets the number of rows inserted/updated.
<T> T	handleResult(ResultSetHandler<T> handler) Processes the current result set using the given handler.
<T> List<T>	retrieveList(int columnIndex, Class<T> type) Retrieves all values of a given column in the current result set.
<T> List<T>	retrieveList(RowMapper<T> rowMapper) Retrieves and maps all rows in the current result set using the given row mapper.
<T> List<T>	retrieveList(String columnLabel, Class<T> type) Retrieves all values of a given column in the current result set.
<T> T	retrieveValue(int columnIndex, Class<T> type) Retrieves a column value from the current result set, which must contain a exactly one row.
<T> T	retrieveValue(RowMapper<T> rowMapper) Retrieves and maps a single row in current result set, which must contain exactly one row.
<T> T	retrieveValue(String columnLabel, Class<T> type) Retrieves a column value from the current result set, which must contain a exactly one row.

Method Detail

execute

boolean execute(Parameter... parameters)

Executes this call operation.

Parameters:

parameters - values for placeholders in the statement; may be any combination of IN, OUT, or INOUT parameters supported by the target called procedure

Returns:

true if the first result is a ResultSet, false if it is an update count or there are no results

close

void close()

Closes the JDBC resources associated with this call operation.

After a call operation is closed, its execute method may not be subsequently invoked.

Specified by:

close in interface AutoCloseable

getUpdateCount

int getUpdateCount()

Gets the number of rows inserted/updated.

Returns:

update count or -1 if no update count is available

See Also:

java.sql.Statement#getUpdateCount()}

getMoreResults

boolean getMoreResults()

Gets a flag indicating the next result type available.

Invoking this method implicitly closes the last ResultSet returned from the getResultSet() method.

Returns:

true if the next result is a ResultSet, false if it is an update count or there are no more results

See Also:

java.sql.Statement#getMoreResults()}

getResultSet

ResultSet getResultSet()

Gets the current result set.

Returns:

result set or null if the current result is not a result set

See Also:

java.sql.Statement#getResultSet()}

getOutParameter

<T> T getOutParameter(int parameterIndex,
                    Class<T> type)

Gets the value of an OUT or INOUT parameter.

Parameters:

parameterIndex - index of the parameter (starts at 1)

type - data type

Returns:

parameter value

getOutParameter

<T> T getOutParameter(String parameterName,
                    Class<T> type)

Gets the value of an OUT or INOUT parameter.

Parameters:

parameterName - name of the parameter

type - data type

Returns:

parameter value

handleResult

<T> T handleResult(ResultSetHandler<T> handler)

Processes the current result set using the given handler.

Parameters:

handler - the subject handler

Returns:

object produced by handler

retrieveList

<T> List<T> retrieveList(String columnLabel,
                       Class<T> type)

Retrieves all values of a given column in the current result set.

Parameters:

columnLabel - column label (name)

Returns:

list of values for the specified column

retrieveList

<T> List<T> retrieveList(int columnIndex,
                       Class<T> type)

Retrieves all values of a given column in the current result set.

Parameters:

columnIndex - column index (starts at 1)

Returns:

list of values for the specified column

retrieveList

<T> List<T> retrieveList(RowMapper<T> rowMapper)

Retrieves and maps all rows in the current result set using the given row mapper.

Parameters:

rowMapper - the subject row mapper

Returns:

list of objects produced by RowMapper

retrieveValue

<T> T retrieveValue(String columnLabel,
                  Class<T> type)

Retrieves a column value from the current result set, which must contain a exactly one row.

Parameters:

columnLabel - column label (name)

Returns:

value of the specified column

Throws:

SQLNoResultException - if the result contains no rows

SQLNonUniqueResultException - if the result contains more than one row

retrieveValue

<T> T retrieveValue(int columnIndex,
                  Class<T> type)

Retrieves a column value from the current result set, which must contain a exactly one row.

Parameters:

columnIndex - column index (starts at 1)

Returns:

value of the specified column

Throws:

SQLNoResultException - if the result contains no rows

SQLNonUniqueResultException - if the result contains more than one row

retrieveValue

<T> T retrieveValue(RowMapper<T> rowMapper)

Retrieves and maps a single row in current result set, which must contain exactly one row.

Parameters:

rowMapper - the subject row mapper

Returns:

object produced by RowMapper for the row