Package org.firebirdsql.gds.ng

Interface FbBlob

    • 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