Package org.firebirdsql.gds.ng

## Class AbstractFbStatement

- java.lang.Object
- - org.firebirdsql.gds.ng.AbstractFbStatement

- All Implemented Interfaces:
    `FbStatement`, `ExceptionListenable`
  Direct Known Subclasses:
    `AbstractFbWireStatement`, `JnaStatement`

      public abstract class AbstractFbStatement
      extends java.lang.Object
      implements FbStatement

  Since:
    3.0
  Author:
    Mark Rotteveel

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected ExceptionListenerDispatcher` | `exceptionListenerDispatcher` |
    `protected StatementListenerDispatcher` | `statementListenerDispatcher` |

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractFbStatement​(java.lang.Object syncObject)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addExceptionListener​(ExceptionListener listener)` | Adds an exception listener to this object.
    `void` | `addStatementListener​(StatementListener statementListener)` | Registers a `StatementListener`.
    `protected void` | `checkStatementValid()` | Checks if this statement is not in `StatementState.CLOSED`, `StatementState.CLOSING`, `StatementState.NEW` or `StatementState.ERROR`, and throws an `SQLException` if it is.
    `protected void` | `checkStatementValid​(StatementState ignoreState)` | Performs the same check as `checkStatementValid()`, but considers `ignoreState` as valid.
    `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.
    `protected ExecutionPlanProcessor` | `createExecutionPlanProcessor()` |
    `protected SqlCountProcessor` | `createSqlCountProcessor()` |
    `void` | `ensureClosedCursor​(boolean transactionEnd)` | Ensures that the statement cursor is closed.
    `protected void` | `finalize()` |
    `protected abstract void` | `free​(int option)` | Frees the currently allocated statement (either close the cursor with `ISCConstants.DSQL_close` or drop the statement handle using `ISCConstants.DSQL_drop`.
    `protected long` | `getAllowedTimeout()` |
    `java.lang.String` | `getExecutionPlan()` |
    `java.lang.String` | `getExplainedExecutionPlan()` |
    `RowDescriptor` | `getFieldDescriptor()` | Deprecated.
    `byte[]` | `getParameterDescriptionInfoRequestItems()` |
    `RowDescriptor` | `getParameterDescriptor()` |
    `RowDescriptor` | `getRowDescriptor()` |
    `SqlCountHolder` | `getSqlCounts()` | Retrieves the SQL counts for the last execution of this statement.
    `<T> T` | `getSqlInfo​(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)` | Request statement info.
    `StatementState` | `getState()` |
    `byte[]` | `getStatementInfoRequestItems()` |
    `protected WarningMessageCallback` | `getStatementWarningCallback()` |
    `protected java.lang.Object` | `getSynchronizationObject()` | Get synchronization object.
    `long` | `getTimeout()` | Gets the current statement timeout for this statement.
    `FbTransaction` | `getTransaction()` |
    `protected TransactionListener` | `getTransactionListener()` | Gets the `TransactionListener` instance for this statement.
    `StatementType` | `getType()` |
    `protected boolean` | `hasFields()` |
    `protected boolean` | `hasSingletonResult()` |
    `protected boolean` | `isAllRowsFetched()` |
    `protected boolean` | `isPrepareAllowed​(StatementState state)` | Is a call to `FbStatement.prepare(String)` allowed for the supplied `StatementState`.
    `protected abstract boolean` | `isValidTransactionClass​(java.lang.Class<? extends FbTransaction> transactionClass)` | Method to decide if a transaction implementation class is valid for the statement implementation.
    `protected void` | `parseStatementInfo​(byte[] statementInfoResponse)` | Parse the statement info response in `statementInfoResponse`.
    `protected void` | `queueRowData​(RowValue rowData)` | Queues row data for consumption
    `void` | `removeExceptionListener​(ExceptionListener listener)` | Removes an exception listener to this object.
    `void` | `removeStatementListener​(StatementListener statementListener)` | Removes a `StatementListener`.
    `protected void` | `reset()` | Reset statement state, equivalent to calling `reset(boolean)` with `false`
    `protected void` | `reset​(boolean resetAll)` | Resets the statement for next execution.
    `protected void` | `resetAll()` | Reset statement state and clear parameter description, equivalent to calling `reset(boolean)` with `true`
    `protected void` | `setAllRowsFetched​(boolean allRowsFetched)` | Sets the `allRowsFetched` property.
    `protected void` | `setFieldDescriptor​(RowDescriptor fieldDescriptor)` | Deprecated. Use `setRowDescriptor(RowDescriptor)` instead; will be removed in Jaybird 5
    `protected void` | `setParameterDescriptor​(RowDescriptor parameterDescriptor)` | Sets the parameter descriptor.
    `protected void` | `setRowDescriptor​(RowDescriptor rowDescriptor)` | Sets the (result set) row descriptor.
    `void` | `setTimeout​(long statementTimeout)` | Sets the statement timeout.
    `void` | `setTransaction​(FbTransaction newTransaction)` | Associates a transaction with this statement
    `protected void` | `setType​(StatementType type)` | Sets the StatementType
    `protected OperationCloseHandle` | `signalExecute()` | Signals the start of an execute for this statement.
    `protected OperationCloseHandle` | `signalFetch()` | Signals the start of a fetch for this statement.
    `protected void` | `switchState​(StatementState newState)` | Sets the StatementState.
    `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 class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.firebirdsql.gds.ng.FbStatement

      `emptyRowDescriptor, execute, fetchRows, getDatabase, getDefaultSqlInfoSize, getHandle, getMaxSqlInfoSize, getSqlInfo, prepare, setCursorName`

