Package org.firebirdsql.gds.ng

## Interface FbStatement

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

      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 Deprecated Methods
    Modifier and Type | Method | 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()` |
    `java.lang.String` | `getExplainedExecutionPlan()` |
    `RowDescriptor` | `getFieldDescriptor()` | Deprecated. Use `getRowDescriptor()` instead; will be removed in Jaybird 5
    `int` | `getHandle()` |
    `int` | `getMaxSqlInfoSize()` |
    `RowDescriptor` | `getParameterDescriptor()` |
    `RowDescriptor` | `getRowDescriptor()` |
    `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()` |
    `long` | `getTimeout()` | Gets the current statement timeout for this statement.
    `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` | `setTimeout​(long timeoutMillis)` | Sets the statement timeout.
    `void` | `setTransaction​(FbTransaction transaction)` | Associates a transaction with this statement
    `void` | `validateParameters​(RowValue parameters)` | Validates if the number of parameters matches the expected number and types, and if all values have been set.

    - ### 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

          @Deprecated
          RowDescriptor getFieldDescriptor()

      Deprecated.
      Use `getRowDescriptor()` instead; will be removed in Jaybird 5
      Returns:
        descriptor of the fields returned by this statement

    - #### getRowDescriptor

          RowDescriptor getRowDescriptor()

      Returns:
        descriptor of the row 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.

    - #### validateParameters

          void validateParameters​(RowValue parameters)
                           throws java.sql.SQLException

      Validates if the number of parameters matches the expected number and types, and if all values have been set.
      Parameters:
        `parameters` - Parameter values to validate
      Throws:
        `java.sql.SQLException` - When the number or type of parameters does not match `getParameterDescriptor()`, or when a parameter has not been set.

    - #### 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.

    - #### getExplainedExecutionPlan

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

      Returns:
        The detailed 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

    - #### setTimeout

          void setTimeout​(long timeoutMillis)
                   throws java.sql.SQLException

      Sets the statement timeout.

      The statement timeout value is ignored in implementations that do not support timeouts. If the provided timeout value is greater than supported (eg greater than â€4294967295â€¬ milliseconds on Firebird 4), the implementation should behave as if zero (`0`) was set, but still report the original value.

      The configured timeout only affects subsequent executes on this statement. The timeout includes time spent between reading from the result set.

      Parameters:
        `timeoutMillis` - Timeout value in milliseconds
      Throws:
        `java.sql.SQLException` - If the value is less than zero, this statement is closed, or a database access error occurs
      Since:
        4.0

    - #### getTimeout

          long getTimeout()
                   throws java.sql.SQLException

      Gets the current statement timeout for this statement.

      This method will only return the current statement timeout value for this method, it will not consider attachment or connection level timeouts. This is an implementation decision that might change in a point release.

      Returns:
        The configured timeout in milliseconds; read the documentation in `setTimeout(long)`
      Throws:
        `java.sql.SQLException` - If this statement is closed, or a database access error occurs
      Since:
        4.0
      See Also:
        `setTimeout(long)`