Package org.firebirdsql.gds.ng.jna

## Class JnaStatement

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

- All Implemented Interfaces:
    `java.lang.AutoCloseable`, `FbStatement`, `ExceptionListenable`

      public class JnaStatement
      extends AbstractFbStatement

  Implementation of `FbStatement` for native client access.
  Since:
    3.0
  Author:
    Mark Rotteveel

- - ### Field Summary

    - ### Fields inherited from class org.firebirdsql.gds.ng.AbstractFbStatement

      `exceptionListenerDispatcher, statementListenerDispatcher`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JnaStatement​(JnaDatabase database)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected XSQLDA` | `allocateXSqlDa​(RowDescriptor rowDescriptor)` | Creates an XSQLDA, populates type information and allocates memory for the sqldata fields.
    `RowDescriptor` | `emptyRowDescriptor()` |
    `void` | `execute​(RowValue parameters)` | Execute the statement.
    `void` | `fetchRows​(int fetchSize)` | Requests this statement to fetch the next `fetchSize` rows.
    `protected void` | `free​(int option)` | Frees the currently allocated statement.
    `JnaDatabase` | `getDatabase()` |
    `int` | `getDefaultSqlInfoSize()` |
    `int` | `getHandle()` |
    `int` | `getMaxSqlInfoSize()` |
    `byte[]` | `getSqlInfo​(byte[] requestItems, int bufferLength)` | Request statement info.
    `JnaTransaction` | `getTransaction()` |
    `protected boolean` | `isValidTransactionClass​(java.lang.Class<? extends FbTransaction> transactionClass)` | Method to decide if a transaction implementation class is valid for the statement implementation.
    `void` | `prepare​(java.lang.String statementText)` | Prepare the statement text.
    `void` | `setCursorName​(java.lang.String cursorName)` | Sets the named cursor name for this statement.
    `protected void` | `setParameterDescriptor​(RowDescriptor parameterDescriptor)` | Sets the parameter descriptor.
    `protected void` | `setRowDescriptor​(RowDescriptor fieldDescriptor)` | Sets the (result set) row descriptor.
    `protected void` | `setXSqlDaData​(XSQLDA xSqlDa, RowDescriptor rowDescriptor, RowValue parameters)` | Populates an XSQLDA from the row descriptor and parameter values.
    `protected RowValue` | `toRowValue​(RowDescriptor rowDescriptor, XSQLDA xSqlDa)` | Converts the data from an XSQLDA to a RowValue.
    `LockCloseable` | `withLock()` | Locks the lock with `Lock.lock()` (or equivalent).

    - ### Methods inherited from class org.firebirdsql.gds.ng.AbstractFbStatement

      `addExceptionListener, addStatementListener, checkStatementValid, checkStatementValid, close, closeCursor, closeCursor, createExecutionPlanProcessor, createSqlCountProcessor, ensureClosedCursor, fetchScroll, fetchScrollImpl, finalize, forceState, getAllowedTimeout, getCursorInfo, getCursorInfo, getCursorInfoImpl, getExecutionPlan, getExplainedExecutionPlan, getParameterDescriptionInfoRequestItems, getParameterDescriptor, getRowDescriptor, getSqlCounts, getSqlInfo, getState, getStatementInfoRequestItems, getStatementWarningCallback, getTimeout, getTransactionListener, getType, hasFetched, hasFields, hasSingletonResult, isAfterLast, isBeforeFirst, isPrepareAllowed, parseStatementInfo, queueRowData, removeExceptionListener, removeStatementListener, reset, reset, resetAll, setAfterLast, setBeforeFirst, setTimeout, setTransaction, setType, signalExecute, signalFetch, switchState, unprepare, validateParameters`

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

      `batchCancel, batchExecute, clearCursorFlag, createBatchParameterBuffer, deferredBatchCreate, deferredBatchRelease, deferredBatchSend, isCursorFlagSet, setCursorFlag, supportBatchUpdates, supportsCursorInfo, supportsFetchScroll`

- - ### Constructor Detail

    - #### JnaStatement

          public JnaStatement​(JnaDatabase database)

  - ### Method Detail

    - #### withLock

          public final LockCloseable withLock()

      Description copied from interface: `FbStatement`
      Locks the lock with `Lock.lock()` (or equivalent).

      Implementations are expected to apply the same lock as `FbAttachment.withLock()`.

      Returns:
        lock closeable which unlocks the lock on close
      See Also:
        `FbAttachment.withLock()`

    - #### setParameterDescriptor

          protected void setParameterDescriptor​(RowDescriptor parameterDescriptor)

      Description copied from class: `AbstractFbStatement`
      Sets the parameter descriptor.
      Overrides:
        `setParameterDescriptor` in class `AbstractFbStatement`
      Parameters:
        `parameterDescriptor` - Parameter descriptor

    - #### setRowDescriptor

          protected void setRowDescriptor​(RowDescriptor fieldDescriptor)

      Description copied from class: `AbstractFbStatement`
      Sets the (result set) row descriptor.
      Overrides:
        `setRowDescriptor` in class `AbstractFbStatement`
      Parameters:
        `fieldDescriptor` - Row descriptor

    - #### free

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

      Description copied from class: `AbstractFbStatement`
      Frees the currently allocated statement. Either close the cursor with `ISCConstants.DSQL_close` or drop the statement handle using `ISCConstants.DSQL_drop`.
      Specified by:
        `free` in class `AbstractFbStatement`
      Parameters:
        `option` - Free option
      Throws:
        `java.sql.SQLException`

    - #### isValidTransactionClass

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

      Description copied from class: `AbstractFbStatement`
      Method to decide if a transaction implementation class is valid for the statement implementation.

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

      Specified by:
        `isValidTransactionClass` in class `AbstractFbStatement`
      Parameters:
        `transactionClass` - Class of the transaction
      Returns:
        `true` when the transaction class is valid for the statement implementation.

    - #### getDatabase

          public JnaDatabase getDatabase()

      Returns:
        The database connection that created this statement

    - #### getHandle

          public int getHandle()

      Returns:
        The Firebird statement handle identifier

    - #### getTransaction

          public JnaTransaction getTransaction()

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

    - #### prepare

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

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

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

      Description copied from interface: `FbStatement`
      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 `FbStatement.getParameterDescriptor()`, a parameter value was not set, or when an error occurred executing this statement.

    - #### setXSqlDaData

          protected void setXSqlDaData​(XSQLDA xSqlDa,
                                       RowDescriptor rowDescriptor,
                                       RowValue parameters)

      Populates an XSQLDA from the row descriptor and parameter values.
      Parameters:
        `xSqlDa` - XSQLDA
        `rowDescriptor` - Row descriptor
        `parameters` - Parameter values

    - #### allocateXSqlDa

          protected XSQLDA allocateXSqlDa​(RowDescriptor rowDescriptor)

      Creates an XSQLDA, populates type information and allocates memory for the sqldata fields.
      Parameters:
        `rowDescriptor` - The row descriptor
      Returns:
        Allocated XSQLDA without data

    - #### toRowValue

          protected RowValue toRowValue​(RowDescriptor rowDescriptor,
                                        XSQLDA xSqlDa)

      Converts the data from an XSQLDA to a RowValue.
      Parameters:
        `rowDescriptor` - Row descriptor
        `xSqlDa` - XSQLDA
      Returns:
        Row value

    - #### fetchRows

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

      The JNA implementation ignores the specified `fetchSize` to prevent problems with - for example - positioned updates with named cursors. For the wire protocol that case is handled by the server ignoring the fetch size. Internally the native fetch will batch a number of records, but the number is outside our control.

      Parameters:
        `fetchSize` - Number of rows to fetch (must be greater than `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 greater than `0`.

    - #### getSqlInfo

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

      Description copied from interface: `FbStatement`
      Request statement info.
      Parameters:
        `requestItems` - Array of info items to request
        `bufferLength` - Response buffer length to use
      Returns:
        Response buffer
      Throws:
        `java.sql.SQLException` - For errors retrieving or transforming the response.

    - #### getDefaultSqlInfoSize

          public int getDefaultSqlInfoSize()

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

    - #### getMaxSqlInfoSize

          public int getMaxSqlInfoSize()

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

    - #### setCursorName

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

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

          public final RowDescriptor emptyRowDescriptor()

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