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 Summary

Modifier and Type
Method
Description
`@Nullable SQLException`
`getException()`
Returns the first encountered exception.
`@Nullable SQLWarning`
`getWarning()`
Returns the first encountered warning.
`void`
`handleCommandStatus(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(SQLException error)`
Called when an error occurs.
`void`
`handleResultRows(Query fromQuery, Field[] fields, List<Tuple> tuples, @Nullable ResultCursor cursor)`
Called when result rows are received from a query.
`void`
`handleWarning(SQLWarning warning)`
Called when a warning is emitted.
`void`
`secureProgress()`
Callback for batch statements.

## 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