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
`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
`JnaDatabase​(JnaDatabaseConnection connection)`

### Method Summary

All Methods Instance Methods Concrete Methods
`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)
                               throws java.sql.SQLException

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`
Throws:
  `java.sql.SQLException` - if the database is not attached or the transaction is not active

#### createBlobForInput

    public FbBlob createBlobForInput​(FbTransaction transaction,
                                     BlobParameterBuffer blobParameterBuffer,
                                     long blobId)
                              throws java.sql.SQLException

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`
Throws:
  `java.sql.SQLException` - if the database is not attached or the transaction is not active

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