Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.ng

# Interface FbDatabase

All Superinterfaces:
  `AutoCloseable`, `ExceptionListenable`, `FbAttachment`

All Known Subinterfaces:
  `FbWireDatabase`

All Known Implementing Classes:
  `AbstractFbDatabase`, `AbstractFbWireDatabase`, `V10Database`, `V11Database`, `V12Database`, `V13Database`, `V15Database`, `V16Database`, `V18Database`, `V19Database`

public interface FbDatabase extends FbAttachment
Connection handle to a database.

All methods defined in this interface are required to notify all `SQLException` thrown from the methods defined in this interface, and those exceptions notified by all `ExceptionListenable` implementations created from them.

Since:
  3.0
Author:
  Mark Rotteveel

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDatabaseListener(DatabaseListener listener)`
  Adds a `DatabaseListener` instance to this database.
  `void`
  `addWeakDatabaseListener(DatabaseListener listener)`
  Adds a `DatabaseListener` instance to this database using a weak reference.
  `void`
  `cancelEvent(EventHandle eventHandle)`
  Cancels a registered event.
  `void`
  `cancelOperation(int kind)`
  Cancels the current operation.
  `void`
  `countEvents(EventHandle eventHandle)`
  Counts the events occurred.
  `default FbBlob`
  `createBlobForInput(FbTransaction transaction, long blobId)`
  Creates a blob for read access to an existing blob on the server.
  `FbBlob`
  `createBlobForInput(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer, long blobId)`
  Creates a blob for read access to an existing blob on the server.
  `default FbBlob`
  `createBlobForInput(FbTransaction transaction, BlobConfig blobConfig, long blobId)`
  Creates a blob for read access to an existing blob on the server.
  `default FbBlob`
  `createBlobForOutput(FbTransaction transaction)`
  Creates a blob for write access to a new blob on the server.
  `FbBlob`
  `createBlobForOutput(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer)`
  Creates a blob for write access to a new blob on the server.
  `default FbBlob`
  `createBlobForOutput(FbTransaction transaction, BlobConfig blobConfig)`
  Creates a blob for write access to a new blob on the server.
  `BlobParameterBuffer`
  `createBlobParameterBuffer()`
  Creates a blob parameter buffer that is usable with `createBlobForInput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer, long)` and `createBlobForOutput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer)` of this instance.
  `void`
  `createDatabase()`
  Creates a new database, connection remains attached to database.
  `EventHandle`
  `createEventHandle(String eventName, EventHandler eventHandler)`
  Creates an event handle for this database type.
  `FbStatement`
  `createStatement(FbTransaction transaction)`
  Creates a statement associated with a transaction
  `TransactionParameterBuffer`
  `createTransactionParameterBuffer()`
  Creates a transaction parameter buffer that is usable with `startTransaction(org.firebirdsql.gds.TransactionParameterBuffer)`.
  `void`
  `dropDatabase()`
  Drops (and deletes) the currently attached database.
  `RowDescriptor`
  `emptyRowDescriptor()`
  `void`
  `executeImmediate(String statementText, FbTransaction transaction)`
  Performs an execute immediate of a statement.
  `short`
  `getConnectionDialect()`
  `IConnectionProperties`
  `getConnectionProperties()`
  `short`
  `getDatabaseDialect()`
  `byte[]`
  `getDatabaseInfo(byte[] requestItems, int maxBufferLength)`
  Performs a database info request.
  `<T> T`
  `getDatabaseInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)`
  Request database info.
  `int`
  `getHandle()`
  `int`
  `getOdsMajor()`
  `int`
  `getOdsMinor()`
  `default OdsVersion`
  `getOdsVersion()`
  `void`
  `queueEvent(EventHandle eventHandle)`
  Queues a wait for an event.
  `FbTransaction`
  `reconnectTransaction(long transactionId)`
  Reconnects a prepared transaction.
  `void`
  `removeDatabaseListener(DatabaseListener listener)`
  Removes a `DatabaseListener` instance from this database.
  `FbTransaction`
  `startTransaction(String statementText)`
  Creates and starts a transaction using a SQL statement
  `FbTransaction`
  `startTransaction(TransactionParameterBuffer tpb)`
  Creates and starts a transaction.

  ### Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable

  `addExceptionListener, removeExceptionListener`

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

  `attach, close, forceClose, getDatatypeCoder, getEncoding, getEncodingFactory, getNetworkTimeout, getServerVersion, isAttached, isLockedByCurrentThread, setNetworkTimeout, withLock`

- ## Method Details

  - ### createDatabase

    void createDatabase() throws SQLException
    Creates a new database, connection remains attached to database.
    Throws:
      `SQLException`

  - ### dropDatabase

    void dropDatabase() throws SQLException
    Drops (and deletes) the currently attached database.
    Throws:
      `SQLException`

  - ### cancelOperation

    void cancelOperation(int kind) throws SQLException
    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!
    Parameters:
      `kind` - Cancellation type
    Throws:
      `SQLException` - For errors cancelling, or if the cancel operation is not supported.

  - ### startTransaction

    FbTransaction startTransaction(TransactionParameterBuffer tpb) throws SQLException
    Creates and starts a transaction.
    Parameters:
      `tpb` - TransactionParameterBuffer with the required transaction options
    Returns:
      FbTransaction
    Throws:
      `SQLException`

  - ### startTransaction

    FbTransaction startTransaction(String statementText) throws SQLException
    Creates and starts a transaction using a SQL statement
    Parameters:
      `statementText` - statement which starts a transaction
    Returns:
      FbTransaction
    Throws:
      `SQLException` - for database access error
    Since:
      6

  - ### reconnectTransaction

    FbTransaction reconnectTransaction(long transactionId) throws SQLException
    Reconnects a prepared transaction.

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

    Parameters:
      `transactionId` - The id of the transaction to reconnect.
    Returns:
      FbTransaction
    Throws:
      `SQLException` - For errors reconnecting the transaction

  - ### createStatement

    FbStatement createStatement(FbTransaction transaction) throws SQLException
    Creates a statement associated with a transaction
    Parameters:
      `transaction` - FbTransaction to associate with this statement (can be `null`)
    Returns:
      FbStatement
    Throws:
      `SQLException`

  - ### createBlobForOutput

    FbBlob createBlobForOutput(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer) throws SQLException
    Creates a blob for write access to a new blob on the server.

    The blob is initially closed.

    Parameters:
      `transaction` - transaction associated with the blob
      `blobParameterBuffer` - blob parameter buffer
    Returns:
      instance of `FbBlob`
    Throws:
      `SQLException` - if the database is not attached or the transaction is not active

  - ### createBlobForOutput

    default FbBlob createBlobForOutput(FbTransaction transaction) throws SQLException
    Creates a blob for write access to a new blob on the server.

    The blob is initially closed.

    Equivalent to calling `createBlobForOutput(FbTransaction, BlobParameterBuffer)` with `null` for `blobParameterBuffer`.

    Parameters:
      `transaction` - transaction associated with the blob
    Returns:
      instance of `FbBlob`
    Throws:
      `SQLException` - if the database is not attached or the transaction is not active
    Since:
      5

  - ### createBlobForOutput

    default FbBlob createBlobForOutput(FbTransaction transaction, BlobConfig blobConfig) throws SQLException
    Creates a blob for write access to a new blob on the server.

    The blob is initially closed.

    Parameters:
      `transaction` - transaction associated with the blob
      `blobConfig` - blob config (cannot be `null`)
    Returns:
      instance of `FbBlob`
    Throws:
      `SQLException` - if the database is not attached or the transaction is not active
    Since:
      5

  - ### createBlobForInput

    FbBlob createBlobForInput(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer, long blobId) throws SQLException
    Creates a blob for read access to an existing blob on the server.

    The blob is initially closed.

    If the server supports inline blobs, a locally cached blob may be returned if an inline blob was received for `transaction` and `blobId`, and if `blobParameterBuffer` is `null` or empty (`ParameterBuffer.isEmpty()`).

    Parameters:
      `transaction` - transaction associated with the blob
      `blobParameterBuffer` - blob parameter buffer
      `blobId` - id of the blob
    Returns:
      instance of `FbBlob`
    Throws:
      `SQLException` - if the database is not attached or the transaction is not active

  - ### createBlobForInput

    default FbBlob createBlobForInput(FbTransaction transaction, long blobId) throws SQLException
    Creates a blob for read access to an existing blob on the server.

    The blob is initially closed.

    Equivalent to calling `createBlobForInput(FbTransaction, BlobParameterBuffer, long)` with `null` for `blobParameterBuffer`.

    Parameters:
      `transaction` - transaction associated with the blob
      `blobId` - id of the blob
    Returns:
      instance of `FbBlob`
    Throws:
      `SQLException` - if the database is not attached or the transaction is not active
    Since:
      5

  - ### createBlobForInput

    default FbBlob createBlobForInput(FbTransaction transaction, BlobConfig blobConfig, long blobId) throws SQLException
    Creates a blob for read access to an existing blob on the server.

    The blob is initially closed.

    Parameters:
      `transaction` - transaction associated with the blob
      `blobConfig` - blob config (cannot be `null`)
      `blobId` - handle id of the blob
    Returns:
      instance of `FbBlob`
    Throws:
      `SQLException` - if the database is not attached or the transaction is not active
    Since:
      5

  - ### createBlobParameterBuffer

    BlobParameterBuffer createBlobParameterBuffer()
    Creates a blob parameter buffer that is usable with `createBlobForInput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer, long)` and `createBlobForOutput(FbTransaction, org.firebirdsql.gds.BlobParameterBuffer)` of this instance.
    Returns:
      A blob parameter buffer.

  - ### createTransactionParameterBuffer

    TransactionParameterBuffer createTransactionParameterBuffer()
    Creates a transaction parameter buffer that is usable with `startTransaction(org.firebirdsql.gds.TransactionParameterBuffer)`.
    Returns:
      A transaction parameter buffer

  - ### getDatabaseInfo

    <T> T getDatabaseInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws SQLException
    Request database 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:
      `SQLException` - For errors retrieving or transforming the response.

  - ### getDatabaseInfo

    byte[] getDatabaseInfo(byte[] requestItems, int maxBufferLength) throws SQLException
    Performs a database info request.
    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:
      `SQLException` - For errors retrieving the information.

  - ### executeImmediate

    void executeImmediate(String statementText, FbTransaction transaction) throws SQLException
    Performs an execute immediate of a statement.

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

    Parameters:
      `statementText` - Statement text
      `transaction` - Transaction (`null` only allowed if database is not attached!)
    Throws:
      `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

  - ### getDatabaseDialect

    short getDatabaseDialect()
    Returns:
      The database dialect

  - ### getConnectionDialect

    short getConnectionDialect()
    Returns:
      The client connection dialect

  - ### getHandle

    int getHandle()
    Specified by:
      `getHandle` in interface `FbAttachment`
    Returns:
      The database handle value

  - ### getOdsMajor

    int getOdsMajor()
    Returns:
      ODS major version

  - ### getOdsMinor

    int getOdsMinor()
    Returns:
      ODS minor version

  - ### getOdsVersion

    default OdsVersion getOdsVersion()
    Returns:
      ODS version
    Since:
      6

  - ### addDatabaseListener

    void addDatabaseListener(DatabaseListener listener)
    Adds a `DatabaseListener` instance to this database.
    Parameters:
      `listener` - Database listener

  - ### addWeakDatabaseListener

    void addWeakDatabaseListener(DatabaseListener listener)
    Adds a `DatabaseListener` instance to this database using a weak reference.

    If the listener is already strongly referenced, this call will be ignored

    Parameters:
      `listener` - Database listener

  - ### removeDatabaseListener

    void removeDatabaseListener(DatabaseListener listener)
    Removes a `DatabaseListener` instance from this database.
    Parameters:
      `listener` - Database Listener

  - ### createEventHandle

    EventHandle createEventHandle(String eventName, EventHandler eventHandler) throws SQLException
    Creates an event handle for this database type.

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

    Parameters:
      `eventName` - Name of the event
      `eventHandler` - The event handler to call when the event occurred
    Returns:
      A suitable event handle instance
    Throws:
      `SQLException` - For errors creating the event handle

  - ### countEvents

    void countEvents(EventHandle eventHandle) throws SQLException
    Counts the events occurred.
    Parameters:
      `eventHandle` - The event handle
    Throws:
      `SQLException` - When the count can not be done (as - for example - the event handle is of the wrong type)

  - ### queueEvent

    void queueEvent(EventHandle eventHandle) throws SQLException
    Queues a wait for an event.
    Parameters:
      `eventHandle` - The event handle (created using `createEventHandle(String, EventHandler)` of this instance).
    Throws:
      `SQLException` - For errors establishing the asynchronous channel, or for queuing the event.

  - ### cancelEvent

    void cancelEvent(EventHandle eventHandle) throws SQLException
    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.

    Parameters:
      `eventHandle` - The event handle to cancel
    Throws:
      `SQLException` - For errors cancelling the event

  - ### getConnectionProperties

    IConnectionProperties getConnectionProperties()
    Returns:
      An immutable copy of the connection properties of this database

  - ### emptyRowDescriptor

    RowDescriptor emptyRowDescriptor()
    Returns:
      A potentially cached empty row descriptor for this database.