Class AbstractFbBlob
- java.lang.Object
- 
- org.firebirdsql.gds.ng.AbstractFbBlob
 
- 
- All Implemented Interfaces:
- java.lang.AutoCloseable,- FbBlob,- DatabaseListener,- ExceptionListenable,- TransactionListener
 - Direct Known Subclasses:
- AbstractFbWireBlob,- JnaBlob
 
 public abstract class AbstractFbBlob extends java.lang.Object implements FbBlob, TransactionListener, DatabaseListener Base class for low-level blob operations.- Since:
- 3.0
- Author:
- Mark Rotteveel
 
- 
- 
Nested Class SummaryNested Classes Modifier and Type Class Description protected static classAbstractFbBlob.BlobStateState of the blob.- 
Nested classes/interfaces inherited from interface org.firebirdsql.gds.ng.FbBlobFbBlob.SeekMode
 
- 
 - 
Field SummaryFields Modifier and Type Field Description protected ExceptionListenerDispatcherexceptionListenerDispatcher- 
Fields inherited from interface org.firebirdsql.gds.ng.FbBlobNO_BLOB_ID
 
- 
 - 
Constructor SummaryConstructors Modifier Constructor Description protectedAbstractFbBlob(FbDatabase database, FbTransaction transaction, BlobParameterBuffer blobParameterBuffer)
 - 
Method SummaryAll Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description voidaddExceptionListener(ExceptionListener listener)Adds an exception listener to this object.voidcancel()Cancels an output blob (which means its contents will be thrown away).protected abstract voidcancelImpl()Internal implementation ofcancel().protected voidcheckBlobClosed()protected voidcheckBlobOpen()Checks if the blob is open.protected voidcheckDatabaseAttached()protected voidcheckTransactionActive()protected voidclearDatabase()protected voidclearDeferredException()Clears the deferred exception.protected voidclearTransaction()voidclose()Closes the blob.protected abstract voidcloseImpl()Internal implementation ofclose().protected BlobLengthProcessorcreateBlobLengthProcessor()voiddetached(FbDatabase database)Called when thedatabaseconnection has been detachedvoiddetaching(FbDatabase database)Called before thedatabasewill be detached.protected voiderrorOccurred(java.sql.SQLException e)intget(byte[] b, int off, int len)Reads content from the blob intobstarting atoffforlenbytes.intget(byte[] b, int off, int len, float minFillFactor)Variant ofFbBlob.get(byte[], int, int)to exert some control over the number of requests performed.protected abstract intget(byte[] b, int off, int len, int minLen)Default implementation forget(byte[], int, int)andget(byte[], int, int, float).<T> TgetBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor)Request blob info.protected BlobParameterBuffergetBlobParameterBuffer()FbDatabasegetDatabase()protected byte[]getKnownBlobInfoItems()The known blob info items for the connected server as a blob info request buffer.intgetMaximumSegmentSize()The maximum segment size allowed by the protocol forFbBlob.getSegment(int)andFbBlob.putSegment(byte[]).protected AbstractFbBlob.BlobStategetState()The current blob state.protected FbTransactiongetTransaction()protected booleanisEndingTransaction()booleanisEof()booleanisOpen()longlength()Requests the blob length from the server.voidputSegment(byte[] segment)Writes a segment of blob data.protected voidregisterDeferredException(java.sql.SQLException deferredException)Registers an exception as a deferred exception.protected abstract voidreleaseResources()Release Java resources held.voidremoveExceptionListener(ExceptionListener listener)Removes an exception listener to this object.protected voidresetEof()Resets the eof state of the blob to false (not eof).protected voidsetEof()Marks this blob as EOF (End of file).protected voidsetState(AbstractFbBlob.BlobState newState)Sets the state of the blob to the specified value.protected voidthrowAndClearDeferredException()If a deferred exception is registered it is cleared and thrown.voidtransactionStateChanged(FbTransaction transaction, TransactionState newState, TransactionState previousState)Signals that the transaction state changed.protected voidtransferDeferredExceptionTo(java.sql.SQLException target)If a deferred exception is registered, it is cleared and set as a next exception ontarget.voidwarningReceived(FbDatabase database, java.sql.SQLWarning warning)Called when a warning was received for thedatabaseconnection.protected LockCloseablewithLock()- 
Methods inherited from class java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 - 
Methods inherited from interface org.firebirdsql.gds.ng.FbBlobgetBlobId, getBlobInfo, getHandle, getSegment, isOutput, open, put, seek
 
- 
 
- 
- 
- 
Field Detail- 
exceptionListenerDispatcherprotected final ExceptionListenerDispatcher exceptionListenerDispatcher 
 
- 
 - 
Constructor Detail- 
AbstractFbBlobprotected AbstractFbBlob(FbDatabase database, FbTransaction transaction, BlobParameterBuffer blobParameterBuffer) throws java.sql.SQLException - Throws:
- java.sql.SQLException
 
 
- 
 - 
