org.firebirdsql.gds.ng

## Interface FbStatement

- All Superinterfaces:
    ExceptionListenable
  All Known Subinterfaces:
    FbWireStatement
  All Known Implementing Classes:
    AbstractFbStatement, AbstractFbWireStatement, JnaStatement, V10Statement, V11Statement, V12Statement, V13Statement

      public interface FbStatement
      extends ExceptionListenable

  API for statement handles.

  All methods defined in this interface are required to notify all `SQLException` thrown from the methods defined in this interface.

  Since:
    3.0
  Author:
    Mark Rotteveel

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addStatementListener(StatementListener statementListener)` Registers a `StatementListener`.
    `void` | `close()` Close and deallocate this statement.
    `void` | `closeCursor()` Closes the cursor associated with this statement, leaving the statement itself allocated.
    `void` | `closeCursor(boolean transactionEnd)` Closes the cursor associated with this statement, leaving the statement itself allocated.
    `RowDescriptor` | `emptyRowDescriptor()`
    `void` | `ensureClosedCursor(boolean transactionEnd)` Ensures that the statement cursor is closed.
    `void` | `execute(RowValue parameters)` Execute the statement.
    `void` | `fetchRows(int fetchSize)` Requests this statement to fetch the next `fetchSize` rows.
    `FbDatabase` | `getDatabase()`
    `int` | `getDefaultSqlInfoSize()`
    `java.lang.String` | `getExecutionPlan()`
    `RowDescriptor` | `getFieldDescriptor()`
    `int` | `getHandle()`
    `int` | `getMaxSqlInfoSize()`
    `RowDescriptor` | `getParameterDescriptor()`
    `SqlCountHolder` | `getSqlCounts()` Retrieves the SQL counts for the last execution of this statement.
    `byte[]` | `getSqlInfo(byte[] requestItems, int bufferLength)` Request statement info.
    `<T> T` | `getSqlInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)` Request statement info.
    `StatementState` | `getState()`
    `FbTransaction` | `getTransaction()`
    `StatementType` | `getType()`
    `void` | `prepare(java.lang.String statementText)` Prepare the statement text.
    `void` | `removeStatementListener(StatementListener statementListener)` Removes a `StatementListener`.
    `void` | `setCursorName(java.lang.String cursorName)` Sets the named cursor name for this statement.
    `void` | `setTransaction(FbTransaction transaction)` Associates a transaction with this statement

    - ### Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable

      `addExceptionListener, removeExceptionListener`

- - ### Method Detail

    - #### getTransaction

          FbTransaction getTransaction()

      Returns:
        Transaction currently associated with this statement

    - #### getDatabase

          FbDatabase getDatabase()

      Returns:
        The database connection that created this statement

    - #### setTransaction

          void setTransaction(FbTransaction transaction)
                       throws java.sql.SQLException

      Associates a transaction with this statement
      Parameters:
        `transaction` - The transaction
      Throws:
        `java.sql.SQLException`

    - #### getParameterDescriptor

          RowDescriptor getParameterDescriptor()

      Returns:
        descriptor of the parameters of this statement

    - #### getFieldDescriptor

          RowDescriptor getFieldDescriptor()

      Returns:
        descriptor of the fields returned by this statement

    - #### getType

          StatementType getType()

      Returns:
        The statement type

    - #### getState

          StatementState getState()

      Returns:
        The current state of this statement

    - #### getHandle

          int getHandle()

      Returns:
        The Firebird statement handle identifier

    - #### close

          void close()
              throws java.sql.SQLException

      Close and deallocate this statement.
      Throws:
        `java.sql.SQLException`

    - #### closeCursor

          void closeCursor()
                    throws java.sql.SQLException

      Closes the cursor associated with this statement, leaving the statement itself allocated.

      Equivalent to calling `closeCursor(boolean)` with `false`.

      Throws:
        `java.sql.SQLException`

    - #### closeCursor

          void closeCursor(boolean transactionEnd)
                    throws java.sql.SQLException

      Closes the cursor associated with this statement, leaving the statement itself allocated.

      When this method is called in preparation of a commit or rollback (see `transactionEnd`), then implementations may opt to not close the cursor on the server if the server closes the cursor automatically.

      Parameters:
        `transactionEnd` - Close is in response to a transaction end.
      Throws:
        `java.sql.SQLException`

    - #### prepare

          void prepare(java.lang.String statementText)
                throws java.sql.SQLException

      Prepare the statement text.

      If this handle is in state `StatementState.NEW` then it will first allocate the statement.

      Parameters:
        `statementText` - Statement text
      Throws:
        `java.sql.SQLException` - If a database access error occurs, or this statement is currently executing a query.

    - #### execute

          void execute(RowValue parameters)
                throws java.sql.SQLException

      Execute the statement.
      Parameters:
        `parameters` - The list of parameter values to use for execution.
      Throws:
        `java.sql.SQLException` - When the number of type of parameters does not match the types returned by `getParameterDescriptor()`, a parameter value was not set, or when an error occurred executing this statement.

    - #### fetchRows

          void fetchRows(int fetchSize)
                  throws java.sql.SQLException

      Requests this statement to fetch the next `fetchSize` rows.

      Fetched rows are not returned from this method, but sent to the registered `StatementListener` instances.

      Parameters:
        `fetchSize` - Number of rows to fetch (must be `> 0`)
      Throws:
        `java.sql.SQLException` - For database access errors, when called on a closed statement, when no cursor is open or when the fetch size is not `> 0`.

    - #### addStatementListener

          void addStatementListener(StatementListener statementListener)

      Registers a `StatementListener`.
      Parameters:
        `statementListener` - The row listener

    - #### removeStatementListener

          void removeStatementListener(StatementListener statementListener)

      Removes a `StatementListener`.
      Parameters:
        `statementListener` - The row listener

    - #### getSqlInfo

          <T> T getSqlInfo(byte[] requestItems,
                           int bufferLength,
                           InfoProcessor<T> infoProcessor)
                    throws java.sql.SQLException

      Request statement info.
      Parameters:
        `requestItems` - Array of info items to request
        `bufferLength` - Response buffer length to use
        `infoProcessor` - Implementation of `InfoProcessor` to transform the info response
      Returns:
        Transformed info response of type T
      Throws:
        `java.sql.SQLException` - For errors retrieving or transforming the response.

    - #### getSqlInfo

          byte[] getSqlInfo(byte[] requestItems,
                            int bufferLength)
                     throws java.sql.SQLException

      Request statement info.
      Parameters:
        `requestItems` - Array of info items to request
        `bufferLength` - Response buffer length to use
      Returns:
        Response buffer
      Throws:
        `java.sql.SQLException`

    - #### getDefaultSqlInfoSize

          int getDefaultSqlInfoSize()

      Returns:
        The default size to use for the sql info buffer

    - #### getMaxSqlInfoSize

          int getMaxSqlInfoSize()

      Returns:
        The maximum size to use for the sql info buffer

    - #### getExecutionPlan

          java.lang.String getExecutionPlan()
                                     throws java.sql.SQLException

      Returns:
        The execution plan of the currently prepared statement
      Throws:
        `java.sql.SQLException` - If this statement is closed.

    - #### getSqlCounts

          SqlCountHolder getSqlCounts()
                               throws java.sql.SQLException

      Retrieves the SQL counts for the last execution of this statement.

      The retrieved SQL counts are also notified to all registered `StatementListener`s.

      In general the `FbStatement` will (should) retrieve and notify listeners of the SQL counts automatically at times were it is relevant (eg after executing a statement that does not produce multiple rows, or after fetching all rows).

      Returns:
        The SQL counts of the last execution of this statement
      Throws:
        `java.sql.SQLException` - If this statement is closed, or if this statement is in state `StatementState.CURSOR_OPEN` and not all rows have been fetched.

    - #### setCursorName

          void setCursorName(java.lang.String cursorName)
                      throws java.sql.SQLException

      Sets the named cursor name for this statement.
      Parameters:
        `cursorName` - Name of the cursor
      Throws:
        `java.sql.SQLException` - If this statement is closed, TODO: Other reasons (eg cursor open)?

    - #### emptyRowDescriptor

          RowDescriptor emptyRowDescriptor()

      Returns:
        A potentially cached empty row descriptor for this statement or database.

    - #### ensureClosedCursor

          void ensureClosedCursor(boolean transactionEnd)
                           throws java.sql.SQLException

      Ensures that the statement cursor is closed. Resets a statement so it is ready to be reused for re-execute or prepare.

      Implementations should only close an open cursor and log this fact with a stacktrace on debug. This is a stopgap measure for situations where the code using this statement handle has not been able to properly close the cursor.

      Parameters:
        `transactionEnd` - Close is in response to a transaction end
      Throws:
        `java.sql.SQLException` - If this statement is closed or the cursor could not be closed.
      Since:
        3.0.6

Copyright © 2001-2021 Jaybird (Firebird JDBC/JCA) team. All rights reserved.