Module org.firebirdsql.jaybird
Package org.firebirdsql.jdbc

# Interface FBFetcher

@InternalApi @NullMarked public sealed interface FBFetcher
Instances of this interface fetch records from the server.

This interface is internal API of Jaybird. Future versions may radically change, move, or make inaccessible this type.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_FETCH_ROWS`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `absolute(int row)`
  Move cursor to the absolute row.
  `void`
  `afterLast()`
  Move cursor after last record.
  `default void`
  `beforeExecuteInsert()`
  Signals to the fetcher that an insert is about to be executed.
  `void`
  `beforeFirst()`
  Move cursor before first record.
  `void`
  `close()`
  Close this fetcher and corresponding result set.
  `void`
  `close(CompletionReason completionReason)`
  Close this fetcher and corresponding result set.
  `int`
  `currentPosition()`
  The current position of the fetcher.
  `void`
  `deleteRow()`
  Delete row at current position.
  `boolean`
  `first()`
  Move cursor to the first row.
  `FetchConfig`
  `getFetchConfig()`
  `int`
  `getFetchDirection()`
  Retrieves the fetch direction for this fetcher object.
  `int`
  `getFetchSize()`
  Get the suggested number of rows to fetch with each batch fetch.
  `int`
  `getRowNum()`
  Get row number.
  `void`
  `insertRow(RowValue data)`
  Insert row at current position.
  `boolean`
  `isAfterLast()`
  `boolean`
  `isBeforeFirst()`
  `boolean`
  `isClosed()`
  `boolean`
  `isEmpty()`
  `boolean`
  `isFirst()`
  `boolean`
  `isLast()`
  `boolean`
  `last()`
  Move cursor to the last row.
  `boolean`
  `next()`
  Move to next row.
  `boolean`
  `previous()`
  Move cursor to the previous row.
  `boolean`
  `relative(int row)`
  Move cursor relative to the current row.
  `void`
  `renotifyCurrentRow()`
  Notifies the fetcher listener with the row data of the current row (or {`null` if not currently in a row).
  `default boolean`
  `rowDeleted()`
  Is the current row a deleted row (through the owning result set)?
  `default boolean`
  `rowInserted()`
  Is the current row a newly inserted row (through the owning result set)?
  `default boolean`
  `rowUpdated()`
  Is the current row an updated row (through the owning result set)?
  `void`
  `setFetchDirection(int direction)`
  Gives a hint as to the direction in which the rows in this fetcher object will be processed.
  `void`
  `setFetcherListener(FBObjectListener.FetcherListener fetcherListener)`
  Sets the fetcher listener.
  `void`
  `setFetchSize(int fetchSize)`
  Set the suggested number of rows to fetch with each batch fetch.
  `void`
  `setReadOnly()`
  Updates the result set behavior of this fetcher to readonly.
  `int`
  `size()`
  Total number of rows of this fetcher, taking the max rows into account if relevant.
  `void`
  `updateRow(RowValue data)`
  Update row at current position.

- ## Field Details

  - ### DEFAULT_FETCH_ROWS

    static final int DEFAULT_FETCH_ROWS
    See Also:
      - Constant Field Values

- ## Method Details

  - ### first

    boolean first() throws SQLException
    Move cursor to the first row.
    Returns:
      `true` if cursor was moved to the first row.
    Throws:
      `SQLException`

  - ### last

    boolean last() throws SQLException
    Move cursor to the last row.
    Returns:
      `true` if cursor was moved to the last row.
    Throws:
      `SQLException`

  - ### previous

    boolean previous() throws SQLException
    Move cursor to the previous row.
    Returns:
      `true` if cursor was moved to the previous row.
    Throws:
      `SQLException`

  - ### next

    boolean next() throws SQLException
    Move to next row.
    Returns:
      `true` if cursor was moved.
    Throws:
      `SQLException`

  - ### absolute

    boolean absolute(int row) throws SQLException
    Move cursor to the absolute row.
    Parameters:
      `row` - absolute row number.
    Returns:
      `true` if cursor was successfully moved.
    Throws:
      `SQLException`

  - ### relative

    boolean relative(int row) throws SQLException
    Move cursor relative to the current row.
    Parameters:
      `row` - relative row position.
    Returns:
      `true` if cursor was successfully moved.
    Throws:
      `SQLException`

  - ### beforeFirst

    void beforeFirst() throws SQLException
    Move cursor before first record.
    Throws:
      `SQLException`

  - ### afterLast

    void afterLast() throws SQLException
    Move cursor after last record.
    Throws:
      `SQLException`

  - ### close

    void close() throws SQLException
    Close this fetcher and corresponding result set.

    Equivalent to calling `close(CompletionReason)` with `CompletionReason.OTHER`.

    Throws:
      `SQLException`

  - ### close

    void close(CompletionReason completionReason) throws SQLException
    Close this fetcher and corresponding result set.
    Parameters:
      `completionReason` - Reason for completion
    Throws:
      `SQLException`

  - ### isClosed

    boolean isClosed()
    Returns:
      `true` if this fetcher is closed, otherwise `false`
    Since:
      6

  - ### getRowNum

    int getRowNum() throws SQLException
    Get row number.
    Returns:
      row number
    Throws:
      `SQLException`
    See Also:
      - `currentPosition()`

  - ### isEmpty

    boolean isEmpty() throws SQLException
    Returns:
      `true` if the result set is empty; otherwise `false`
    Throws:
      `SQLException`

  - ### isBeforeFirst

    boolean isBeforeFirst() throws SQLException
    Returns:
      `true` if positioned before the first row, contrary to `ResultSet.isBeforeFirst()` it also reports `true` if empty and next was not invoked
    Throws:
      `SQLException`
    See Also:
      - `ResultSet.isBeforeFirst()`

  - ### isFirst

    boolean isFirst() throws SQLException
    Throws:
      `SQLException`
    See Also:
      - `ResultSet.isFirst()`

  - ### isLast

    boolean isLast() throws SQLException
    Throws:
      `SQLException`
    See Also:
      - `ResultSet.isLast()`

  - ### isAfterLast

    boolean isAfterLast() throws SQLException
    Returns:
      `true` if positioned after the last row, contrary to `ResultSet.isBeforeFirst()` it also reports `true` if empty and next was invoked
    Throws:
      `SQLException`
    See Also:
      - `ResultSet.isAfterLast()`

  - ### beforeExecuteInsert

    default void beforeExecuteInsert() throws SQLException
    Signals to the fetcher that an insert is about to be executed.

    This method is primarily intended for a workaround with `FBServerScrollFetcher` if the insert is performed when the server-side cursor is not fully materialized by the server, as that could result in the server also including the inserted row, leading to duplicate reporting of the inserted row. In response to this method, the fetcher can trigger full materialization of the server-side cursor.

    The default implementation of this method does nothing.

    Throws:
      `SQLException` - for database access exceptions
    Since:
      5.0.6

  - ### insertRow

    void insertRow(RowValue data) throws SQLException
    Insert row at current position. This method adds a row at the current position in case of updatable result sets after successful execution of the `ResultSet.insertRow()` method.
    Parameters:
      `data` - row data
    Throws:
      `SQLException`

  - ### deleteRow

    void deleteRow() throws SQLException
    Delete row at current position. This method deletes a row at the current position in case of updatable result sets after successful execution of the `ResultSet.deleteRow()` method.
    Throws:
      `SQLException`

  - ### updateRow

    void updateRow(RowValue data) throws SQLException
    Update row at current position. This method updates a row at the current position in case of updatable result sets after successful execution of the `ResultSet.updateRow()` method.
    Parameters:
      `data` - row data
    Throws:
      `SQLException`

  - ### renotifyCurrentRow

    void renotifyCurrentRow() throws SQLException
    Notifies the fetcher listener with the row data of the current row (or {`null` if not currently in a row).
    Throws:
      `SQLException`

  - ### getFetchConfig

    FetchConfig getFetchConfig()
    Returns:
      current fetch config of this fetcher
    Since:
      6

  - ### setReadOnly

    void setReadOnly() throws SQLException
    Updates the result set behavior of this fetcher to readonly.
    Throws:
      `SQLException` - if called on a closed fetcher, or if this fetcher is explicitly used for updatable use cases
    Since:
      6

  - ### getFetchSize

    int getFetchSize() throws SQLException
    Get the suggested number of rows to fetch with each batch fetch.
    Returns:
      The number of rows to be fetched, or `0` for the default fetch size
    Throws:
      `SQLException`

  - ### setFetchSize

    void setFetchSize(int fetchSize) throws SQLException
    Set the suggested number of rows to fetch with each batch fetch.
    Parameters:
      `fetchSize` - The suggested number of rows to fetch, or `0` to use the default fetch size
    Throws:
      `SQLException` - if `fetchSize < 0`

  - ### getFetchDirection

    int getFetchDirection() throws SQLException
    Retrieves the fetch direction for this fetcher object.
    Returns:
      current fetch direction
    Throws:
      `SQLException`
    Since:
      6

  - ### setFetchDirection

    void setFetchDirection(int direction) throws SQLException
    Gives a hint as to the direction in which the rows in this fetcher object will be processed.

    NOTE: In practice, existing fetcher implementations only validate and store the value, and the value is effectively ignored.

    Parameters:
      `direction` - fetch direction; one of `ResultSet.FETCH_FORWARD`, `ResultSet.FETCH_REVERSE`, or `ResultSet.FETCH_UNKNOWN`
    Throws:
      `SQLException`
    Since:
      6

  - ### currentPosition

    int currentPosition() throws SQLException
    The current position of the fetcher.

    Contrary to `getRowNum()`, this should also report the after-last position.

    Returns:
      Position of the fetcher, with `0` for before-first, and `size + 1` for after-last.
    Throws:
      `SQLException`
    See Also:
      - `getRowNum()`

  - ### size

    int size() throws SQLException
    Total number of rows of this fetcher, taking the max rows into account if relevant.

    If the size of the fetcher is not known or not fixed, a `SQLException` should be thrown.

    Returns:
      size of fetcher
    Throws:
      `SQLException` - For exception retrieving the cursor size, or if it is not possible to determine the fetcher size

  - ### setFetcherListener

    void setFetcherListener(FBObjectListener.FetcherListener fetcherListener)
    Sets the fetcher listener.

    Any current fetcher is replaced with the provided fetcher listener.

    Parameters:
      `fetcherListener` - Fetcher listener

  - ### rowInserted

    default boolean rowInserted() throws SQLException
    Is the current row a newly inserted row (through the owning result set)?
    Returns:
      `true` if the row is newly inserted, `false` otherwise
    Throws:
      `SQLException`

  - ### rowDeleted

    default boolean rowDeleted() throws SQLException
    Is the current row a deleted row (through the owning result set)?
    Returns:
      `true` if the row is deleted, `false` otherwise
    Throws:
      `SQLException`

  - ### rowUpdated

    default boolean rowUpdated() throws SQLException
    Is the current row an updated row (through the owning result set)?
    Returns:
      `true` if the row is updated, `false` otherwise
    Throws:
      `SQLException`