org.firebirdsql.gds.ng.jna

## Class JnaBlob

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

- All Implemented Interfaces:
    java.lang.AutoCloseable, FbBlob, DatabaseListener, ExceptionListenable, TransactionListener

      public class JnaBlob
      extends AbstractFbBlob
      implements FbBlob, DatabaseListener

  Implementation of `FbBlob` for native client access.
  Since:
    3.0
  Author:
    Mark Rotteveel

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.firebirdsql.gds.ng.AbstractFbBlob

      `AbstractFbBlob.BlobState`

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

      `FbBlob.SeekMode`

  - ### Field Summary

    - ### Fields inherited from class org.firebirdsql.gds.ng.AbstractFbBlob

      `exceptionListenerDispatcher`

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

      `NO_BLOB_ID`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JnaBlob(JnaDatabase database, JnaTransaction transaction, BlobParameterBuffer blobParameterBuffer)` Creates a blob for output (writing to the database).
    `JnaBlob(JnaDatabase database, JnaTransaction transaction, BlobParameterBuffer blobParameterBuffer, long blobId)` Creates a blob for input (reading from the database).

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `cancelImpl()` Internal implementation of `AbstractFbBlob.cancel()`.
    `protected void` | `closeImpl()` Internal implementation of `AbstractFbBlob.close()`.
    `protected int` | `get(byte[] b, int off, int len, int minLen)` Default implementation for `AbstractFbBlob.get(byte[], int, int)` and `AbstractFbBlob.get(byte[], int, int, float)`.
    `long` | `getBlobId()` Returns the blob id.
    `byte[]` | `getBlobInfo(byte[] requestItems, int bufferLength)` Request blob info.
    `JnaDatabase` | `getDatabase()`
    `int` | `getHandle()` Returns the blob handle identifier.
    `com.sun.jna.ptr.IntByReference` | `getJnaHandle()`
    `byte[]` | `getSegment(int sizeRequested)` Gets a segment of blob data.
    `JnaTransaction` | `getTransaction()`
    `boolean` | `isOutput()`
    `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.
    `protected void` | `releaseResources()` Release Java resources held.
    `void` | `seek(int offset, FbBlob.SeekMode seekMode)` Performs a seek on a blob with the specified `seekMode` and `offset`.

    - ### Methods inherited from class org.firebirdsql.gds.ng.AbstractFbBlob

      `addExceptionListener, cancel, checkBlobClosed, checkBlobOpen, checkDatabaseAttached, checkTransactionActive, clearDatabase, clearDeferredException, clearTransaction, close, createBlobLengthProcessor, detached, detaching, errorOccurred, get, get, getBlobInfo, getBlobParameterBuffer, getKnownBlobInfoItems, getMaximumSegmentSize, getState, isEndingTransaction, isEof, isOpen, length, putSegment, registerDeferredException, removeExceptionListener, resetEof, setEof, setState, throwAndClearDeferredException, transactionStateChanged, transferDeferredExceptionTo, validateBufferLength, warningReceived, 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

      `cancel, close, get, get, getBlobInfo, getMaximumSegmentSize, isEof, isOpen, length, putSegment`

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

      `addExceptionListener, removeExceptionListener`

    - ### Methods inherited from interface org.firebirdsql.gds.ng.listeners.DatabaseListener

      `detached, detaching, warningReceived`

- - ### Constructor Detail

    - #### JnaBlob

          public JnaBlob(JnaDatabase database,
                         JnaTransaction transaction,
                         BlobParameterBuffer blobParameterBuffer)
                  throws java.sql.SQLException

      Creates a blob for output (writing to the database).
      Parameters:
        `database` - database
        `transaction` - transaction
        `blobParameterBuffer` - blob parameter buffer
      Throws:
        `java.sql.SQLException`

    - #### JnaBlob

          public JnaBlob(JnaDatabase database,
                         JnaTransaction transaction,
                         BlobParameterBuffer blobParameterBuffer,
                         long blobId)
                  throws java.sql.SQLException

      Creates a blob for input (reading from the database).
      Parameters:
        `database` - database
        `transaction` - transaction
        `blobParameterBuffer` - blob parameter buffer
        `blobId` - blob id
      Throws:
        `java.sql.SQLException`

  - ### Method Detail

    - #### getDatabase

          public JnaDatabase getDatabase()

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

    - #### getTransaction

          public JnaTransaction getTransaction()

      Overrides:
        `getTransaction` in class `AbstractFbBlob`

    - #### getHandle

          public int getHandle()

      Description copied from interface: `FbBlob`
      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).

      Specified by:
        `getHandle` in interface `FbBlob`
      Returns:
        The Firebird blob handle identifier

    - #### getJnaHandle

          public final com.sun.jna.ptr.IntByReference getJnaHandle()

    - #### getBlobId

          public final long getBlobId()

      Description copied from interface: `FbBlob`
      Returns the blob id.

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

      Specified by:
        `getBlobId` in interface `FbBlob`
      Returns:
        The Firebird blob id

    - #### open

          public void open()
                    throws java.sql.SQLException

      Description copied from interface: `FbBlob`
      Opens an existing input blob, or creates an output blob.
      Specified by:
        `open` in interface `FbBlob`
      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

    - #### isOutput

          public final boolean isOutput()

      Specified by:
        `isOutput` in interface `FbBlob`
      Returns:
        `true` if this is an output blob (write only), `false` if this is an input blob (read only)

    - #### getSegment

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

      Description copied from interface: `FbBlob`
      Gets a segment of blob data.

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

      Specified by:
        `getSegment` in interface `FbBlob`
      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:
        `FbBlob.get(byte[], int, int)`

    - #### get

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

      Description copied from class: `AbstractFbBlob`
      Default implementation for `AbstractFbBlob.get(byte[], int, int)` and `AbstractFbBlob.get(byte[], int, int, float)`.
      Specified by:
        `get` in class `AbstractFbBlob`
      Parameters:
        `b` - target byte array
        `off` - offset to start
        `len` - number of bytes
        `minLen` - minimum number of bytes to fill (must be `0 < minLen <= len` if `len != 0`
      Returns:
        actual number of bytes read; is `0` if `len == 0`, will only be less than `minLen` if end-of-blob is reached
      Throws:
        `java.sql.SQLException` - for database access errors, if `off < 0`, `len < 0`, or if `off + len > b.length`, or `len != 0 && (minLen <= 0 || minLen > len)`

    - #### put

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

      Description copied from interface: `FbBlob`
      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) `FbBlob.getMaximumSegmentSize()`.

      Specified by:
        `put` in interface `FbBlob`
      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`

    - #### seek

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

      Description copied from interface: `FbBlob`
      Performs a seek on a blob with the specified `seekMode` and `offset`.

      Firebird only supports seek on stream blobs.

      Specified by:
        `seek` in interface `FbBlob`
      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.

    - #### getBlobInfo

          public byte[] getBlobInfo(byte[] requestItems,
                                    int bufferLength)
                             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
      Returns:
        Response buffer
      Throws:
        `java.sql.SQLException`

    - #### closeImpl

          protected void closeImpl()
                            throws java.sql.SQLException

      Description copied from class: `AbstractFbBlob`
      Internal implementation of `AbstractFbBlob.close()`. The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.
      Specified by:
        `closeImpl` in class `AbstractFbBlob`
      Throws:
        `java.sql.SQLException`

    - #### cancelImpl

          protected void cancelImpl()
                             throws java.sql.SQLException

      Description copied from class: `AbstractFbBlob`
      Internal implementation of `AbstractFbBlob.cancel()`. The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.
      Specified by:
        `cancelImpl` in class `AbstractFbBlob`
      Throws:
        `java.sql.SQLException`

    - #### releaseResources

          protected void releaseResources()

      Description copied from class: `AbstractFbBlob`
      Release Java resources held. This should not communicate with the Firebird server.
      Specified by:
        `releaseResources` in class `AbstractFbBlob`

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