Interface FbBlob
- 
- All Superinterfaces:
- java.lang.AutoCloseable,- ExceptionListenable
 - All Known Subinterfaces:
- FbWireBlob
 - All Known Implementing Classes:
- AbstractFbBlob,- AbstractFbWireBlob,- AbstractFbWireInputBlob,- AbstractFbWireOutputBlob,- InlineBlob,- JnaBlob,- V10InputBlob,- V10OutputBlob,- V11InputBlob,- V11OutputBlob
 
 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.Implementations may defer the open or create the blob (meaning it's only open client-side), so the actual open or create is done when server-side access to the blob is needed. As a result getBlobId()andgetHandle()may report invalid or unexpected values, see those methods for details.- Since:
- 3.0
- Author:
- Mark Rotteveel
 
- 
- 
Nested Class SummaryNested Classes Modifier and Type Interface Description static classFbBlob.SeekModeSeek mode forseek(int, org.firebirdsql.gds.ng.FbBlob.SeekMode).
 - 
Field SummaryFields Modifier and Type Field Description static longNO_BLOB_IDNo blob id
 - 
Method SummaryAll 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.intget(byte[] b, int off, int len)Reads content from the blob intobstarting atoffforlenbytes.intget(byte[] b, int off, int len, float minFillFactor)Variant ofget(byte[], int, int)to exert some control over the number of requests performed.longgetBlobId()Returns the blob id.byte[]getBlobInfo(byte[] requestItems, int bufferLength)Request blob info.<T> TgetBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)Request blob info.FbDatabasegetDatabase()intgetHandle()Returns the blob handle identifier.intgetMaximumSegmentSize()The maximum segment size allowed by the protocol forgetSegment(int)andputSegment(byte[]).byte[]getSegment(int sizeRequested)Gets a segment of blob data.booleanisEof()booleanisOpen()booleanisOutput()longlength()Requests the blob length from the server.voidopen()Opens an existing input blob, or creates an output blob.voidput(byte[] b, int off, int len)Writes content ofbstarting atoffforlengthbytes to the 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.ExceptionListenableaddExceptionListener, removeExceptionListener
 
- 
 
- 
- 
- 
Field Detail- 
NO_BLOB_IDstatic final long NO_BLOB_ID No blob id- See Also:
- getBlobId(), Constant Field Values
 
 
- 
 - 
Method Detail- 
getBlobIdlong 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 valueNO_BLOB_IDis technically invalid, but Firebird will handle it as an empty blob (both for input and output).- Returns:
- The Firebird blob id
 
 - 
getHandleint 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
 
 - 
getDatabaseFbDatabase getDatabase() - Returns:
- The database connection that created this blob
 
 - 
openvoid 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
 
 - 
isOpenboolean isOpen() - Returns:
- trueif this blob is currently open.
 
 - 
isEofboolean isEof() - Returns:
- trueif this blob has reached the end or has been closed, always- truefor an open output blob.
 
 - 
closevoid close() throws java.sql.SQLExceptionCloses the blob.Closing an already closed blob is a no-op. - Specified by:
- closein interface- java.lang.AutoCloseable
- Throws:
- java.sql.SQLException- If the transaction is not active, or a database connection error occurred
 
 - 
cancelvoid 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.
 
 - 
isOutputboolean isOutput() - Returns:
- trueif this is an output blob (write only),- falseif this is an input blob (read only)
 
 - 
getSegmentbyte[] getSegment(int sizeRequested) throws java.sql.SQLExceptionGets a segment of blob data.When 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.
- See Also:
- get(byte[], int, int)
 
 - 
getint get(byte[] b, int off, int len) throws java.sql.SQLExceptionReads content from the blob intobstarting atoffforlenbytes.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 returns0when 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 lenbytes, 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, useget(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 lenwhen 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
 
 - 
getint get(byte[] b, int off, int len, float minFillFactor) throws java.sql.SQLExceptionVariant ofget(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 toget(byte[], int, int)where avoiding the potential inefficiencies of that method are preferred over getting all the requestedlenbytes.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 returns0when 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 > 1or- minFillFactor is NaN
- Since:
- 5.0.7
 
 - 
putSegmentvoid putSegment(byte[] segment) throws java.sql.SQLExceptionWrites a segment of blob data.Implementations must handle segment lengths exceeding getMaximumSegmentSize()by batching. This method should either callput(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)
 
 - 
putvoid put(byte[] b, int off, int len) throws java.sql.SQLExceptionWrites content ofbstarting atoffforlengthbytes 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
 
 - 
seekvoid 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 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.
 
 - 
getMaximumSegmentSizeint 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 request
- bufferLength- Response buffer length to use
- infoProcessor- Implementation of- InfoProcessorto transform the info response
- Returns:
- Transformed info response of type T
- Throws:
- java.sql.SQLException- For errors retrieving or transforming the response.
 
 - 
lengthlong 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.
 
 - 
getBlobInfobyte[] getBlobInfo(byte[] requestItems, int bufferLength) throws java.sql.SQLExceptionRequest blob info.- Parameters:
- requestItems- Array of info items to request
- bufferLength- Response buffer length to use
- Returns:
- Response buffer
- Throws:
- java.sql.SQLException
 
 
- 
 
-