Package org.firebirdsql.gds.ng

## Class AbstractFbBlob

- java.lang.Object
- - org.firebirdsql.gds.ng.AbstractFbBlob

- All Implemented Interfaces:
    `java.lang.AutoCloseable`, `FbBlob`, `DatabaseListener`, `ExceptionListenable`, `TransactionListener`
  Direct Known Subclasses:
    `AbstractFbWireBlob`, `JnaBlob`

      public abstract class AbstractFbBlob
      extends java.lang.Object
      implements FbBlob, TransactionListener, DatabaseListener

  Since:
    3.0
  Author:
    Mark Rotteveel

- - ### Nested Class Summary

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

      `FbBlob.SeekMode`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected ExceptionListenerDispatcher` | `exceptionListenerDispatcher` |

    - ### Fields inherited from interface org.firebirdsql.gds.ng.FbBlob

      `NO_BLOB_ID`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractFbBlob​(FbDatabase database, FbTransaction transaction, BlobParameterBuffer blobParameterBuffer)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addExceptionListener​(ExceptionListener listener)` | Adds an exception listener to this object.
    `void` | `cancel()` | Cancels an output blob (which means its contents will be thrown away).
    `protected abstract void` | `cancelImpl()` | Internal implementation of `cancel()`.
    `protected void` | `checkBlobClosed()` |
    `protected void` | `checkBlobOpen()` |
    `protected void` | `checkDatabaseAttached()` |
    `protected void` | `checkTransactionActive()` |
    `protected void` | `clearDatabase()` |
    `protected void` | `clearTransaction()` |
    `void` | `close()` | Closes the blob.
    `protected abstract void` | `closeImpl()` | Internal implementation of `close()`.
    `protected BlobLengthProcessor` | `createBlobLengthProcessor()` |
    `void` | `detached​(FbDatabase database)` | Called when the `database` connection has been detached
    `void` | `detaching​(FbDatabase database)` | Called before the `database` will be detached.
    `<T> T` | `getBlobInfo​(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)` | Request blob info.
    `protected BlobParameterBuffer` | `getBlobParameterBuffer()` |
    `FbDatabase` | `getDatabase()` |
    `int` | `getMaximumSegmentSize()` | The maximum segment size allowed by the protocol for `FbBlob.getSegment(int)` and `FbBlob.putSegment(byte[])`.
    `protected FbTransaction` | `getTransaction()` |
    `protected boolean` | `isEndingTransaction()` |
    `boolean` | `isEof()` |
    `boolean` | `isOpen()` |
    `long` | `length()` | Requests the blob length from the server.
    `protected abstract void` | `releaseResources()` | Release Java resources held.
    `void` | `removeExceptionListener​(ExceptionListener listener)` | Removes an exception listener to this object.
    `protected void` | `resetEof()` | Resets the eof state of the blob to false (not eof).
    `protected void` | `setEof()` | Marks this blob as EOF (End of file).
    `protected void` | `setOpen​(boolean open)` | Sets the open state of the blob to the specified value.
    `void` | `transactionStateChanged​(FbTransaction transaction, TransactionState newState, TransactionState previousState)` | Signals that the transaction state changed.
    `void` | `warningReceived​(FbDatabase database, java.sql.SQLWarning warning)` | Called when a warning was received for the `database` connection.
    `protected LockCloseable` | `withLock()` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

      `getBlobId, getBlobInfo, getHandle, getSegment, isOutput, open, putSegment, seek`

