Top Description Methods
org.postgresql.core

public Interface ResultHandler

Known Direct Implementers
org.postgresql.core.ResultHandlerBase, org.postgresql.core.ResultHandlerDelegate
Imports
org.checkerframework.checker.nullness.qual.Nullable, java.sql.SQLException, .SQLWarning, java.util.List

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 ([email protected])

Method Summary

Modifier and TypeMethod and Description
public @Nullable SQLException

Returns:

the first encountered exception
getException()

Returns the first encountered exception.

public @Nullable SQLWarning

Returns:

the first encountered warning
getWarning()

Returns the first encountered warning.

public void
handleCommandStatus(String
the command status string (e.g. "SELECT") returned by the backend
status, long
the number of rows affected by an INSERT, UPDATE, DELETE, FETCH, or MOVE command; -1 if not available.
updateCount, long
for a single-row INSERT query, the OID of the newly inserted row; 0 if not available.
insertOID)

Called when a query that did not return a resultset completes.

public void
handleCompletion()

Called before a QueryExecutor method returns.

public void
handleError(SQLException
the error that occurred
error)

Called when an error occurs.

public void
handleResultRows(Query
the underlying query that generated these results; this may not be very specific (e.g. it may be a query that includes multiple statements).
fromQuery, Field[]
column metadata for the resultset; might be null if Query.QUERY_NO_METADATA was specified.
fields, List<Tuple>
the actual data
tuples, @Nullable ResultCursor
a cursor to use to fetch additional data; null if no further results are present.
cursor)

Called when result rows are received from a query.

public void
handleWarning(SQLWarning
the warning that occurred.
warning)

Called when a warning is emitted.

public void
secureProgress()

Callback for batch statements.

Method Detail

getExceptionback to summary
public @Nullable SQLException getException()

Returns the first encountered exception. The rest are chained via SQLException#setNextException(SQLException)

Returns:@Nullable SQLException

the first encountered exception

getWarningback to summary
public @Nullable SQLWarning getWarning()

Returns the first encountered warning. The rest are chained via SQLException#setNextException(SQLException)

Returns:@Nullable SQLWarning

the first encountered warning

handleCommandStatusback to summary
public void handleCommandStatus(String status, long updateCount, long insertOID)

Called when a query that did not return a resultset completes.

Parameters
status:String

the command status string (e.g. "SELECT") returned by the backend

updateCount:long

the number of rows affected by an INSERT, UPDATE, DELETE, FETCH, or MOVE command; -1 if not available.

insertOID:long

for a single-row INSERT query, the OID of the newly inserted row; 0 if not available.

handleCompletionback to summary
public 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.

Exceptions
SQLException:
if the handler wishes the original method to throw an exception.
handleErrorback to summary
public 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:SQLException

the error that occurred

handleResultRowsback to summary
public void handleResultRows(Query fromQuery, Field[] fields, List<Tuple> tuples, @Nullable ResultCursor cursor)

Called when result rows are received from a query.

Parameters
fromQuery:Query

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:Field[]

column metadata for the resultset; might be null if Query.QUERY_NO_METADATA was specified.

tuples:List<Tuple>

the actual data

cursor:@Nullable ResultCursor

a cursor to use to fetch additional data; null if no further results are present.

handleWarningback to summary
public void handleWarning(SQLWarning warning)

Called when a warning is emitted.

Parameters
warning:SQLWarning

the warning that occurred.

secureProgressback to summary
public 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.