Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.ng.listeners

# Interface StatementListener

All Known Implementing Classes:
  `StatementListenerDispatcher`

public interface StatementListener
Listener interface for receiving rows and related information as retrieved by an `FbStatement.fetchRows(int)`, or `FbStatement.execute(RowValue)` with a singleton result.

All listener methods have a default implementation that does nothing.

Since:
  3.0
Author:
  Mark Rotteveel

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default void`
  `afterLast(FbStatement sender)`
  Method to be notified when the cursor of a statement is positioned after the last row.
  `default void`
  `beforeFirst(FbStatement sender)`
  Method to be notified when the cursor of a statement is positioned before the first row.
  `default void`
  `fetchComplete(FbStatement sender, FetchDirection fetchDirection, int rows)`
  Method to be notified of the number of rows fetched in a single `FbStatement.fetchRows(int)`.
  `default void`
  `receivedRow(FbStatement sender, RowValue rowValue)`
  Method to be notified of a new row of data.
  `default void`
  `sqlCounts(FbStatement sender, SqlCountHolder sqlCounts)`
  Called when the SQL counts of a statement have been retrieved.
  `default void`
  `statementExecuted(FbStatement sender, boolean hasResultSet, boolean hasSingletonResult)`
  Method to be notified when a statement has been executed.
  `default void`
  `statementStateChanged(FbStatement sender, StatementState newState, StatementState previousState)`
  Method to be notified when the state of a statement has changed.
  `default void`
  `warningReceived(FbStatement sender, SQLWarning warning)`
  Called when a warning was received for the `sender` statement.

- ## Method Details

  - ### receivedRow

    default void receivedRow(FbStatement sender, RowValue rowValue)
    Method to be notified of a new row of data.

    Listeners that process `beforeFirst(FbStatement)` and/or `afterLast(FbStatement)` should consider calls to this method to clear the before-first or after-last state to an

  - in-cursor
  state.

Parameters:
  `sender` - the `FbStatement` that called this method
  `rowValue` - The row values.

- ### fetchComplete

  default void fetchComplete(FbStatement sender, FetchDirection fetchDirection, int rows)
  Method to be notified of the number of rows fetched in a single `FbStatement.fetchRows(int)`.

  This method will not be called for singleton results of statements like `EXECUTE PROCEDURE`.

  When end of cursor is reached, it is undefined whether this method will be called first or `afterLast/beforeFirst`. Listeners must be prepared to handle either order.

  Parameters:
    `sender` - the `FbStatement` that called this method
    `fetchDirection` - fetch direction of the completed fetch operation
    `rows` - number of rows fetched in the completed fetch operation (NOTE: for native implementations, this will always be `1` or `0` for end of cursor)
  Since:
    6

- ### beforeFirst

  default void beforeFirst(FbStatement sender)
  Method to be notified when the cursor of a statement is positioned before the first row.

  When server-side scrolling is used, this method can be called multiple times during the lifetime of a single open cursor. This method may be called even if the cursor is already before-first.

  Parameters:
    `sender` - the `FbStatement` that called this method
  Since:
    5
  See Also:
    - `statementExecuted(FbStatement, boolean, boolean)`
    - `receivedRow(FbStatement, RowValue)`
    - `afterLast(FbStatement)`

- ### afterLast

  default void afterLast(FbStatement sender)
  Method to be notified when the cursor of a statement is positioned after the last row.

  When server-side scrolling is used, this method might be called multiple times during the lifetime of a single open cursor. This method may be called even if the cursor is already after-last.

  Parameters:
    `sender` - the `FbStatement` that called this method
  Since:
    5
  See Also:
    - `statementExecuted(FbStatement, boolean, boolean)`
    - `receivedRow(FbStatement, RowValue)`
    - `beforeFirst(FbStatement)`

- ### statementExecuted

  default void statementExecuted(FbStatement sender, boolean hasResultSet, boolean hasSingletonResult)
  Method to be notified when a statement has been executed.

  This event with `hasResultSet=true` can be seen as a counterpart of `afterLast(FbStatement)`.

  Parameters:
    `sender` - the `FbStatement` that called this method
    `hasResultSet` - `true` there is a result set, `false` there is no result set
    `hasSingletonResult` - `true` singleton result, `false` statement will produce indeterminate number of rows; can be ignored when `hasResultSet` is `false`

- ### statementStateChanged

  default void statementStateChanged(FbStatement sender, StatementState newState, StatementState previousState)
  Method to be notified when the state of a statement has changed.
  Parameters:
    `sender` - the `FbStatement` that called this method
    `newState` - new state of the statement
    `previousState` - old state of the statement

- ### warningReceived

  default void warningReceived(FbStatement sender, SQLWarning warning)
  Called when a warning was received for the `sender` statement.
  Parameters:
    `sender` - Statement receiving the warning
    `warning` - Warning

- ### sqlCounts

  default void sqlCounts(FbStatement sender, SqlCountHolder sqlCounts)
  Called when the SQL counts of a statement have been retrieved.
  Parameters:
    `sender` - Statement that called this method
    `sqlCounts` - SQL counts