- - ### Field Detail

    - #### exceptionListenerDispatcher

          protected final ExceptionListenerDispatcher exceptionListenerDispatcher

  - ### Constructor Detail

    - #### AbstractFbBlob

          protected AbstractFbBlob​(FbDatabase database,
                                   FbTransaction transaction,
                                   BlobParameterBuffer blobParameterBuffer)

  - ### Method Detail

    - #### isOpen

          public final boolean isOpen()

      Specified by:
        `isOpen` in interface `FbBlob`
      Returns:
        `true` if this blob is currently open.

    - #### isEof

          public final boolean isEof()

      Specified by:
        `isEof` in interface `FbBlob`
      Returns:
        `true` if this blob has reached the end or has been closed, always `true` for an open output blob.

    - #### setEof

          protected final void setEof()

      Marks this blob as EOF (End of file).

      For an output blob this is a no-op (as those are never end of file, unless explicitly closed)

    - #### resetEof

          protected final void resetEof()

      Resets the eof state of the blob to false (not eof).

      This method should only be called by sub-classes of this class.

    - #### setOpen

          protected final void setOpen​(boolean open)

      Sets the open state of the blob to the specified value.

      This method should only be called by sub-classes of this class.

      Parameters:
        `open` - New value of open.

    - #### close

          public final void close()
                           throws java.sql.SQLException

      Description copied from interface: `FbBlob`
      Closes the blob.

      Closing an already closed blob is a no-op.

      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `FbBlob`
      Throws:
        `java.sql.SQLException` - If the transaction is not active, or a database connection error occurred

    - #### closeImpl

          protected abstract void closeImpl()
                                     throws java.sql.SQLException

      Internal implementation of `close()`. The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.
      Throws:
        `java.sql.SQLException`

    - #### cancel

          public final void cancel()
                            throws java.sql.SQLException

      Description copied from interface: `FbBlob`
      Cancels an output blob (which means its contents will be thrown away).

      Calling cancel on an input blob will close it. Contrary to `FbBlob.close()`, calling cancel on an already closed (or cancelled) blob will throw an `SQLException`.

      Specified by:
        `cancel` in interface `FbBlob`
      Throws:
        `java.sql.SQLException` - If the blob has already been closed, the transaction is not active, or a database connection error occurred.

    - #### cancelImpl

          protected abstract void cancelImpl()
                                      throws java.sql.SQLException

      Internal implementation of `cancel()`. The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.
      Throws:
        `java.sql.SQLException`

    - #### releaseResources

          protected abstract void releaseResources()

      Release Java resources held. This should not communicate with the Firebird server.

    - #### withLock

          protected final LockCloseable withLock()

      See Also:
        `FbAttachment.withLock()`

    - #### transactionStateChanged

          public void transactionStateChanged​(FbTransaction transaction,
                                              TransactionState newState,
                                              TransactionState previousState)

      Description copied from interface: `TransactionListener`
      Signals that the transaction state changed.
      Specified by:
        `transactionStateChanged` in interface `TransactionListener`
      Parameters:
        `transaction` - `FbTransaction` that changed state

    - #### detaching

          public void detaching​(FbDatabase database)

      Description copied from interface: `DatabaseListener`
      Called before the `database` will be detached.

      This event is intended for cleanup action, implementer should take care that no exceptions are thrown from this method.

      Specified by:
        `detaching` in interface `DatabaseListener`
      Parameters:
        `database` - The database object that is detaching

    - #### detached

          public void detached​(FbDatabase database)

      Description copied from interface: `DatabaseListener`
      Called when the `database` connection has been detached
      Specified by:
        `detached` in interface `DatabaseListener`
      Parameters:
        `database` - The database object that was detached

    - #### warningReceived

          public void warningReceived​(FbDatabase database,
                                      java.sql.SQLWarning warning)

      Description copied from interface: `DatabaseListener`
      Called when a warning was received for the `database` connection.

      In implementation it is possible that some warnings are not sent to listeners on the database, but only to listeners on specific connection derived objects (like an `FbStatement` implementation).

      Specified by:
        `warningReceived` in interface `DatabaseListener`
      Parameters:
        `database` - Database receiving the warning
        `warning` - Warning

    - #### isEndingTransaction

          protected final boolean isEndingTransaction()

      Returns:
        `true` if the transaction is committing, rolling back or preparing

    - #### checkTransactionActive

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

      Throws:
        `java.sql.SQLException` - When no transaction is set, or the transaction state is not `TransactionState.ACTIVE`

    - #### checkDatabaseAttached

          protected void checkDatabaseAttached()
                                        throws java.sql.SQLException

      Throws:
        `java.sql.SQLException` - When no database is set, or the database is not attached

    - #### checkBlobOpen

          protected void checkBlobOpen()
                                throws java.sql.SQLException

      Throws:
        `java.sql.SQLException` - When the blob is closed.

    - #### checkBlobClosed

          protected void checkBlobClosed()
                                  throws java.sql.SQLException

      Throws:
        `java.sql.SQLException` - When the blob is open.

    - #### getTransaction

          protected FbTransaction getTransaction()

    - #### clearTransaction

          protected final void clearTransaction()

    - #### getDatabase

          public FbDatabase getDatabase()

      Specified by:
        `getDatabase` in interface `FbBlob`
      Returns:
        The database connection that created this blob

    - #### getBlobInfo

          public <T> T getBlobInfo​(byte[] requestItems,
                                   int bufferLength,
                                   InfoProcessor<T> infoProcessor)
                            throws java.sql.SQLException

      Description copied from interface: `FbBlob`
      Request blob info.
      Specified by:
        `getBlobInfo` in interface `FbBlob`
      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.

    - #### length

          public long length()
                      throws java.sql.SQLException

      Description copied from interface: `FbBlob`
      Requests the blob length from the server.
      Specified by:
        `length` in interface `FbBlob`
      Returns:
        Length of the blob.
      Throws:
        `java.sql.SQLException` - For Errors retrieving the length, or if the blob is not associated with a blob id, or the database is not attached.

    - #### addExceptionListener

          public final void addExceptionListener​(ExceptionListener listener)

      Description copied from interface: `ExceptionListenable`
      Adds an exception listener to this object.

      Implementations use `WeakReference`.

      Specified by:
        `addExceptionListener` in interface `ExceptionListenable`
      Parameters:
        `listener` - Listener to register

    - #### removeExceptionListener

          public final void removeExceptionListener​(ExceptionListener listener)

      Description copied from interface: `ExceptionListenable`
      Removes an exception listener to this object.
      Specified by:
        `removeExceptionListener` in interface `ExceptionListenable`
      Parameters:
        `listener` - Listener to remove

    - #### clearDatabase

          protected final void clearDatabase()

    - #### getBlobParameterBuffer

          protected BlobParameterBuffer getBlobParameterBuffer()

      Returns:
        The blob parameter buffer of this blob.

    - #### createBlobLengthProcessor

          protected BlobLengthProcessor createBlobLengthProcessor()

      Returns:
        New instance of `BlobLengthProcessor` for this blob.

    - #### getMaximumSegmentSize

          public int getMaximumSegmentSize()

      Description copied from interface: `FbBlob`
      The maximum segment size allowed by the protocol for `FbBlob.getSegment(int)` and `FbBlob.putSegment(byte[])`.

      This value is not the segment size (optionally) defined for the column.

      Specified by:
        `getMaximumSegmentSize` in interface `FbBlob`
      Returns:
        The maximum segment size allowed for get or put.