Package org.firebirdsql.gds.ng

Interface FbBlob

    • Method Detail

      • 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 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.

        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:
        java.sql.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 java.sql.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:
        java.sql.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 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