Package org.postgresql.core

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.

  • Method Details

    • handleResultRows

      void handleResultRows(Query fromQuery, Field[] fields, List<Tuple> tuples, @Nullable 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(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(SQLWarning warning)
      Called when a warning is emitted.
      Parameters:
      warning - the warning that occurred.

    • handleError

      void handleError(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 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:
      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

      @Nullable SQLException getException()
      Returns the first encountered exception. The rest are chained via SQLException.setNextException(SQLException)
      Returns:
      the first encountered exception

    • getWarning

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