Class SqlStatement


  • public class SqlStatement
    extends java.lang.Object
    SqlStatement contains a SQL statement and associated resources throughout its lifetime.

    The goal of SqlStatement is to make tracing, error-handling and resource-management easier. None of the methods throws a SQLException; if an error occurs in one of the methods, the method wraps the exception in a RuntimeException describing the high-level operation, logs that the operation failed, and throws that RuntimeException.

    If methods succeed, the method generates lifecycle logging such as the elapsed time and number of rows fetched.

    There are a few obligations on the caller. The caller must:

    • call the handle(Throwable) method if one of the contained objects (say the ResultSet) gives an error;
    • call the close() method if all operations complete successfully.
    • increment the rowCount field each time a row is fetched.

    The close() method is idempotent. You are welcome to call it more than once.

    SqlStatement is not thread-safe.

    Since:
    2.3
    Author:
    jhyde
    • Field Summary

      Fields 
      Modifier and Type Field Description
      int rowCount  
    • Constructor Summary

      Constructors 
      Constructor Description
      SqlStatement​(javax.sql.DataSource dataSource, java.lang.String sql, java.util.List<SqlStatement.Type> types, int maxRows, int firstRowOrdinal, Locus locus, int resultSetType, int resultSetConcurrency, Util.Functor1<java.lang.Void,​java.sql.Statement> callback)
      Creates a SqlStatement.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Closes all resources (statement, result set) held by this SqlStatement.
      void execute()
      Executes the current statement, and handles any SQLException.
      (package private) java.lang.String formatTimingStatus​(long totalMs, int rowCount)  
      java.util.List<SqlStatement.Accessor> getAccessors()  
      java.sql.ResultSet getResultSet()  
      java.sql.ResultSet getWrappedResultSet()
      Returns the result set in a proxy which automatically closes this SqlStatement (and hence also the statement and result set) when the result set is closed.
      java.util.List<SqlStatement.Type> guessTypes()  
      java.lang.RuntimeException handle​(java.lang.Throwable e)
      Handles an exception thrown from the ResultSet, implicitly calls close(), and returns an exception which includes the full stack, including a description of the high-level operation.
      • Methods inherited from class java.lang.Object

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

      • rowCount

        public int rowCount
    • Constructor Detail

      • SqlStatement

        public SqlStatement​(javax.sql.DataSource dataSource,
                            java.lang.String sql,
                            java.util.List<SqlStatement.Type> types,
                            int maxRows,
                            int firstRowOrdinal,
                            Locus locus,
                            int resultSetType,
                            int resultSetConcurrency,
                            Util.Functor1<java.lang.Void,​java.sql.Statement> callback)
        Creates a SqlStatement.
        Parameters:
        dataSource - Data source
        sql - SQL
        types - Suggested types of columns, or null; if present, must have one element for each SQL column; each not-null entry overrides deduced JDBC type of the column
        maxRows - Maximum rows; <= 0 means no maximum
        firstRowOrdinal - Ordinal of first row to skip to; <= 0 do not skip
        locus - Execution context of this statement
        resultSetType - Result set type
        resultSetConcurrency - Result set concurrency
    • Method Detail

      • execute

        public void execute()
        Executes the current statement, and handles any SQLException.
      • close

        public void close()
        Closes all resources (statement, result set) held by this SqlStatement.

        If any of them fails, wraps them in a RuntimeException describing the high-level operation which this statement was performing. No further error-handling is required to produce a descriptive stack trace, unless you want to absorb the error.

        This method is idempotent.

      • formatTimingStatus

        java.lang.String formatTimingStatus​(long totalMs,
                                            int rowCount)
      • getResultSet

        public java.sql.ResultSet getResultSet()
      • handle

        public java.lang.RuntimeException handle​(java.lang.Throwable e)
        Handles an exception thrown from the ResultSet, implicitly calls close(), and returns an exception which includes the full stack, including a description of the high-level operation.
        Parameters:
        e - Exception
        Returns:
        Runtime exception
      • guessTypes

        public java.util.List<SqlStatement.Type> guessTypes()
                                                     throws java.sql.SQLException
        Throws:
        java.sql.SQLException
      • getAccessors

        public java.util.List<SqlStatement.Accessor> getAccessors()
                                                           throws java.sql.SQLException
        Throws:
        java.sql.SQLException
      • getWrappedResultSet

        public java.sql.ResultSet getWrappedResultSet()
        Returns the result set in a proxy which automatically closes this SqlStatement (and hence also the statement and result set) when the result set is closed.

        This helps to prevent connection leaks. The caller still has to remember to call ResultSet.close(), of course.

        Returns:
        Wrapped result set