Package org.firebirdsql.gds.ng.jna

## Class JnaDatabase

- java.lang.Object
- - org.firebirdsql.gds.ng.AbstractFbAttachment<T>
  - - org.firebirdsql.gds.ng.AbstractFbDatabase<JnaDatabaseConnection>
    - - org.firebirdsql.gds.ng.jna.JnaDatabase

- All Implemented Interfaces:
    `java.lang.AutoCloseable`, `FbAttachment`, `FbDatabase`, `FbClientFeatureAccess`, `JnaAttachment`, `ExceptionListenable`, `TransactionListener`

      public class JnaDatabase
      extends AbstractFbDatabase<JnaDatabaseConnection>
      implements JnaAttachment, TransactionListener, FbClientFeatureAccess

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

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected com.sun.jna.ptr.IntByReference` | `handle` |
    `static int` | `MAX_STATEMENT_LENGTH` |
    `static int` | `STATUS_VECTOR_SIZE` |
    `protected ISC_STATUS[]` | `statusVector` |

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

      `databaseListenerDispatcher`

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

      `connection, exceptionListenerDispatcher`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JnaDatabase​(JnaDatabaseConnection connection)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `afterAttachActions()` | Additional tasks to execute directly after attach operation.
    `void` | `attach()` | Attach to the attachment type.
    `protected void` | `attachOrCreate​(DatabaseParameterBuffer dpb, boolean create)` |
    `void` | `cancelEvent​(EventHandle eventHandle)` | Cancels a registered event.
    `void` | `cancelOperation​(int kind)` | Cancels the current operation.
    `protected void` | `checkConnected()` | Checks if the attachment is connected, and throws a `SQLException` if it isn't connected.
    `void` | `countEvents​(EventHandle eventHandle)` | Counts the events occurred.
    `FbBlob` | `createBlobForInput​(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer, long blobId)` | Creates a blob for read access to an existing blob on the server.
    `FbBlob` | `createBlobForOutput​(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer)` | Creates a blob for write access to a new blob on the server.
    `void` | `createDatabase()` | Creates a new database, connection remains attached to database.
    `JnaEventHandle` | `createEventHandle​(java.lang.String eventName, EventHandler eventHandler)` | Creates an event handle for this database type.
    `JnaStatement` | `createStatement​(FbTransaction transaction)` | Creates a statement associated with a transaction
    `void` | `dropDatabase()` | Drops (and deletes) the currently attached database.
    `void` | `executeImmediate​(java.lang.String statementText, FbTransaction transaction)` | Performs an execute immediate of a statement.
    `protected void` | `finalize()` |
    `protected FbClientLibrary` | `getClientLibrary()` |
    `byte[]` | `getDatabaseInfo​(byte[] requestItems, int maxBufferLength)` | Performs a database info request.
    `EncodingDefinition` | `getEncodingDefinition()` |
    `java.util.Set<FbClientFeature>` | `getFeatures()` |
    `int` | `getHandle()` |
    `com.sun.jna.ptr.IntByReference` | `getJnaHandle()` |
    `int` | `getNetworkTimeout()` | Gets the current network timeout for this attachment.
    `protected byte[]` | `getTransactionIdBuffer​(long transactionId)` |
    `boolean` | `hasFeature​(FbClientFeature clientFeature)` | Checks for presence of a client feature.
    `protected void` | `internalDetach()` | Actual implementation of database detach.
    `void` | `processStatusVector​(ISC_STATUS[] statusVector, WarningMessageCallback warningMessageCallback)` |
    `void` | `queueEvent​(EventHandle eventHandle)` | Queues a wait for an event.
    `FbTransaction` | `reconnectTransaction​(long transactionId)` | Reconnects a prepared transaction.
    `void` | `setNetworkTimeout​(int milliseconds)` | Sets the network timeout for this attachment.
    `JnaTransaction` | `startTransaction​(TransactionParameterBuffer tpb)` | Creates and starts a transaction.
    `protected JnaEventHandle` | `validateEventHandle​(EventHandle eventHandle)` |

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

      `addDatabaseListener, addWeakDatabaseListener, close, createBlobParameterBuffer, createTransactionParameterBuffer, emptyRowDescriptor, getActiveTransactionCount, getConnectionDialect, getConnectionProperties, getDatabaseDialect, getDatabaseInfo, getDatabaseInformationProcessor, getDatabaseWarningCallback, getDescribeDatabaseInfoBlock, getOdsMajor, getOdsMinor, getParameterDescriptionInfoRequestItems, getStatementInfoRequestItems, removeDatabaseListener, setDatabaseDialect, setOdsMajor, setOdsMinor, transactionAdded, transactionStateChanged`

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

      `addExceptionListener, forceClose, getDatatypeCoder, getEncoding, getEncodingFactory, getServerVersion, getServerVersionInformation, isAttached, isLockedByCurrentThread, removeExceptionListener, safelyDetach, setAttached, setDetached, setServerVersion, withLock`

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

      `addExceptionListener, removeExceptionListener`

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

      `close, forceClose, getDatatypeCoder, getEncoding, getEncodingFactory, getServerVersion, isAttached, isLockedByCurrentThread, withLock`

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

      `createBlobForInput, createBlobForInput, createBlobForOutput, createBlobForOutput`

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

      `transactionStateChanged`

- - ### Field Detail

    - #### STATUS_VECTOR_SIZE

          public static final int STATUS_VECTOR_SIZE

      See Also:
        Constant Field Values

    - #### MAX_STATEMENT_LENGTH

          public static final int MAX_STATEMENT_LENGTH

      See Also:
        Constant Field Values

    - #### handle

          protected final com.sun.jna.ptr.IntByReference handle

    - #### statusVector

          protected final ISC_STATUS[] statusVector

  - ### Constructor Detail

    - #### JnaDatabase

          public JnaDatabase​(JnaDatabaseConnection connection)

  - ### Method Detail

    - #### getClientLibrary

          protected final FbClientLibrary getClientLibrary()

      Returns:
        The client library instance associated with the database.

    - #### checkConnected

          protected void checkConnected()
                                 throws java.sql.SQLException

      Description copied from class: `AbstractFbAttachment`
      Checks if the attachment is connected, and throws a `SQLException` if it isn't connected.
      Specified by:
        `checkConnected` in class `AbstractFbAttachment<JnaDatabaseConnection>`
      Throws:
        `java.sql.SQLException`

    - #### internalDetach

          protected void internalDetach()
                                 throws java.sql.SQLException

      Description copied from class: `AbstractFbDatabase`
      Actual implementation of database detach.

      Implementations of this method should only be called from `AbstractFbDatabase.close()`, and should not notify database listeners of the database `DatabaseListener.detaching(FbDatabase)` and `DatabaseListener.detached(FbDatabase)` events.

      Specified by:
        `internalDetach` in class `AbstractFbDatabase<JnaDatabaseConnection>`
      Throws:
        `java.sql.SQLException`

    - #### attach

          public void attach()
                      throws java.sql.SQLException

      Description copied from interface: `FbAttachment`
      Attach to the attachment type.
      Specified by:
        `attach` in interface `FbAttachment`
      Throws:
        `java.sql.SQLException`

    - #### attachOrCreate

          protected void attachOrCreate​(DatabaseParameterBuffer dpb,
                                        boolean create)
                                 throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### afterAttachActions

          protected void afterAttachActions()
                                     throws java.sql.SQLException

      Additional tasks to execute directly after attach operation.

      Implementation retrieves database information like dialect ODS and server version.

      Throws:
        `java.sql.SQLException` - For errors reading or writing database information.

    - #### createDatabase

          public void createDatabase()
                              throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Creates a new database, connection remains attached to database.
      Specified by:
        `createDatabase` in interface `FbDatabase`
      Throws:
        `java.sql.SQLException`

    - #### dropDatabase

          public void dropDatabase()
                            throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Drops (and deletes) the currently attached database.
      Specified by:
        `dropDatabase` in interface `FbDatabase`
      Throws:
        `java.sql.SQLException`

    - #### cancelOperation

          public void cancelOperation​(int kind)
                               throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Cancels the current operation.

      The cancellation types are:

      `ISCConstants.fb_cancel_disable`
        disables execution of fb_cancel_raise requests for the specified attachment. It can be useful when your program is executing critical operations, such as cleanup, for example.
      `ISCConstants.fb_cancel_enable`
        re-enables delivery of a cancel execution that was previously disabled. The 'cancel' state is effective by default, being initialized when the attachment is created.
      `ISCConstants.fb_cancel_raise`
        cancels any activity related to the database handle. The effect will be that, as soon as possible, the engine will try to stop the running request and return an exception to the caller
      `ISCConstants.fb_cancel_abort`
        forcibly close client side of connection. Useful if you need to close a connection urgently. All active transactions will be rolled back by the server. 'Success' is always returned to the application. Use with care!
      Specified by:
        `cancelOperation` in interface `FbDatabase`
      Parameters:
        `kind` - Cancellation type
      Throws:
        `java.sql.SQLException` - For errors cancelling, or if the cancel operation is not supported.

    - #### startTransaction

          public JnaTransaction startTransaction​(TransactionParameterBuffer tpb)
                                          throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Creates and starts a transaction.
      Specified by:
        `startTransaction` in interface `FbDatabase`
      Parameters:
        `tpb` - TransactionParameterBuffer with the required transaction options
      Returns:
        FbTransaction
      Throws:
        `java.sql.SQLException`

    - #### reconnectTransaction

          public FbTransaction reconnectTransaction​(long transactionId)
                                             throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Reconnects a prepared transaction.

      Reconnecting transactions is only allowed for transactions in limbo (prepared, but not committed or rolled back).

      Specified by:
        `reconnectTransaction` in interface `FbDatabase`
      Parameters:
        `transactionId` - The id of the transaction to reconnect.
      Returns:
        FbTransaction
      Throws:
        `java.sql.SQLException` - For errors reconnecting the transaction

    - #### getTransactionIdBuffer

          protected byte[] getTransactionIdBuffer​(long transactionId)

    - #### createStatement

          public JnaStatement createStatement​(FbTransaction transaction)
                                       throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Creates a statement associated with a transaction
      Specified by:
        `createStatement` in interface `FbDatabase`
      Parameters:
        `transaction` - FbTransaction to associate with this statement (can be `null`)
      Returns:
        FbStatement
      Throws:
        `java.sql.SQLException`

    - #### createBlobForOutput

          public FbBlob createBlobForOutput​(FbTransaction transaction,
                                            BlobParameterBuffer blobParameterBuffer)

      Description copied from interface: `FbDatabase`
      Creates a blob for write access to a new blob on the server.

      The blob is initially closed.

      Specified by:
        `createBlobForOutput` in interface `FbDatabase`
      Parameters:
        `transaction` - transaction associated with the blob
        `blobParameterBuffer` - blob parameter buffer
      Returns:
        instance of `FbBlob`

    - #### createBlobForInput

          public FbBlob createBlobForInput​(FbTransaction transaction,
                                           BlobParameterBuffer blobParameterBuffer,
                                           long blobId)

      Description copied from interface: `FbDatabase`
      Creates a blob for read access to an existing blob on the server.

      The blob is initially closed.

      Specified by:
        `createBlobForInput` in interface `FbDatabase`
      Parameters:
        `transaction` - transaction associated with the blob
        `blobParameterBuffer` - blob parameter buffer
        `blobId` - id of the blob
      Returns:
        instance of `FbBlob`

    - #### getDatabaseInfo

          public byte[] getDatabaseInfo​(byte[] requestItems,
                                        int maxBufferLength)
                                 throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Performs a database info request.
      Specified by:
        `getDatabaseInfo` in interface `FbDatabase`
      Parameters:
        `requestItems` - Information items to request
        `maxBufferLength` - Maximum response buffer length to use
      Returns:
        The response buffer (note: length is the actual length of the response, not `maxBufferLength`
      Throws:
        `java.sql.SQLException` - For errors retrieving the information.

    - #### executeImmediate

          public void executeImmediate​(java.lang.String statementText,
                                       FbTransaction transaction)
                                throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Performs an execute immediate of a statement.

      A call to this method is the equivalent of a `isc_dsql_execute_immediate()` without parameters.

      Specified by:
        `executeImmediate` in interface `FbDatabase`
      Parameters:
        `statementText` - Statement text
        `transaction` - Transaction (`null` only allowed if database is not attached!)
      Throws:
        `java.sql.SQLException` - For errors executing the statement, or if `transaction` is `null` when the database is attached or not `null` when the database is not attached

    - #### getHandle

          public int getHandle()

      Specified by:
        `getHandle` in interface `FbAttachment`
      Specified by:
        `getHandle` in interface `FbDatabase`
      Returns:
        The attachment handle value

    - #### setNetworkTimeout

          public void setNetworkTimeout​(int milliseconds)
                                 throws java.sql.SQLException

      Description copied from interface: `FbAttachment`
      Sets the network timeout for this attachment.
      Specified by:
        `setNetworkTimeout` in interface `FbAttachment`
      Parameters:
        `milliseconds` - Timeout in milliseconds; 0 means no timeout. If the attachment doesn't support milliseconds, it should round up to the nearest second.
      Throws:
        `java.sql.SQLException` - If this attachment is closed, the value of `milliseconds` is smaller than 0, or if setting the timeout fails.
        `java.sql.SQLFeatureNotSupportedException` - If this attachment doesn't support (changing) the network timeout.

    - #### getNetworkTimeout

          public int getNetworkTimeout()
                                throws java.sql.SQLException

      Description copied from interface: `FbAttachment`
      Gets the current network timeout for this attachment.
      Specified by:
        `getNetworkTimeout` in interface `FbAttachment`
      Overrides:
        `getNetworkTimeout` in class `AbstractFbAttachment<JnaDatabaseConnection>`
      Returns:
        Timeout in milliseconds, 0 means no timeout
      Throws:
        `java.sql.SQLException` - If this attachment is closed
        `java.sql.SQLFeatureNotSupportedException` - If this attachment doesn't support network timeout

    - #### getJnaHandle

          public com.sun.jna.ptr.IntByReference getJnaHandle()

    - #### getEncodingDefinition

          public final EncodingDefinition getEncodingDefinition()

    - #### validateEventHandle

          protected JnaEventHandle validateEventHandle​(EventHandle eventHandle)
                                                throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### createEventHandle

          public JnaEventHandle createEventHandle​(java.lang.String eventName,
                                                  EventHandler eventHandler)
                                           throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Creates an event handle for this database type.

      The returned event handle can be used with `FbDatabase.queueEvent(org.firebirdsql.gds.EventHandle)`.

      Specified by:
        `createEventHandle` in interface `FbDatabase`
      Parameters:
        `eventName` - Name of the event
        `eventHandler` - The event handler to call when the event occurred
      Returns:
        A suitable event handle instance
      Throws:
        `java.sql.SQLException` - For errors creating the event handle

    - #### countEvents

          public void countEvents​(EventHandle eventHandle)
                           throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Counts the events occurred.
      Specified by:
        `countEvents` in interface `FbDatabase`
      Parameters:
        `eventHandle` - The event handle
      Throws:
        `java.sql.SQLException` - When the count can not be done (as - for example - the event handle is of the wrong type)

    - #### queueEvent

          public void queueEvent​(EventHandle eventHandle)
                          throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Queues a wait for an event.
      Specified by:
        `queueEvent` in interface `FbDatabase`
      Parameters:
        `eventHandle` - The event handle (created using `FbDatabase.createEventHandle(String, EventHandler)` of this instance).
      Throws:
        `java.sql.SQLException` - For errors establishing the asynchronous channel, or for queuing the event.

    - #### cancelEvent

          public void cancelEvent​(EventHandle eventHandle)
                           throws java.sql.SQLException

      Description copied from interface: `FbDatabase`
      Cancels a registered event.

      After cancellation, the event handle should be considered unusable. Before queueing a new event, an new handle needs to be created.

      Specified by:
        `cancelEvent` in interface `FbDatabase`
      Parameters:
        `eventHandle` - The event handle to cancel
      Throws:
        `java.sql.SQLException` - For errors cancelling the event

    - #### processStatusVector

          public void processStatusVector​(ISC_STATUS[] statusVector,
                                          WarningMessageCallback warningMessageCallback)
                                   throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

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

    - #### hasFeature

          public boolean hasFeature​(FbClientFeature clientFeature)

      Description copied from interface: `FbClientFeatureAccess`
      Checks for presence of a client feature.
      Specified by:
        `hasFeature` in interface `FbClientFeatureAccess`
      Parameters:
        `clientFeature` - Client feature
      Returns:
        `true` if the feature is present, `false` otherwise

    - #### getFeatures

          public java.util.Set<FbClientFeature> getFeatures()

      Specified by:
        `getFeatures` in interface `FbClientFeatureAccess`
      Returns:
        an unmodifiable set with supported client features