Package 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
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `FbBlob.SeekMode` | Seek mode for `seek(int, org.firebirdsql.gds.ng.FbBlob.SeekMode)`.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static long` | `NO_BLOB_ID` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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`