Package org.firebirdsql.gds.ng

Interface FbDatabase

    • Method Detail

      • createDatabase

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

      • dropDatabase

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

      • cancelOperation

        void cancelOperation​(int kind)
              throws java.sql.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:
        java.sql.SQLException - For errors cancelling, or if the cancel operation is not supported.

      • startTransaction

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

      • reconnectTransaction

        FbTransaction reconnectTransaction​(long transactionId)
                            throws java.sql.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:
        java.sql.SQLException - For errors reconnecting the transaction

      • createStatement

        FbStatement createStatement​(FbTransaction transaction)
                     throws java.sql.SQLException
        Creates a statement associated with a transaction
        Parameters:
        transaction - FbTransaction to associate with this statement (can be null)
        Returns:
        FbStatement
        Throws:
        java.sql.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,
                                   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

      • getDatabaseInfo

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

      • getDatabaseInfo

        byte[] getDatabaseInfo​(byte[] requestItems,
                       int maxBufferLength)
                throws java.sql.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:
        java.sql.SQLException - For errors retrieving the information.

      • executeImmediate

        void executeImmediate​(java.lang.String statementText,
                      FbTransaction transaction)
               throws java.sql.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:
        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

      • 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

      • 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​(java.lang.String eventName,
                              EventHandler eventHandler)
                       throws java.sql.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:
        java.sql.SQLException - For errors creating the event handle

      • countEvents

        void countEvents​(EventHandle eventHandle)
          throws java.sql.SQLException
        Counts the events occurred.
        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

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

      • cancelEvent

        void cancelEvent​(EventHandle eventHandle)
          throws java.sql.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:
        java.sql.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.