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, V11InputBlob, V11OutputBlob

      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.

  Implementations may defer the open or create the blob (meaning it's only open client-side), so the actual open or create is done when server-side access to the blob is needed. As a result `getBlobId()` and `getHandle()` may report invalid or unexpected values, see those methods for details.

  Since:
    3.0
  Author:
    Mark Rotteveel

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `FbBlob.SeekMode` Seek mode for `seek(int, org.firebirdsql.gds.ng.FbBlob.SeekMode)`.

  - ### Field Summary

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

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cancel()` Cancels an output blob (which means its contents will be thrown away).
    `void` | `close()` Closes the blob.
    `int` | `get(byte[] b, int off, int len)` Reads content from the blob into `b` starting at `off` for `len` bytes.
    `int` | `get(byte[] b, int off, int len, float minFillFactor)` Variant of `get(byte[], int, int)` to exert some control over the number of requests performed.
    `long` | `getBlobId()` Returns the blob id.
    `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()` Returns the blob handle identifier.
    `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` | `put(byte[] b, int off, int len)` Writes content of `b` starting at `off` for `length` bytes to the 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

      No blob id
      See Also:
        `getBlobId()`, Constant Field Values

  - ### Method Detail

    - #### getBlobId

          long getBlobId()

      Returns the blob id.

      For output blobs, this will return `NO_BLOB_ID` (`0L`) if the blob wasn't opened yet, or if the blob is deferred opened (client-side only). The value `NO_BLOB_ID` is technically invalid, but Firebird will handle it as an empty blob (both for input and output).

      Returns:
        The Firebird blob id

    - #### getHandle

          int getHandle()

      Returns the blob handle identifier.

      If the blob wasn't opened yet, this will return `0`. If the blob was deferred opened (client-side only), this will return an invalid blob handle value (e.g. `0xFFFF`, though this value is potentially protocol/implementation specific).

      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.

      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.
      See Also:
        `get(byte[], int, int)`

    - #### get

          int get(byte[] b,
                  int off,
                  int len)
           throws java.sql.SQLException

      Reads content from the blob into `b` starting at `off` for `len` bytes.

      Implementations must read the requested number of bytes (`len`), unless end-of-blob is reached before the requested number of bytes were read. The return value of this method is the actual number of bytes read.

      If the implementation cannot perform reads without additional allocation, it should use at most `DatabaseConnectionProperties.getBlobBufferSize()` as an internal buffer. If the implementation can perform reads without additional allocation, it is recommended it performs reads using (at most) `getMaximumSegmentSize()`.

      Contrary to similar methods like `InputStream.read(byte[], int, int)`, this method returns `0` when no bytes were read if end-of-blob is reached without reading any bytes, not `-1`.

      Given this method attempts to fulfill the entire request for `len` bytes, it may not always be efficient. For example, requests near multiples of the maximum segment size (or blob buffer size) may result in a final request for just a few bytes. This is not a problem if the entire blob is requested at once, but for intermediate buffering it might be better not to do that final request, and instead work with a smaller number of bytes than requested. For those cases, use `get(byte[], int, int, float)`.

      Parameters:
        `b` - target byte array
        `off` - offset to start
        `len` - number of bytes
      Returns:
        actual number of bytes read; this will only be less than `len` when end-of-blob was reached
      Throws:
        `java.sql.SQLException` - for database access errors, if `off < 0`, `len < 0`, or if `off + len > b.length`
      Since:
        5.0.7

    - #### get

          int get(byte[] b,
                  int off,
                  int len,
                  float minFillFactor)
           throws java.sql.SQLException

      Variant of `get(byte[], int, int)` to exert some control over the number of requests performed.

      This method will request segments until at least `(int) (minFillFactor * len)` bytes have been retrieved, or end-of-blob is reached. This method is intended as an alternative to `get(byte[], int, int)` where avoiding the potential inefficiencies of that method are preferred over getting all the requested `len` bytes.

      If the implementation cannot perform reads without additional allocation, it should use at most `DatabaseConnectionProperties.getBlobBufferSize()` as an internal buffer. If the implementation can perform reads without additional allocation, it is recommended it performs reads using (at most) `getMaximumSegmentSize()`.

      Contrary to similar methods like `InputStream.read(byte[], int, int)`, this method returns `0` when no bytes were read if end-of-blob is reached without reading any bytes, not `-1`.

      Parameters:
        `b` - target byte array
        `off` - offset to start
        `len` - number of bytes
        `minFillFactor` - minimum fill factor (`0 < minFillFactor <= 1`)
      Returns:
        actual number of bytes read, this method returns at least `(int) (minFillFactor * len)` bytes, unless end-of-blob is reached
      Throws:
        `java.sql.SQLException` - for database access errors, if `off < 0`, `len < 0`, or if `off + len > b.length`, `minFillFactor <= 0`, or `minFillFactor > 1` or `minFillFactor is NaN`
      Since:
        5.0.7

    - #### putSegment

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

      Writes a segment of blob data.

      Implementations must handle segment lengths exceeding `getMaximumSegmentSize()` by batching. This method should either call `put(segment, 0, segment.length)`, or produce the same effects as that call.

      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 a database connection error occurred
      See Also:
        `put(byte[], int, int)`

    - #### put

          void put(byte[] b,
                   int off,
                   int len)
            throws java.sql.SQLException

      Writes content of `b` starting at `off` for `length` bytes to the blob.

      Implementations must write all bytes to the blob, using multiple round-trips if necessary.

      If the implementation cannot perform writes without additional allocation, it should use at most `DatabaseConnectionProperties.getBlobBufferSize()` as an internal buffer. If the implementation can perform writes without additional allocation, it is recommended it performs reads using (at most) `getMaximumSegmentSize()`.

      Parameters:
        `b` - source byte array
        `off` - offset to start
        `len` - number of bytes
      Throws:
        `java.sql.SQLException` - for database access errors, if `off < 0`, `len < 0`, or if `off + len > b.length`
      Since:
        5.0.7

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

Copyright © 2001-2025 Jaybird (Firebird JDBC) team. All rights reserved.