Package org.firebirdsql.gds.ng

Interface FbBlob

All Superinterfaces:
AutoCloseable, ExceptionListenable
All Known Subinterfaces:
FbWireBlob
All Known Implementing Classes:
AbstractFbBlob, AbstractFbWireBlob, AbstractFbWireInputBlob, AbstractFbWireOutputBlob, JnaBlob, V10InputBlob, V10OutputBlob
public interface FbBlob extends ExceptionListenable, 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

  • Field Details

  • Method Details

    • 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 SQLException
      Opens an existing input blob, or creates an output blob.
      Throws:
      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 SQLException
      Closes the blob.

      Closing an already closed blob is a no-op.

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

    • cancel

      void cancel() throws 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:
      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)

    • getSynchronizationObject

      Object getSynchronizationObject()
      Get synchronization object.
      Returns:
      object, cannot be null.

    • getSegment

      byte[] getSegment(int sizeRequested) throws 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:
      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 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:
      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 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:
      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 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:
      SQLException - For errors retrieving or transforming the response.

    • length

      long length() throws SQLException
      Requests the blob length from the server.
      Returns:
      Length of the blob.
      Throws:
      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 SQLException
      Request blob info.
      Parameters:
      requestItems - Array of info items to request
      bufferLength - Response buffer length to use
      Returns:
      Response buffer
      Throws:
      SQLException