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`