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
SQLExceptionthrown from the methods defined in this interface.- Since:
- 3.0
- Author:
- Mark Rotteveel
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static classFbBlob.SeekModeSeek mode forseek(int, org.firebirdsql.gds.ng.FbBlob.SeekMode).
-
Field Summary
Fields Modifier and Type Field Description static longNO_BLOB_ID
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidcancel()Cancels an output blob (which means its contents will be thrown away).voidclose()Closes the blob.longgetBlobId()byte[]getBlobInfo(byte[] requestItems, int bufferLength)Request blob info.<T> TgetBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)Request blob info.FbDatabasegetDatabase()intgetHandle()intgetMaximumSegmentSize()The maximum segment size allowed by the protocol forgetSegment(int)andputSegment(byte[]).byte[]getSegment(int sizeRequested)Gets a segment of blob data.java.lang.ObjectgetSynchronizationObject()Get synchronization object.booleanisEof()booleanisOpen()booleanisOutput()longlength()Requests the blob length from the server.voidopen()Opens an existing input blob, or creates an output blob.voidputSegment(byte[] segment)Writes a segment of blob data.voidseek(int offset, FbBlob.SeekMode seekMode)Performs a seek on a blob with the specifiedseekModeandoffset.-
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:
trueif this blob is currently open.
-
isEof
boolean isEof()
- Returns:
trueif this blob has reached the end or has been closed, alwaystruefor an open output blob.
-
close
void close() throws java.sql.SQLExceptionCloses the blob.Closing an already closed blob is a no-op.
- Specified by:
closein interfacejava.lang.AutoCloseable- Throws:
java.sql.SQLException- If the transaction is not active, or a database connection error occurred
-
cancel
void cancel() throws java.sql.SQLExceptionCancels 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 anSQLException.- 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:
trueif this is an output blob (write only),falseif 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.SQLExceptionGets a segment of blob data.When
TODO: Consider allowing this and have the implementation handle longer segments by sending multiple (batched?) requests.sizeRequestedexceedsgetMaximumSegmentSize()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.
-
putSegment
void putSegment(byte[] segment) throws java.sql.SQLExceptionWrites 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.SQLExceptionPerforms a seek on a blob with the specifiedseekModeandoffset.Firebird only supports seek on stream blobs.
- Parameters:
offset- Offset of the seek, effect depends on value ofseekModeseekMode- Value ofFbBlob.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 forgetSegment(int)andputSegment(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.SQLExceptionRequest blob info.- Parameters:
requestItems- Array of info items to requestbufferLength- Response buffer length to useinfoProcessor- Implementation ofInfoProcessorto 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.SQLExceptionRequests 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.SQLExceptionRequest blob info.- Parameters:
requestItems- Array of info items to requestbufferLength- Response buffer length to use- Returns:
- Response buffer
- Throws:
java.sql.SQLException
-
-