- - ### Field Detail

    - #### statementListenerDispatcher

          protected final StatementListenerDispatcher statementListenerDispatcher

    - #### exceptionListenerDispatcher

          protected final ExceptionListenerDispatcher exceptionListenerDispatcher

  - ### Constructor Detail

    - #### AbstractFbStatement

          protected AbstractFbStatement​(java.lang.Object syncObject)

  - ### Method Detail

    - #### getTransactionListener

          protected final TransactionListener getTransactionListener()

      Gets the `TransactionListener` instance for this statement.

      This method should only be called by this object itself. Subclasses may provide their own transaction listener, but the instance returned by this method should be the same for the lifetime of this `FbStatement`.

      Returns:
        The transaction listener instance for this statement.

    - #### getStatementWarningCallback

          protected final WarningMessageCallback getStatementWarningCallback()

    - #### getSynchronizationObject

          protected final java.lang.Object getSynchronizationObject()

      Get synchronization object.
      Returns:
        object, cannot be `null`.

    - #### close

          public void close()
                     throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      Close and deallocate this statement.
      Specified by:
        `close` in interface `FbStatement`
      Throws:
        `java.sql.SQLException`

    - #### closeCursor

          public final void closeCursor()
                                 throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      Closes the cursor associated with this statement, leaving the statement itself allocated.

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

      Specified by:
        `closeCursor` in interface `FbStatement`
      Throws:
        `java.sql.SQLException`

    - #### closeCursor

          public final void closeCursor​(boolean transactionEnd)
                                 throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      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.

      Specified by:
        `closeCursor` in interface `FbStatement`
      Parameters:
        `transactionEnd` - Close is in response to a transaction end.
      Throws:
        `java.sql.SQLException`

    - #### ensureClosedCursor

          public final void ensureClosedCursor​(boolean transactionEnd)
                                        throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      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.

      Specified by:
        `ensureClosedCursor` in interface `FbStatement`
      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.

    - #### getState

          public StatementState getState()

      Specified by:
        `getState` in interface `FbStatement`
      Returns:
        The current state of this statement

    - #### switchState

          protected final void switchState​(StatementState newState)
                                    throws java.sql.SQLException

      Sets the StatementState.
      Parameters:
        `newState` - New state
      Throws:
        `java.sql.SQLException` - When the state is changed to an illegal next state

    - #### getType

          public final StatementType getType()

      Specified by:
        `getType` in interface `FbStatement`
      Returns:
        The statement type

    - #### setType

          protected void setType​(StatementType type)

      Sets the StatementType
      Parameters:
        `type` - New type

    - #### queueRowData

          protected final void queueRowData​(RowValue rowData)

      Queues row data for consumption
      Parameters:
        `rowData` - Row data

    - #### setAllRowsFetched

          protected final void setAllRowsFetched​(boolean allRowsFetched)

      Sets the `allRowsFetched` property.

      When set to true all registered `StatementListener` instances are notified for the `StatementListener.allRowsFetched(FbStatement)` event.

      Parameters:
        `allRowsFetched` - `true`: all rows fetched, `false` not all rows fetched.

    - #### isAllRowsFetched

          protected final boolean isAllRowsFetched()

    - #### reset

          protected final void reset()

      Reset statement state, equivalent to calling `reset(boolean)` with `false`

    - #### resetAll

          protected final void resetAll()

      Reset statement state and clear parameter description, equivalent to calling `reset(boolean)` with `true`

    - #### reset

          protected void reset​(boolean resetAll)

      Resets the statement for next execution. Implementation in derived class must synchronize on `getSynchronizationObject()` and call `super.reset(resetAll)`
      Parameters:
        `resetAll` - Also reset field and parameter info

    - #### isPrepareAllowed

          protected boolean isPrepareAllowed​(StatementState state)

      Is a call to `FbStatement.prepare(String)` allowed for the supplied `StatementState`.
      Parameters:
        `state` - The statement state
      Returns:
        `true` call to `prepare` is allowed

    - #### getParameterDescriptor

          public final RowDescriptor getParameterDescriptor()

      Specified by:
        `getParameterDescriptor` in interface `FbStatement`
      Returns:
        descriptor of the parameters of this statement

    - #### setParameterDescriptor

          protected void setParameterDescriptor​(RowDescriptor parameterDescriptor)

      Sets the parameter descriptor.
      Parameters:
        `parameterDescriptor` - Parameter descriptor

    - #### getFieldDescriptor

          @Deprecated
          public final RowDescriptor getFieldDescriptor()

      Deprecated.
      Specified by:
        `getFieldDescriptor` in interface `FbStatement`
      Returns:
        descriptor of the fields returned by this statement

    - #### setFieldDescriptor

          @Deprecated
          protected void setFieldDescriptor​(RowDescriptor fieldDescriptor)

      Deprecated.
      Use `setRowDescriptor(RowDescriptor)` instead; will be removed in Jaybird 5
      Sets the (result set) field descriptor.
      Parameters:
        `fieldDescriptor` - Field descriptor

    - #### getRowDescriptor

          public final RowDescriptor getRowDescriptor()

      Specified by:
        `getRowDescriptor` in interface `FbStatement`
      Returns:
        descriptor of the row returned by this statement

    - #### setRowDescriptor

          protected void setRowDescriptor​(RowDescriptor rowDescriptor)

      Sets the (result set) row descriptor.
      Parameters:
        `rowDescriptor` - Row descriptor

    - #### getStatementInfoRequestItems

          public byte[] getStatementInfoRequestItems()

      Returns:
        The (full) statement info request items.
      See Also:
        `getParameterDescriptionInfoRequestItems()`

    - #### getParameterDescriptionInfoRequestItems

          public byte[] getParameterDescriptionInfoRequestItems()

      Returns:
        The `isc_info_sql_describe_vars` info request items.
      See Also:
        `getStatementInfoRequestItems()`

    - #### getSqlInfo

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

      Request statement info.
      Specified by:
        `getSqlInfo` in interface `FbStatement`
      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.

    - #### getExecutionPlan

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

      Specified by:
        `getExecutionPlan` in interface `FbStatement`
      Returns:
        The execution plan of the currently prepared statement
      Throws:
        `java.sql.SQLException` - If this statement is closed.

    - #### getExplainedExecutionPlan

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

      Specified by:
        `getExplainedExecutionPlan` in interface `FbStatement`
      Returns:
        The detailed execution plan of the currently prepared statement
      Throws:
        `java.sql.SQLException` - If this statement is closed.

    - #### createExecutionPlanProcessor

          protected ExecutionPlanProcessor createExecutionPlanProcessor()

      Returns:
        New instance of `ExecutionPlanProcessor` (or subclass) for this statement.

    - #### getSqlCounts

          public SqlCountHolder getSqlCounts()
                                      throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      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).

      Specified by:
        `getSqlCounts` in interface `FbStatement`
      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.

    - #### createSqlCountProcessor

          protected SqlCountProcessor createSqlCountProcessor()

      Returns:
        New instance of `SqlCountProcessor` (or subclass) for this statement.

    - #### free

          protected abstract void free​(int option)
                                throws java.sql.SQLException

      Frees the currently allocated statement (either close the cursor with `ISCConstants.DSQL_close` or drop the statement handle using `ISCConstants.DSQL_drop`.
      Parameters:
        `option` - Free option
      Throws:
        `java.sql.SQLException`

    - #### validateParameters

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

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

    - #### addStatementListener

          public final void addStatementListener​(StatementListener statementListener)

      Description copied from interface: `FbStatement`
      Registers a `StatementListener`.
      Specified by:
        `addStatementListener` in interface `FbStatement`
      Parameters:
        `statementListener` - The row listener

    - #### removeStatementListener

          public final void removeStatementListener​(StatementListener statementListener)

      Description copied from interface: `FbStatement`
      Removes a `StatementListener`.
      Specified by:
        `removeStatementListener` in interface `FbStatement`
      Parameters:
        `statementListener` - The row listener

    - #### addExceptionListener

          public final void addExceptionListener​(ExceptionListener listener)

      Description copied from interface: `ExceptionListenable`
      Adds an exception listener to this object.

      Implementations use `WeakReference`.

      Specified by:
        `addExceptionListener` in interface `ExceptionListenable`
      Parameters:
        `listener` - Listener to register

    - #### removeExceptionListener

          public final void removeExceptionListener​(ExceptionListener listener)

      Description copied from interface: `ExceptionListenable`
      Removes an exception listener to this object.
      Specified by:
        `removeExceptionListener` in interface `ExceptionListenable`
      Parameters:
        `listener` - Listener to remove

    - #### checkStatementValid

          protected final void checkStatementValid()
                                            throws java.sql.SQLException

      Checks if this statement is not in `StatementState.CLOSED`, `StatementState.CLOSING`, `StatementState.NEW` or `StatementState.ERROR`, and throws an `SQLException` if it is.
      Throws:
        `java.sql.SQLException` - When this statement is closed or in error state.

    - #### checkStatementValid

          protected final void checkStatementValid​(StatementState ignoreState)
                                            throws java.sql.SQLException

      Performs the same check as `checkStatementValid()`, but considers `ignoreState` as valid.
      Parameters:
        `ignoreState` - The invalid state (see `checkStatementValid()` to ignore
      Throws:
        `java.sql.SQLException` - When this statement is closed or in error state.

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `java.lang.Throwable`

    - #### getTransaction

          public FbTransaction getTransaction()

      Specified by:
        `getTransaction` in interface `FbStatement`
      Returns:
        Transaction currently associated with this statement

    - #### isValidTransactionClass

          protected abstract boolean isValidTransactionClass​(java.lang.Class<? extends FbTransaction> transactionClass)

      Method to decide if a transaction implementation class is valid for the statement implementation.

      Eg a `V10Statement` will only work with an `FbWireTransaction` implementation.

      Parameters:
        `transactionClass` - Class of the transaction
      Returns:
        `true` when the transaction class is valid for the statement implementation.

    - #### setTransaction

          public final void setTransaction​(FbTransaction newTransaction)
                                    throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      Associates a transaction with this statement
      Specified by:
        `setTransaction` in interface `FbStatement`
      Parameters:
        `newTransaction` - The transaction
      Throws:
        `java.sql.SQLException`

    - #### setTimeout

          public void setTimeout​(long statementTimeout)
                          throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      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.

      Specified by:
        `setTimeout` in interface `FbStatement`
      Parameters:
        `statementTimeout` - 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

    - #### getTimeout

          public long getTimeout()
                          throws java.sql.SQLException

      Description copied from interface: `FbStatement`
      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.

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

    - #### getAllowedTimeout

          protected long getAllowedTimeout()
                                    throws java.sql.SQLException

      Returns:
        The timeout value, or `0` if the timeout is larger than supported
      Throws:
        `java.sql.SQLException` - If the statement is invalid

    - #### parseStatementInfo

          protected void parseStatementInfo​(byte[] statementInfoResponse)
                                     throws java.sql.SQLException

      Parse the statement info response in `statementInfoResponse`. If the response is truncated, a new request is done using `getStatementInfoRequestItems()`
      Parameters:
        `statementInfoResponse` - Statement info response
      Throws:
        `java.sql.SQLException`

    - #### hasSingletonResult

          protected final boolean hasSingletonResult()

      Returns:
        `true` if this is a stored procedure (or other singleton result producing statement) with at least 1 output field

    - #### hasFields

          protected final boolean hasFields()

      Returns:
        `true` if this statement has at least one output field (either singleton or result set)

    - #### signalExecute

          protected final OperationCloseHandle signalExecute()

      Signals the start of an execute for this statement.
      Returns:
        `OperationCloseHandle` handle for the operation

    - #### signalFetch

          protected final OperationCloseHandle signalFetch()

      Signals the start of a fetch for this statement.
      Returns:
        `OperationCloseHandle` handle for the operation