Package 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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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​(String columnLabel, 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> 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​(String columnLabel, 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.

    • 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

      • 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

      • getResultSet

        ResultSet getResultSet()
        Gets the current result set.
        Returns:
        result set or null if the current result is not a result set

      • 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