org.firebirdsql.gds.ng

## Interface FbBlob

All Superinterfaces:
  java.lang.AutoCloseable, ExceptionListenable

All Known Subinterfaces:
  FbWireBlob

All Known Implementing Classes:
  AbstractFbBlob, AbstractFbWireBlob, AbstractFbWireInputBlob, AbstractFbWireOutputBlob, JnaBlob, V10InputBlob, V10OutputBlob

    public interface FbBlob
    extends ExceptionListenable, java.lang.AutoCloseable

Interface for blob operations.

All methods defined in this interface are required to notify all `SQLException` thrown from the methods defined in this interface.

Since:
  3.0
Author:
  Mark Rotteveel

### Nested Class Summary

Nested Classes
`static class` `FbBlob.SeekMode` Seek mode for `seek(int, org.firebirdsql.gds.ng.FbBlob.SeekMode)`.

### Field Summary

Fields
`static long` `NO_BLOB_ID`

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `cancel()` Cancels an output blob (which means its contents will be thrown away).
`void` `close()` Closes the blob.
`long` `getBlobId()`
`byte[]` `getBlobInfo(byte[] requestItems, int bufferLength)` Request blob info.
`<T> T` `getBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)` Request blob info.
`FbDatabase` `getDatabase()`
`int` `getHandle()`
`int` `getMaximumSegmentSize()` The maximum segment size allowed by the protocol for `getSegment(int)` and `putSegment(byte[])`.
`byte[]` `getSegment(int sizeRequested)` Gets a segment of blob data.
`boolean` `isEof()`
`boolean` `isOpen()`
`boolean` `isOutput()`
`long` `length()` Requests the blob length from the server.
`void` `open()` Opens an existing input blob, or creates an output blob.
`void` `putSegment(byte[] segment)` Writes a segment of blob data.
`void` `seek(int offset, FbBlob.SeekMode seekMode)` Performs a seek on a blob with the specified `seekMode` and `offset`.

### Methods inherited from interface org.firebirdsql.gds.ng.listeners.ExceptionListenable

`addExceptionListener, removeExceptionListener`

### Field Detail

#### NO_BLOB_ID

    static final long NO_BLOB_ID

See Also:
  Constant Field Values

### Method Detail

#### getBlobId

    long getBlobId()

Returns:
  The Firebird blob id

#### getHandle

    int getHandle()

Returns:
  The Firebird blob handle identifier

#### getDatabase

    FbDatabase getDatabase()

Returns:
  The database connection that created this blob

#### open

    void open()
       throws java.sql.SQLException

Opens an existing input blob, or creates an output blob.

Throws:
  `java.sql.SQLException` - If the blob is already open, this is a (closed) output blob and it already has a blobId, the transaction is not active, or a database connection error occurred

#### isOpen

    boolean isOpen()

Returns:
  `true` if this blob is currently open.

#### isEof

    boolean isEof()

Returns:
  `true` if this blob has reached the end or has been closed, always `true` for an open output blob.

#### close

    void close()
        throws java.sql.SQLException

Closes the blob.

Closing an already closed blob is a no-op.

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

#### cancel

    void cancel()
         throws java.sql.SQLException

Cancels an output blob (which means its contents will be thrown away).

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

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

#### isOutput

    boolean isOutput()

Returns:
  `true` if this is an output blob (write only), `false` if this is an input blob (read only)

#### getSegment

    byte[] getSegment(int sizeRequested)
               throws java.sql.SQLException

Gets a segment of blob data.

When `sizeRequested` exceeds `getMaximumSegmentSize()` it is silently reduced to the maximum segment size.

TODO: Consider allowing this and have the implementation handle longer segments by sending multiple (batched?) requests.

Parameters:
  `sizeRequested` - Requested segment size (> 0).
Returns:
  Retrieved segment (size may be less than requested)
Throws:
  `java.sql.SQLException` - If this is an output blob, the blob is closed, the transaction is not active, or a database connection error occurred.

#### putSegment

    void putSegment(byte[] segment)
             throws java.sql.SQLException

Writes a segment of blob data.

Implementation must handle segment length exceeding `getMaximumSegmentSize()` by batching. TODO: reconsider and let caller handle that?

Passing a section that is length 0 will throw an `SQLException`.

Parameters:
  `segment` - Segment to write
Throws:
  `java.sql.SQLException` - If this is an input blob, the blob is closed, the transaction is not active, the segment is length 0 or longer than the maximum segment size, or a database connection error occurred.

#### seek

    void seek(int offset,
              FbBlob.SeekMode seekMode)
       throws java.sql.SQLException

Performs a seek on a blob with the specified `seekMode` and `offset`.

Firebird only supports seek on stream blobs.

Parameters:
  `offset` - Offset of the seek, effect depends on value of `seekMode`
  `seekMode` - Value of `FbBlob.SeekMode`
Throws:
  `java.sql.SQLException` - If the blob is closed, the transaction is not active, or a database error occurred.

#### getMaximumSegmentSize

    int getMaximumSegmentSize()

The maximum segment size allowed by the protocol for `getSegment(int)` and `putSegment(byte[])`.

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

Returns:
  The maximum segment size allowed for get or put.

#### getBlobInfo

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

Request blob 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.

#### length

    long length()
         throws java.sql.SQLException

Requests the blob length from the server.

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.

#### getBlobInfo

    byte[] getBlobInfo(byte[] requestItems,
                       int bufferLength)
                throws java.sql.SQLException

Request blob info.

Parameters:
  `requestItems` - Array of info items to request
  `bufferLength` - Response buffer length to use
Returns:
  Response buffer
Throws:
  `java.sql.SQLException`