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

# Interface FirebirdStatement

All Superinterfaces:
  `AutoCloseable`, `Statement`, `Wrapper`

All Known Subinterfaces:
  `FirebirdCallableStatement`, `FirebirdPreparedStatement`

All Known Implementing Classes:
  `AbstractStatement`, `FBCallableStatement`, `FBPreparedStatement`, `FBStatement`

@NullMarked public interface FirebirdStatement extends Statement
Firebird-specific extensions to the `Statement` interface.

Author:
  Roman Rokytskyy

- ## Field Summary

  ### Fields inherited from interface java.sql.Statement

  `CLOSE_ALL_RESULTS, CLOSE_CURRENT_RESULT, EXECUTE_FAILED, KEEP_CURRENT_RESULT, NO_GENERATED_KEYS, RETURN_GENERATED_KEYS, SUCCESS_NO_INFO`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `@Nullable ResultSet`
  `getCurrentResultSet()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `Statement.getResultSet()` instead, will be removed in Jaybird 7
  `int`
  `getDeletedRowsCount()`
  Get number of deleted rows.
  `@Nullable String`
  `getExecutionPlan()`
  Gets the simple execution plan of the statement.
  `@Nullable String`
  `getExplainedExecutionPlan()`
  Gets the explained (or detailed) execution plan of the statement.
  `int`
  `getInsertedRowsCount()`
  Get number of inserted rows.
  `default @Nullable String`
  `getLastExecutionPlan()`
  Deprecated.
  use `getExecutionPlan()`; there are currently no plans to remove this method
  `default @Nullable String`
  `getLastExplainedExecutionPlan()`
  Deprecated.
  use `getExplainedExecutionPlan()`; there are currently no plans to remove this method
  `int`
  `getLocalStatementId()`
  The local statement id is intended to identify the statement for internal implementation purposes.
  `int`
  `getUpdatedRowsCount()`
  Get number of updated rows.
  `boolean`
  `hasOpenResultSet()`
  Check if this statement has open result set.
  `boolean`
  `isValid()`
  Check if this statement is valid.

  ### Methods inherited from interface java.sql.Statement

  `addBatch, cancel, clearBatch, clearWarnings, close, closeOnCompletion, enquoteIdentifier, enquoteLiteral, enquoteNCharLiteral, execute, execute, execute, execute, executeBatch, executeLargeBatch, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeQuery, executeUpdate, executeUpdate, executeUpdate, executeUpdate, getConnection, getFetchDirection, getFetchSize, getGeneratedKeys, getLargeMaxRows, getLargeUpdateCount, getMaxFieldSize, getMaxRows, getMoreResults, getMoreResults, getQueryTimeout, getResultSet, getResultSetConcurrency, getResultSetHoldability, getResultSetType, getUpdateCount, getWarnings, isClosed, isCloseOnCompletion, isPoolable, isSimpleIdentifier, setCursorName, setEscapeProcessing, setFetchDirection, setFetchSize, setLargeMaxRows, setMaxFieldSize, setMaxRows, setPoolable, setQueryTimeout`

  ### Methods inherited from interface java.sql.Wrapper

  `isWrapperFor, unwrap`

- ## Method Details

  - ### getInsertedRowsCount

    int getInsertedRowsCount() throws SQLException
    Get number of inserted rows. You can call this method multiple times, it does not affect the JDBC result number.
    Returns:
      number of inserted rows or -1 if current result is result set.
    Throws:
      `SQLException` - if database error occurs.

  - ### getUpdatedRowsCount

    int getUpdatedRowsCount() throws SQLException
    Get number of updated rows. You can call this method multiple times, it does not affect the JDBC result number.
    Returns:
      number of updated rows or -1 if current result is result set.
    Throws:
      `SQLException` - if database error occurs.

  - ### getDeletedRowsCount

    int getDeletedRowsCount() throws SQLException
    Get number of deleted rows. You can call this method multiple times, it does not affect the JDBC result number.
    Returns:
      number of deleted rows or -1 if current result is result set.
    Throws:
      `SQLException` - if database error occurs.

  - ### hasOpenResultSet

    boolean hasOpenResultSet()
    Check if this statement has open result set. Note, this method works correctly if auto-commit is disabled. In auto-commit mode it will always return `false` because from the statement's point of view result set is not open (in auto-commit mode complete result set is fetched and cached in wrapping object before returning from the `Statement.getResultSet()` method).
    Returns:
      `true` if there's already open result set associated with this statement, otherwise `false`.

  - ### getCurrentResultSet

    @Deprecated(since="6", forRemoval=true) @Nullable ResultSet getCurrentResultSet() throws SQLException
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `Statement.getResultSet()` instead, will be removed in Jaybird 7
    Get current result set. Behaviour of this method is similar to the behavior of the `Statement.getResultSet()`.
    Returns:
      instance of `ResultSet` representing current result set or `null` if it is not available.
    Throws:
      `SQLException` - if a database access error happens

  - ### isValid

    boolean isValid()
    Check if this statement is valid.
    Returns:
      `true` if statement is valid and can be used to execute SQL.

  - ### getLastExecutionPlan

    @Deprecated(since="6", forRemoval=false) default @Nullable String getLastExecutionPlan() throws SQLException
    Deprecated.
    use `getExecutionPlan()`; there are currently no plans to remove this method
    Alias for `getExecutionPlan()`.
    Throws:
      `SQLException`

  - ### getExecutionPlan

    @Nullable String getExecutionPlan() throws SQLException
    Gets the simple execution plan of the statement.

    Behaviour depends on the specific type:

    - `Statement` but not `PreparedStatement` — returns the plan of the last executed statement
    - `PreparedStatement` — returns the plan of the prepared statement
    - `CallableStatement` — is not guaranteed to return the plan until after the first execution
    Returns:
      execution plan returned by the server
    Throws:
      `SQLException` - if no statement was executed or prepared before calling this method, if the statement is not valid or open, or there was an error when obtaining the execution plan
    Since:
      6
    See Also:
      - `getExplainedExecutionPlan()`

  - ### getLastExplainedExecutionPlan

    @Deprecated(since="6", forRemoval=false) default @Nullable String getLastExplainedExecutionPlan() throws SQLException
    Deprecated.
    use `getExplainedExecutionPlan()`; there are currently no plans to remove this method
    Alias for `getExplainedExecutionPlan()`.
    Throws:
      `SQLException`
    See Also:
      - `getExplainedExecutionPlan()`

  - ### getExplainedExecutionPlan

    @Nullable String getExplainedExecutionPlan() throws SQLException
    Gets the explained (or detailed) execution plan of the statement.

    The explained execution plan is a more structured and comprehensible form compared to the (simple) execution plan returned by `getExecutionPlan()`. This requires Firebird 3.0 or higher.

    Behaviour depends on the specific type:

    - `Statement` but not `PreparedStatement` — returns the plan of the last executed statement
    - `PreparedStatement` — returns the plan of the prepared statement
    - `CallableStatement` — is not guaranteed to return the plan until after the first execution
    Returns:
      execution plan returned by the server
    Throws:
      `SQLException` - if no statement was executed or prepared before calling this method, if the statement is not valid or open, or there was an error when obtaining the execution plan
    Since:
      6
    See Also:
      - `getExecutionPlan()`

  - ### getLocalStatementId

    @InternalApi int getLocalStatementId()
    The local statement id is intended to identify the statement for internal implementation purposes.

    NOTE: This method is only included in this interface to try and avoid problems with proxied and bytecode enhanced classes in certain libraries, you should normally have no reason to call this method directly.

    The id is expected - but not guaranteed - to be unique for a single connection, and - preferably - for the entire JVM run time as well.

    Returns:
      The local statement id.