Package org.firebirdsql.gds.ng.wire

## Class AbstractFbWireDatabase

- java.lang.Object
- - org.firebirdsql.gds.ng.AbstractFbAttachment<T>
  - - org.firebirdsql.gds.ng.AbstractFbDatabase<WireDatabaseConnection>
    - - org.firebirdsql.gds.ng.wire.AbstractFbWireDatabase

- All Implemented Interfaces:
    `java.lang.AutoCloseable`, `FbAttachment`, `FbDatabase`, `ExceptionListenable`, `TransactionListener`, `FbWireAttachment`, `FbWireDatabase`
  Direct Known Subclasses:
    `V10Database`

      public abstract class AbstractFbWireDatabase
      extends AbstractFbDatabase<WireDatabaseConnection>
      implements FbWireDatabase

  Abstract class for operations common to all version of the wire protocol implementation.
  Since:
    3.0
  Author:
    Mark Rotteveel

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.firebirdsql.gds.ng.wire.FbWireAttachment

      `FbWireAttachment.AcceptPacket`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected ProtocolDescriptor` | `protocolDescriptor` |
    `protected FbWireOperations` | `wireOperations` |

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

      `databaseListenerDispatcher`

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

      `connection, exceptionListenerDispatcher`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractFbWireDatabase​(WireDatabaseConnection connection, ProtocolDescriptor descriptor)` | Creates an AbstractFbWireDatabase instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `cancelEvent​(EventHandle eventHandle)` | Cancels a registered event.
    `protected void` | `checkAttached()` | Checks if a physical connection to the server is established and if the connection is attached to a database.
    `protected void` | `checkConnected()` | Checks if a physical connection to the server is established.
    `protected void` | `closeConnection()` | Closes the WireConnection associated with this connection.
    `void` | `consumePackets​(int numberOfResponses, WarningMessageCallback warningCallback)` | Consumes packets notifying for warnings, but ignoring exceptions thrown from the packet.
    `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.
    `EventHandle` | `createEventHandle​(java.lang.String eventName, EventHandler eventHandler)` | Creates an event handle for this database type.
    `void` | `enqueueDeferredAction​(DeferredAction deferredAction)` | Enqueue a deferred action.
    `protected void` | `finalize()` |
    `void` | `forceClose()` | Forces the connection to close without proper detach or cleanup.
    `byte[]` | `getDatabaseInfo​(byte[] requestItems, int maxBufferLength)` | Performs a database info request.
    `int` | `getHandle()` |
    `byte[]` | `getInfo​(int operation, int handle, byte[] requestItems, int maxBufferLength, WarningMessageCallback warningMessageCallback)` | Generic info request.
    `protected XdrInputStream` | `getXdrIn()` | Gets the XdrInputStream.
    `protected XdrOutputStream` | `getXdrOut()` | Gets the XdrOutputStream.
    `XdrStreamAccess` | `getXdrStreamAccess()` |
    `abstract FbWireAsynchronousChannel` | `initAsynchronousChannel()` | Initializes the asynchronous channel (for event notification).
    `boolean` | `isAttached()` | Current attachment status.
    `void` | `queueEvent​(EventHandle eventHandle)` | Queues a wait for an event.
    `GenericResponse` | `readGenericResponse​(WarningMessageCallback warningCallback)` | Convenience method to read a Response to a GenericResponse
    `Response` | `readResponse​(WarningMessageCallback warningCallback)` | Reads the response from the server.
    `SqlResponse` | `readSqlResponse​(WarningMessageCallback warningCallback)` | Convenience method to read a Response to a SqlResponse
    `void` | `setNetworkTimeout​(int milliseconds)` | Sets the network timeout for this attachment.

    - ### 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, internalDetach, removeDatabaseListener, setDatabaseDialect, setOdsMajor, setOdsMinor, transactionAdded, transactionStateChanged`

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

      `addExceptionListener, getDatatypeCoder, getEncoding, getEncodingFactory, getNetworkTimeout, getServerVersion, getServerVersionInformation, 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

      `attach, close, getDatatypeCoder, getEncoding, getEncodingFactory, getNetworkTimeout, getServerVersion, isLockedByCurrentThread, withLock`

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

      `addDatabaseListener, addWeakDatabaseListener, cancelOperation, createBlobForInput, createBlobForInput, createBlobForOutput, createBlobForOutput, createBlobParameterBuffer, createDatabase, createStatement, createTransactionParameterBuffer, dropDatabase, emptyRowDescriptor, executeImmediate, getConnectionDialect, getConnectionProperties, getDatabaseDialect, getDatabaseInfo, getOdsMajor, getOdsMinor, reconnectTransaction, removeDatabaseListener, startTransaction`

    - ### Methods inherited from interface org.firebirdsql.gds.ng.wire.FbWireAttachment

      `authReceiveResponse`

    - ### Methods inherited from interface org.firebirdsql.gds.ng.wire.FbWireDatabase

      `getBlrCalculator, releaseObject`

- - ### Field Detail

    - #### protocolDescriptor

          protected final ProtocolDescriptor protocolDescriptor

    - #### wireOperations

          protected final FbWireOperations wireOperations

  - ### Constructor Detail

    - #### AbstractFbWireDatabase

          protected AbstractFbWireDatabase​(WireDatabaseConnection connection,
                                           ProtocolDescriptor descriptor)

      Creates an AbstractFbWireDatabase instance.
      Parameters:
        `connection` - A WireConnection with an established connection to the server.
        `descriptor` - The ProtocolDescriptor that created this connection (this is used for creating further dependent objects).

  - ### Method Detail

    - #### getHandle

          public final int getHandle()

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

    - #### forceClose

          public void forceClose()
                          throws java.sql.SQLException

      Description copied from class: `AbstractFbAttachment`
      Forces the connection to close without proper detach or cleanup.

      If a given implementation does not support this, then this method should call `FbAttachment.close()`.

      Default implementation, calls `FbAttachment.close()`

      Specified by:
        `forceClose` in interface `FbAttachment`
      Overrides:
        `forceClose` in class `AbstractFbAttachment<WireDatabaseConnection>`
      Throws:
        `java.sql.SQLException` - For problems closing the connection.

    - #### getXdrIn

          protected final XdrInputStream getXdrIn()
                                           throws java.sql.SQLException

      Gets the XdrInputStream.
      Returns:
        Instance of XdrInputStream
      Throws:
        `java.sql.SQLException` - If no connection is opened or when exceptions occur retrieving the InputStream

    - #### getXdrOut

          protected final XdrOutputStream getXdrOut()
                                             throws java.sql.SQLException

      Gets the XdrOutputStream.
      Returns:
        Instance of XdrOutputStream
      Throws:
        `java.sql.SQLException` - If no connection is opened or when exceptions occur retrieving the OutputStream

    - #### getXdrStreamAccess

          public final XdrStreamAccess getXdrStreamAccess()

      Specified by:
        `getXdrStreamAccess` in interface `FbWireAttachment`
      Returns:
        Instance of `XdrStreamAccess` for this attachment.

    - #### isAttached

          public final boolean isAttached()

      Description copied from interface: `FbAttachment`
      Current attachment status.
      Specified by:
        `isAttached` in interface `FbAttachment`
      Overrides:
        `isAttached` in class `AbstractFbAttachment<WireDatabaseConnection>`
      Returns:
        `true` if connected to the server and attached to a database or service, `false` otherwise.

    - #### checkConnected

          protected final void checkConnected()
                                       throws java.sql.SQLException

      Checks if a physical connection to the server is established.
      Specified by:
        `checkConnected` in class `AbstractFbAttachment<WireDatabaseConnection>`
      Throws:
        `java.sql.SQLException` - If not connected.

    - #### checkAttached

          protected final void checkAttached()
                                      throws java.sql.SQLException

      Checks if a physical connection to the server is established and if the connection is attached to a database.

      This method calls `checkConnected()`, so it is not necessary to call both.

      Throws:
        `java.sql.SQLException` - If the database not connected or attached.

    - #### closeConnection

          protected final void closeConnection()
                                        throws java.io.IOException

      Closes the WireConnection associated with this connection.
      Throws:
        `java.io.IOException` - For errors closing the connection.

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

    - #### createBlobForOutput

          public final 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 final 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`

    - #### consumePackets

          public final void consumePackets​(int numberOfResponses,
                                           WarningMessageCallback warningCallback)

      Description copied from interface: `FbWireDatabase`
      Consumes packets notifying for warnings, but ignoring exceptions thrown from the packet.

      This method should only be used inside the implementation if either packets need to be ignored, or to ensure that there is no backlog of packets (eg when an exception occurs during processing of multiple package responses).

      Specified by:
        `consumePackets` in interface `FbWireDatabase`
      Parameters:
        `numberOfResponses` - Number of responses to consume.
        `warningCallback` - Callback for warnings

    - #### readGenericResponse

          public final GenericResponse readGenericResponse​(WarningMessageCallback warningCallback)
                                                    throws java.sql.SQLException,
                                                           java.io.IOException

      Description copied from interface: `FbWireAttachment`
      Convenience method to read a Response to a GenericResponse
      Specified by:
        `readGenericResponse` in interface `FbWireAttachment`
      Parameters:
        `warningCallback` - Callback object for warnings, `null` for default callback
      Returns:
        GenericResponse
      Throws:
        `java.sql.SQLException` - For errors returned from the server, or when attempting to read.
        `java.io.IOException` - For errors reading the response from the connection.

    - #### readSqlResponse

          public final SqlResponse readSqlResponse​(WarningMessageCallback warningCallback)
                                            throws java.sql.SQLException,
                                                   java.io.IOException

      Description copied from interface: `FbWireDatabase`
      Convenience method to read a Response to a SqlResponse
      Specified by:
        `readSqlResponse` in interface `FbWireDatabase`
      Parameters:
        `warningCallback` - Callback object for warnings, `null` for default callback
      Returns:
        SqlResponse
      Throws:
        `java.sql.SQLException` - For errors returned from the server, or when attempting to read.
        `java.io.IOException` - For errors reading the response from the connection.

    - #### readResponse

          public final Response readResponse​(WarningMessageCallback warningCallback)
                                      throws java.sql.SQLException,
                                             java.io.IOException

      Description copied from interface: `FbWireDatabase`
      Reads the response from the server.
      Specified by:
        `readResponse` in interface `FbWireDatabase`
      Parameters:
        `warningCallback` - Callback object for warnings, `null` for default callback
      Returns:
        `Response` read.
      Throws:
        `java.sql.SQLException` - For errors returned from the server, or when attempting to read
        `java.io.IOException` - For errors reading the response from the connection.

    - #### enqueueDeferredAction

          public final void enqueueDeferredAction​(DeferredAction deferredAction)

      Description copied from interface: `FbWireDatabase`
      Enqueue a deferred action.

      FbDatabase implementations that do not support deferred actions are allowed to throw an `UnsupportedOperationException`

      Specified by:
        `enqueueDeferredAction` in interface `FbWireDatabase`
      Parameters:
        `deferredAction` - Deferred action

    - #### createEventHandle

          public final EventHandle createEventHandle​(java.lang.String eventName,
                                                     EventHandler eventHandler)

      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

    - #### queueEvent

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

    - #### countEvents

          public final 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)

    - #### getDatabaseInfo

          public final 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.

    - #### getInfo

          public byte[] getInfo​(int operation,
                                int handle,
                                byte[] requestItems,
                                int maxBufferLength,
                                WarningMessageCallback warningMessageCallback)
                         throws java.sql.SQLException

      Description copied from interface: `FbWireDatabase`
      Generic info request.

      The implementation does not perform handle validation nor notification of error dispatchers. Doing that is the responsibility of the caller.

      Specified by:
        `getInfo` in interface `FbWireDatabase`
      Parameters:
        `operation` - Operation code
        `handle` - Handle (db, transaction, statement, blob, etc)
        `requestItems` - Information items to request
        `maxBufferLength` - Maximum response buffer length to use
        `warningMessageCallback` - Callback for warnings when reading the response (can be `null` to use database default)
      Returns:
        The response buffer (note: length is the actual length of the response, not `maxBufferLength`)
      Throws:
        `java.sql.SQLException` - For errors retrieving the information

    - #### initAsynchronousChannel

          public abstract FbWireAsynchronousChannel initAsynchronousChannel()
                                                                     throws java.sql.SQLException

      Initializes the asynchronous channel (for event notification).
      Throws:
        `java.sql.SQLException` - For errors establishing the channel, or if the channel already exists.

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

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