Class AbstractFbBlob

java.lang.Object
org.firebirdsql.gds.ng.AbstractFbBlob
All Implemented Interfaces:
AutoCloseable, FbBlob, DatabaseListener, ExceptionListenable, TransactionListener
Direct Known Subclasses:
AbstractFbWireBlob

public abstract class AbstractFbBlob extends Object implements FbBlob, TransactionListener, DatabaseListener
Base class for low-level blob operations.
Since:
3.0
Author:
Mark Rotteveel
  • Field Details

  • Constructor Details

  • Method Details

    • isOpen

      public final boolean isOpen()
      Specified by:
      isOpen in interface FbBlob
      Returns:
      true if this blob is currently open.
    • isEof

      public final boolean isEof()
      Specified by:
      isEof in interface FbBlob
      Returns:
      true if this blob has reached the end or has been closed, always true for an open output blob.
    • setEof

      protected final void setEof()
      Marks this blob as EOF (end of file).

      For an output blob this is a no-op (as those are never end of file, unless explicitly closed)

    • resetEof

      protected final void resetEof()
      Resets the eof state of the blob to false (not eof).

      This method should only be called by sub-classes of this class.

    • setOpen

      protected final void setOpen(boolean open)
      Sets the open state of the blob to the specified value.

      This method should only be called by sub-classes of this class.

      Parameters:
      open - new value of open
    • close

      public final void close() throws SQLException
      Description copied from interface: FbBlob
      Closes the blob.

      Closing an already closed blob is a no-op.

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

      protected abstract void closeImpl() throws SQLException
      Internal implementation of close(). The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.
      Throws:
      SQLException
    • cancel

      public final void cancel() throws SQLException
      Description copied from interface: FbBlob
      Cancels an output blob (which means its contents will be thrown away).

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

      Specified by:
      cancel in interface FbBlob
      Throws:
      SQLException - If the blob has already been closed, the transaction is not active, or a database connection error occurred.
    • cancelImpl

      protected abstract void cancelImpl() throws SQLException
      Internal implementation of cancel(). The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.
      Throws:
      SQLException
    • putSegment

      public void putSegment(byte[] segment) throws SQLException
      Description copied from interface: FbBlob
      Writes a segment of blob data.

      Implementations must handle segment lengths exceeding FbBlob.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.

      Specified by:
      putSegment in interface FbBlob
      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 a database connection error occurred
      See Also:
    • get

      public final int get(byte[] b, int off, int len) throws SQLException
      Description copied from interface: FbBlob
      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) FbBlob.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 FbBlob.get(byte[], int, int, float).

      Specified by:
      get in interface FbBlob
      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:
      SQLException - for database access errors, if off < 0, len < 0, or if off + len > b.length
    • get

      public final int get(byte[] b, int off, int len, float minFillFactor) throws SQLException
      Description copied from interface: FbBlob
      Variant of FbBlob.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 FbBlob.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) FbBlob.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.

      Specified by:
      get in interface FbBlob
      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:
      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
    • get

      protected abstract int get(byte[] b, int off, int len, int minLen) throws SQLException
      Default implementation for get(byte[], int, int) and get(byte[], int, int, float).
      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:
      SQLException - for database access errors, if off < 0, len < 0, or if off + len > b.length, or len != 0 && (minLen <= 0 || minLen > len)
    • releaseResources

      protected abstract void releaseResources()
      Release Java resources held. This should not communicate with the Firebird server.
    • withLock

      protected final LockCloseable withLock()
      See Also:
    • transactionStateChanged

      public void transactionStateChanged(FbTransaction transaction, TransactionState newState, TransactionState previousState)
      Description copied from interface: TransactionListener
      Signals that the transaction state changed.
      Specified by:
      transactionStateChanged in interface TransactionListener
      Parameters:
      transaction - FbTransaction that changed state
    • detaching

      public void detaching(FbDatabase database)
      Description copied from interface: DatabaseListener
      Called before the database will be detached.

      This event is intended for cleanup action, implementer should take care that no exceptions are thrown from this method.

      Specified by:
      detaching in interface DatabaseListener
      Parameters:
      database - The database object that is detaching
    • detached

      public void detached(FbDatabase database)
      Description copied from interface: DatabaseListener
      Called when the database connection has been detached
      Specified by:
      detached in interface DatabaseListener
      Parameters:
      database - The database object that was detached
    • warningReceived

      public void warningReceived(FbDatabase database, SQLWarning warning)
      Description copied from interface: DatabaseListener
      Called when a warning was received for the database connection.

      In implementation it is possible that some warnings are not sent to listeners on the database, but only to listeners on specific connection derived objects (like an FbStatement implementation).

      Specified by:
      warningReceived in interface DatabaseListener
      Parameters:
      database - Database receiving the warning
      warning - Warning
    • isEndingTransaction

      protected final boolean isEndingTransaction()
      Returns:
      true if the transaction is committing, rolling back or preparing
    • checkTransactionActive

      protected final void checkTransactionActive() throws SQLException
      Throws:
      SQLException - When no transaction is set, or the transaction state is not TransactionState.ACTIVE
    • checkDatabaseAttached

      protected void checkDatabaseAttached() throws SQLException
      Throws:
      SQLException - When no database is set, or the database is not attached
    • checkBlobOpen

      protected void checkBlobOpen() throws SQLException
      Throws:
      SQLException - When the blob is closed.
    • checkBlobClosed

      protected void checkBlobClosed() throws SQLException
      Throws:
      SQLException - When the blob is open.
    • getTransaction

      protected FbTransaction getTransaction()
    • clearTransaction

      protected final void clearTransaction()
    • getDatabase

      public FbDatabase getDatabase()
      Specified by:
      getDatabase in interface FbBlob
      Returns:
      The database connection that created this blob
    • getBlobInfo

      public <T> T getBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws 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
      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

      public long length() throws SQLException
      Description copied from interface: FbBlob
      Requests the blob length from the server.
      Specified by:
      length in interface FbBlob
      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.
    • addExceptionListener

      public final void addExceptionListener(ExceptionListener listener)
      Description copied from interface: ExceptionListenable
      Adds an exception listener to this object.

      Implementations use WeakReference.

      Specified by:
      addExceptionListener in interface ExceptionListenable
      Parameters:
      listener - Listener to register
    • removeExceptionListener

      public final void removeExceptionListener(ExceptionListener listener)
      Description copied from interface: ExceptionListenable
      Removes an exception listener to this object.
      Specified by:
      removeExceptionListener in interface ExceptionListenable
      Parameters:
      listener - Listener to remove
    • clearDatabase

      protected final void clearDatabase()
    • getBlobParameterBuffer

      protected BlobParameterBuffer getBlobParameterBuffer()
      Returns:
      The blob parameter buffer of this blob.
    • createBlobLengthProcessor

      protected BlobLengthProcessor createBlobLengthProcessor()
      Returns:
      New instance of BlobLengthProcessor for this blob.
    • getMaximumSegmentSize

      public int getMaximumSegmentSize()
      Description copied from interface: FbBlob
      The maximum segment size allowed by the protocol for FbBlob.getSegment(int) and FbBlob.putSegment(byte[]).

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

      Specified by:
      getMaximumSegmentSize in interface FbBlob
      Returns:
      The maximum segment size allowed for get or put.
    • validateBufferLength

      protected final void validateBufferLength(byte[] b, int off, int len) throws SQLException
      Validates requested offset (off) and length (len) against the array (b).
      Parameters:
      b - array
      off - position in array
      len - length from off
      Throws:
      SQLException - if off < 0, len < 0, or if off + len > b.length
      Since:
      6