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
`protected ExceptionListenerDispatcher` `exceptionListenerDispatcher`

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

`NO_BLOB_ID`

### Constructor Summary

Constructors
`protected` `AbstractFbBlob(FbDatabase database, FbTransaction transaction, BlobParameterBuffer blobParameterBuffer)`

### Method Summary

Methods
`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[])`.
`java.lang.Object` `getSynchronizationObject()` Get synchronization object.
`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.

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

#### getSynchronizationObject

    public final java.lang.Object getSynchronizationObject()

Description copied from interface: `FbBlob`
Get synchronization object.

Specified by:
  `getSynchronizationObject` in interface `FbBlob`
Returns:
  object, cannot be `null`.

#### 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` (or subclass) 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.