org.firebirdsql.gds.ng

Interface FbBlob

All Superinterfaces:

java.lang.AutoCloseable, ExceptionListenable

All Known Subinterfaces:

FbWireBlob

All Known Implementing Classes:

AbstractFbBlob, AbstractFbWireBlob, AbstractFbWireInputBlob, AbstractFbWireOutputBlob, JnaBlob, V10InputBlob, V10OutputBlob

public interface FbBlob
extends ExceptionListenable, java.lang.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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	FbBlob.SeekMode Seek mode for seek(int, org.firebirdsql.gds.ng.FbBlob.SeekMode).

Field Summary

Fields

Modifier and Type	Field and Description
static long	NO_BLOB_ID

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancels an output blob (which means its contents will be thrown away).
void	close() Closes the blob.
long	getBlobId()
byte[]	getBlobInfo(byte[] requestItems, int bufferLength) Request blob info.
<T> T	getBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) Request blob info.
FbDatabase	getDatabase()
int	getHandle()
int	getMaximumSegmentSize() The maximum segment size allowed by the protocol for getSegment(int) and putSegment(byte[]).
byte[]	getSegment(int sizeRequested) Gets a segment of blob data.
java.lang.Object	getSynchronizationObject() Get synchronization object.
boolean	isEof()
boolean	isOpen()
boolean	isOutput()
long	length() Requests the blob length from the server.
void	open() Opens an existing input blob, or creates an output blob.
void	putSegment(byte[] segment) Writes a segment of blob data.
void	seek(int offset, FbBlob.SeekMode seekMode) Performs a seek on a blob with the specified seekMode and offset.

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

addExceptionListener, removeExceptionListener

Field Detail

NO_BLOB_ID

static final long NO_BLOB_ID

See Also:

Constant Field Values

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)

getSynchronizationObject

java.lang.Object getSynchronizationObject()

Get synchronization object.

Returns:

object, cannot be null.

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