Interface FbDatabase

All Superinterfaces:
AutoCloseable, ExceptionListenable, FbAttachment
All Known Subinterfaces:
FbWireDatabase
All Known Implementing Classes:
AbstractFbDatabase, AbstractFbWireDatabase, V10Database, V11Database, V12Database, V13Database, V15Database, V16Database, V18Database

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

      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)
      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
    • createBlobForOutput

      default FbBlob createBlobForOutput(FbTransaction transaction)
      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
      Since:
      5
    • createBlobForOutput

      default FbBlob createBlobForOutput(FbTransaction transaction, BlobConfig blobConfig)
      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
      Since:
      5
    • createBlobForInput

      FbBlob createBlobForInput(FbTransaction transaction, BlobParameterBuffer blobParameterBuffer, long blobId)
      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
      blobParameterBuffer - blob parameter buffer
      blobId - id of the blob
      Returns:
      instance of FbBlob
    • createBlobForInput

      default FbBlob createBlobForInput(FbTransaction transaction, long blobId)
      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
      Since:
      5
    • createBlobForInput

      default FbBlob createBlobForInput(FbTransaction transaction, BlobConfig blobConfig, long blobId)
      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
      Since:
      5
    • createBlobParameterBuffer

      BlobParameterBuffer createBlobParameterBuffer()
      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.