Method Detail- 
isOpenpublic final boolean isOpen() 
 - 
isEofpublic final boolean isEof() 
 - 
setEofprotected final void setEof() Marks this blob as EOF (End of file).For an output blob this is a no-op (as those are never end of file, unless explicitly closed) 
 - 
resetEofprotected final void resetEof() Resets the eof state of the blob to false (not eof).This method should only be called by subclasses of this class. 
 - 
setStateprotected final void setState(AbstractFbBlob.BlobState newState) Sets the state of the blob to the specified value.This method should only be called by subclasses of this class. - Parameters:
- newState- new value of state
- Since:
- 5.0.7
 
 - 
getStateprotected final AbstractFbBlob.BlobState getState() The current blob state.- Returns:
- current blob state
- Since:
- 5.0.7
 
 - 
closepublic final void close() throws java.sql.SQLExceptionDescription copied from interface:FbBlobCloses the blob.Closing an already closed blob is a no-op. 
 - 
closeImplprotected abstract void closeImpl() throws java.sql.SQLExceptionInternal implementation ofclose(). The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.- Throws:
- java.sql.SQLException
 
 - 
cancelpublic final void cancel() throws java.sql.SQLExceptionDescription copied from interface:FbBlobCancels an output blob (which means its contents will be thrown away).Calling cancel on an input blob will close it. Contrary to FbBlob.close(), calling cancel on an already closed (or cancelled) blob will throw anSQLException.
 - 
cancelImplprotected abstract void cancelImpl() throws java.sql.SQLExceptionInternal implementation ofcancel(). The implementation does not need to check for attached database and active transaction, nor does it need to mark this blob as closed.- Throws:
- java.sql.SQLException
 
 - 
putSegmentpublic void putSegment(byte[] segment) throws java.sql.SQLExceptionDescription copied from interface:FbBlobWrites a segment of blob data.Implementations must handle segment lengths exceeding FbBlob.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.- Specified by:
- putSegmentin interface- FbBlob
- 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:
- FbBlob.put(byte[], int, int)
 
 - 
getpublic final int get(byte[] b, int off, int len) throws java.sql.SQLExceptionDescription copied from interface:FbBlobReads 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)FbBlob.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, useFbBlob.get(byte[], int, int, float).- Specified by:
- getin interface- FbBlob
- 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
 
 - 
getpublic final int get(byte[] b, int off, int len, float minFillFactor) throws java.sql.SQLExceptionDescription copied from interface:FbBlobVariant ofFbBlob.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 toFbBlob.get(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)FbBlob.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.- Specified by:
- getin interface- FbBlob
- 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
 
 - 
