Interface ResultHandler

  • All Known Implementing Classes:
    BatchResultHandler, PgResultSet.CursorResultHandler, PgStatement.StatementResultHandler, ResultHandlerBase, ResultHandlerDelegate

    public interface ResultHandler

    Callback interface for passing query results from the protocol-specific layer to the protocol-independent JDBC implementation code.

    In general, a single query execution will consist of a number of calls to handleResultRows, handleCommandStatus, handleWarning, and handleError, followed by a single call to handleCompletion when query execution is complete. If the caller wants to throw SQLException, this can be done in handleCompletion.

    Each executed query ends with a call to handleResultRows, handleCommandStatus, or handleError. If an error occurs, subsequent queries won't generate callbacks.

    Author:
    Oliver Jowett (oliver@opencloud.com)
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.sql.SQLException getException()
      Returns the first encountered exception.
      java.sql.SQLWarning getWarning()
      Returns the first encountered warning.
      void handleCommandStatus​(java.lang.String status, long updateCount, long insertOID)
      Called when a query that did not return a resultset completes.
      void handleCompletion()
      Called before a QueryExecutor method returns.
      void handleError​(java.sql.SQLException error)
      Called when an error occurs.
      void handleResultRows​(Query fromQuery, Field[] fields, java.util.List<Tuple> tuples, ResultCursor cursor)
      Called when result rows are received from a query.
      void handleWarning​(java.sql.SQLWarning warning)
      Called when a warning is emitted.
      void secureProgress()
      Callback for batch statements.
    • Method Detail

      • handleResultRows

        void handleResultRows​(Query fromQuery,
                              Field[] fields,
                              java.util.List<Tuple> tuples,
                              ResultCursor cursor)
        Called when result rows are received from a query.
        Parameters:
        fromQuery - the underlying query that generated these results; this may not be very specific (e.g. it may be a query that includes multiple statements).
        fields - column metadata for the resultset; might be null if Query.QUERY_NO_METADATA was specified.
        tuples - the actual data
        cursor - a cursor to use to fetch additional data; null if no further results are present.
      • handleCommandStatus

        void handleCommandStatus​(java.lang.String status,
                                 long updateCount,
                                 long insertOID)
        Called when a query that did not return a resultset completes.
        Parameters:
        status - the command status string (e.g. "SELECT") returned by the backend
        updateCount - the number of rows affected by an INSERT, UPDATE, DELETE, FETCH, or MOVE command; -1 if not available.
        insertOID - for a single-row INSERT query, the OID of the newly inserted row; 0 if not available.
      • handleWarning

        void handleWarning​(java.sql.SQLWarning warning)
        Called when a warning is emitted.
        Parameters:
        warning - the warning that occurred.
      • handleError

        void handleError​(java.sql.SQLException error)
        Called when an error occurs. Subsequent queries are abandoned; in general the only calls between a handleError call and a subsequent handleCompletion call are handleError or handleWarning.
        Parameters:
        error - the error that occurred
      • handleCompletion

        void handleCompletion()
                       throws java.sql.SQLException
        Called before a QueryExecutor method returns. This method may throw a SQLException if desired; if it does, the QueryExecutor method will propagate that exception to the original caller.
        Throws:
        java.sql.SQLException - if the handler wishes the original method to throw an exception.
      • secureProgress

        void secureProgress()
        Callback for batch statements. In case batch statement is executed in autocommit==true mode, the executor might commit "as it this it is best", so the result handler should track which statements are executed successfully and which are not.
      • getException

        java.sql.SQLException getException()
        Returns the first encountered exception. The rest are chained via SQLException.setNextException(SQLException)
        Returns:
        the first encountered exception
      • getWarning

        java.sql.SQLWarning getWarning()
        Returns the first encountered warning. The rest are chained via SQLException.setNextException(SQLException)
        Returns:
        the first encountered warning