getprotected abstract int get(byte[] b, int off, int len, int minLen) throws java.sql.SQLExceptionDefault implementation forget(byte[], int, int)andget(byte[], int, int, float).- Parameters:
- b- target byte array
- off- offset to start
- len- number of bytes
- minLen- minimum number of bytes to fill (must be- 0 < minLen <= lenif- len != 0
- Returns:
- actual number of bytes read; is 0iflen == 0, will only be less thanminLenif end-of-blob is reached
- Throws:
- java.sql.SQLException- for database access errors, if- off < 0,- len < 0, or if- off + len > b.length, or- len != 0 && (minLen <= 0 || minLen > len)
 
 - 
releaseResourcesprotected abstract void releaseResources() Release Java resources held. This should not communicate with the Firebird server.
 - 
registerDeferredExceptionprotected final void registerDeferredException(java.sql.SQLException deferredException) Registers an exception as a deferred exception.This should only be used for exceptions from deferred response that need to be thrown. - Parameters:
- deferredException- deferred exception
- Since:
- 5.0.7
 
 - 
clearDeferredExceptionprotected final void clearDeferredException() Clears the deferred exception.- Since:
- 5.0.7
 
 - 
throwAndClearDeferredExceptionprotected final void throwAndClearDeferredException() throws java.sql.SQLExceptionIf a deferred exception is registered it is cleared and thrown.- Throws:
- java.sql.SQLException- the current deferred exception, if any
- Since:
- 5.0.7
 
 - 
transferDeferredExceptionToprotected final void transferDeferredExceptionTo(java.sql.SQLException target) If a deferred exception is registered, it is cleared and set as a next exception ontarget.- Parameters:
- target- the target exception to add the deferred exception to (not- null)
- Throws:
- java.lang.NullPointerException- if there is a deferred exception, and- target == null
- Since:
- 5.0.7
 
 - 
withLockprotected final LockCloseable withLock() - See Also:
- FbAttachment.withLock()
 
 - 
transactionStateChangedpublic void transactionStateChanged(FbTransaction transaction, TransactionState newState, TransactionState previousState) Description copied from interface:TransactionListenerSignals that the transaction state changed.- Specified by:
- transactionStateChangedin interface- TransactionListener
- Parameters:
- transaction-- FbTransactionthat changed state
 
 - 
detachingpublic void detaching(FbDatabase database) Description copied from interface:DatabaseListenerCalled before thedatabasewill be detached.This event is intended for cleanup action, implementer should take care that no exceptions are thrown from this method. - Specified by:
- detachingin interface- DatabaseListener
- Parameters:
- database- The database object that is detaching
 
 - 
detachedpublic void detached(FbDatabase database) Description copied from interface:DatabaseListenerCalled when thedatabaseconnection has been detached- Specified by:
- detachedin interface- DatabaseListener
- Parameters:
- database- The database object that was detached
 
 - 
warningReceivedpublic void warningReceived(FbDatabase database, java.sql.SQLWarning warning) Description copied from interface:DatabaseListenerCalled when a warning was received for thedatabaseconnection.In implementation it is possible that some warnings are not sent to listeners on the database, but only to listeners on specific connection derived objects (like an FbStatementimplementation).- Specified by:
- warningReceivedin interface- DatabaseListener
- Parameters:
- database- Database receiving the warning
- warning- Warning
 
 - 
isEndingTransactionprotected final boolean isEndingTransaction() - Returns:
- trueif the transaction is committing, rolling back or preparing
 
 - 
checkTransactionActiveprotected final void checkTransactionActive() throws java.sql.SQLException- Throws:
- java.sql.SQLException- when no transaction is set, or the transaction state is not- TransactionState.ACTIVE
 
 - 
checkDatabaseAttachedprotected final void checkDatabaseAttached() throws java.sql.SQLException- Throws:
- java.sql.SQLException- when no database is set, or the database is not attached
 
 - 
checkBlobOpenprotected void checkBlobOpen() throws java.sql.SQLExceptionChecks if the blob is open.NOTE: Subclasses may perform additional side effects, like queuing a server-side open for a deferred open blob. - Throws:
- java.sql.SQLException- when the blob is closed.
 
 - 
checkBlobClosedprotected void checkBlobClosed() throws java.sql.SQLException- Throws:
- java.sql.SQLException- when the blob is open.
 
 - 
getTransactionprotected FbTransaction getTransaction() 
 - 
clearTransactionprotected final void clearTransaction() 
 - 
getDatabasepublic FbDatabase getDatabase() - Specified by:
- getDatabasein interface- FbBlob
- Returns:
- The database connection that created this blob
 
 - 
getBlobInfopublic <T> T getBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws java.sql.SQLExceptionDescription copied from interface:FbBlobRequest blob info.- Specified by:
- getBlobInfoin interface- FbBlob
- 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.
 
 - 
getKnownBlobInfoItemsprotected byte[] getKnownBlobInfoItems() The known blob info items for the connected server as a blob info request buffer.- Returns:
- the known blob info items (possibly empty under implementation-specific circumstances)
- Since:
- 5.0.7
 
 - 
lengthpublic long length() throws java.sql.SQLExceptionDescription copied from interface:FbBlobRequests the blob length from the server.
 - 
errorOccurredprotected final void errorOccurred(java.sql.SQLException e) NotifiesExceptionListenerDispatcher.errorOccurred(SQLException).If there is a registered deferred exception, it is set as a next exception on ebefore notification.- Parameters:
- e- exception to notify to exception listeners
 
 - 
addExceptionListenerpublic final void addExceptionListener(ExceptionListener listener) Description copied from interface:ExceptionListenableAdds an exception listener to this object.Implementations use WeakReference.- Specified by:
- addExceptionListenerin interface- ExceptionListenable
- Parameters:
- listener- Listener to register
 
 - 
removeExceptionListenerpublic final void removeExceptionListener(ExceptionListener listener) Description copied from interface:ExceptionListenableRemoves an exception listener to this object.- Specified by:
- removeExceptionListenerin interface- ExceptionListenable
- Parameters:
- listener- Listener to remove
 
 - 
clearDatabaseprotected final void clearDatabase() 
 - 
getBlobParameterBufferprotected BlobParameterBuffer getBlobParameterBuffer() - Returns:
- The blob parameter buffer of this blob.
 
 - 
createBlobLengthProcessorprotected BlobLengthProcessor createBlobLengthProcessor() - Returns:
- New instance of BlobLengthProcessorfor this blob.
 
 - 
getMaximumSegmentSizepublic int getMaximumSegmentSize() Description copied from interface:FbBlobThe maximum segment size allowed by the protocol forFbBlob.getSegment(int)andFbBlob.putSegment(byte[]).This value is not the segment size (optionally) defined for the column. - Specified by:
- getMaximumSegmentSizein interface- FbBlob
- Returns:
- The maximum segment size allowed for get or put.
 
 
- 
 
-