public abstract class AbstractFbBlob extends java.lang.Object implements FbBlob, TransactionListener, DatabaseListener
Modifier and Type | Class and Description |
---|---|
protected static class |
AbstractFbBlob.BlobState
State of the blob.
|
FbBlob.SeekMode
Modifier and Type | Field and Description |
---|---|
protected ExceptionListenerDispatcher |
exceptionListenerDispatcher |
NO_BLOB_ID
Modifier | Constructor and Description |
---|---|
protected |
AbstractFbBlob(FbDatabase database,
FbTransaction transaction,
BlobParameterBuffer blobParameterBuffer) |
Modifier and Type | Method and Description |
---|---|
void |
addExceptionListener(ExceptionListener listener)
Adds an exception listener to this object.
|
void |
cancel()
Cancels an output blob (which means its contents will be thrown away).
|
protected abstract void |
cancelImpl()
Internal implementation of
cancel() . |
protected void |
checkBlobClosed() |
protected void |
checkBlobOpen()
Checks if the blob is open.
|
protected void |
checkDatabaseAttached() |
protected void |
checkTransactionActive() |
protected void |
clearDatabase() |
protected void |
clearDeferredException()
Clears the deferred exception.
|
protected void |
clearTransaction() |
void |
close()
Closes the blob.
|
protected abstract void |
closeImpl()
Internal implementation of
close() . |
protected BlobLengthProcessor |
createBlobLengthProcessor() |
void |
detached(FbDatabase database)
Called when the
database connection has been detached |
void |
detaching(FbDatabase database)
Called before the
database will be detached. |
protected void |
errorOccurred(java.sql.SQLException e)
|
int |
get(byte[] b,
int off,
int len)
Reads content from the blob into
b starting at off for len bytes. |
int |
get(byte[] b,
int off,
int len,
float minFillFactor)
Variant of
FbBlob.get(byte[], int, int) to exert some control over the number of requests performed. |
protected abstract int |
get(byte[] b,
int off,
int len,
int minLen)
Default implementation for
get(byte[], int, int) and get(byte[], int, int, float) . |
<T> T |
getBlobInfo(byte[] requestItems,
int bufferLength,
InfoProcessor<T> infoProcessor)
Request blob info.
|
protected BlobParameterBuffer |
getBlobParameterBuffer() |
FbDatabase |
getDatabase() |
protected byte[] |
getKnownBlobInfoItems()
The known blob info items for the connected server as a blob info request buffer.
|
int |
getMaximumSegmentSize()
The maximum segment size allowed by the protocol for
FbBlob.getSegment(int) and FbBlob.putSegment(byte[]) . |
protected AbstractFbBlob.BlobState |
getState()
The current blob state.
|
protected FbTransaction |
getTransaction() |
protected boolean |
isEndingTransaction() |
boolean |
isEof() |
boolean |
isOpen() |
long |
length()
Requests the blob length from the server.
|
void |
putSegment(byte[] segment)
Writes a segment of blob data.
|
protected void |
registerDeferredException(java.sql.SQLException deferredException)
Registers an exception as a deferred exception.
|
protected abstract void |
releaseResources()
Release Java resources held.
|
void |
removeExceptionListener(ExceptionListener listener)
Removes an exception listener to this object.
|
protected void |
resetEof()
Resets the eof state of the blob to false (not eof).
|
protected void |
setEof()
Marks this blob as EOF (End of file).
|
protected void |
setState(AbstractFbBlob.BlobState newState)
Sets the state of the blob to the specified value.
|
protected void |
throwAndClearDeferredException()
If a deferred exception is registered it is cleared and thrown.
|
void |
transactionStateChanged(FbTransaction transaction,
TransactionState newState,
TransactionState previousState)
Signals that the transaction state changed.
|
protected void |
transferDeferredExceptionTo(java.sql.SQLException target)
If a deferred exception is registered, it is cleared and set as a next exception on
target . |
protected void |
validateBufferLength(byte[] b,
int off,
int len)
Validates requested offset (
off ) and length (len ) against the array (b ). |
void |
warningReceived(FbDatabase database,
java.sql.SQLWarning warning)
Called when a warning was received for the
database connection. |
protected LockCloseable |
withLock() |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getBlobId, getBlobInfo, getHandle, getSegment, isOutput, open, put, seek
protected final ExceptionListenerDispatcher exceptionListenerDispatcher
protected AbstractFbBlob(FbDatabase database, FbTransaction transaction, BlobParameterBuffer blobParameterBuffer) throws java.sql.SQLException
java.sql.SQLException
public final boolean isOpen()
public final boolean isEof()
protected final void setEof()
For an output blob this is a no-op (as those are never end of file, unless explicitly closed)
protected final void resetEof()
This method should only be called by subclasses of this class.
protected final void setState(AbstractFbBlob.BlobState newState)
This method should only be called by subclasses of this class.
newState
- new value of stateprotected final AbstractFbBlob.BlobState getState()
public final void close() throws java.sql.SQLException
FbBlob
Closing an already closed blob is a no-op.
protected abstract void closeImpl() throws java.sql.SQLException
close()
. The implementation does not need
to check for attached database and active transaction, nor does it need to mark this blob as closed.java.sql.SQLException
public final void cancel() throws java.sql.SQLException
FbBlob
Calling cancel on an input blob will close it. Contrary to FbBlob.close()
, calling cancel on an
already closed (or cancelled) blob will throw an SQLException
.
protected abstract void cancelImpl() throws java.sql.SQLException
cancel()
. The implementation does not need
to check for attached database and active transaction, nor does it need to mark this blob as closed.java.sql.SQLException
public void putSegment(byte[] segment) throws java.sql.SQLException
FbBlob
Implementations must handle segment lengths exceeding FbBlob.getMaximumSegmentSize()
by batching. This method
should either call put(segment, 0, segment.length)
, or produce the same effects as that call.
Passing a section that is length 0 will throw an SQLException
.
putSegment
in interface FbBlob
segment
- segment to writejava.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 occurredFbBlob.put(byte[], int, int)
public final int get(byte[] b, int off, int len) throws java.sql.SQLException
FbBlob
b
starting at off
for len
bytes.
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 returns
0
when 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 len
bytes, 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, use FbBlob.get(byte[], int, int, float)
.
get
in interface FbBlob
b
- target byte arrayoff
- offset to startlen
- number of byteslen
when end-of-blob was reachedjava.sql.SQLException
- for database access errors, if off < 0
, len < 0
, or if off + len > b.length
public final int get(byte[] b, int off, int len, float minFillFactor) throws java.sql.SQLException
FbBlob
FbBlob.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 to FbBlob.get(byte[], int, int)
where
avoiding the potential inefficiencies of that method are preferred over getting all the requested len
bytes.
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 returns
0
when no bytes were read if end-of-blob is reached without reading any bytes, not -1
.
get
in interface FbBlob
b
- target byte arrayoff
- offset to startlen
- number of bytesminFillFactor
- minimum fill factor (0 < minFillFactor <= 1
)(int) (minFillFactor * len)
bytes,
unless end-of-blob is reachedjava.sql.SQLException
- for database access errors, if off < 0
, len < 0
, or if off + len > b.length
,
minFillFactor <= 0
, or minFillFactor > 1
or minFillFactor is NaN
protected abstract int get(byte[] b, int off, int len, int minLen) throws java.sql.SQLException
get(byte[], int, int)
and get(byte[], int, int, float)
.b
- target byte arrayoff
- offset to startlen
- number of bytesminLen
- minimum number of bytes to fill (must be 0 < minLen <= len
if len != 0
0
if len == 0
, will only be less than minLen
if
end-of-blob is reachedjava.sql.SQLException
- for database access errors, if off < 0
, len < 0
, or if off + len > b.length
,
or len != 0 && (minLen <= 0 || minLen > len)
protected abstract void releaseResources()
protected final void registerDeferredException(java.sql.SQLException deferredException)
This should only be used for exceptions from deferred response that need to be thrown.
deferredException
- deferred exceptionprotected final void clearDeferredException()
protected final void throwAndClearDeferredException() throws java.sql.SQLException
java.sql.SQLException
- the current deferred exception, if anyprotected final void transferDeferredExceptionTo(java.sql.SQLException target)
target
.target
- the target exception to add the deferred exception to (not null
)java.lang.NullPointerException
- if there is a deferred exception, and target == null
protected final LockCloseable withLock()
FbAttachment.withLock()
public void transactionStateChanged(FbTransaction transaction, TransactionState newState, TransactionState previousState)
TransactionListener
transactionStateChanged
in interface TransactionListener
transaction
- FbTransaction
that changed statepublic void detaching(FbDatabase database)
DatabaseListener
database
will be detached.
This event is intended for cleanup action, implementer should take care that no exceptions are thrown from this method.
detaching
in interface DatabaseListener
database
- The database object that is detachingpublic void detached(FbDatabase database)
DatabaseListener
database
connection has been detacheddetached
in interface DatabaseListener
database
- The database object that was detachedpublic void warningReceived(FbDatabase database, java.sql.SQLWarning warning)
DatabaseListener
database
connection.
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 FbStatement
implementation).
warningReceived
in interface DatabaseListener
database
- Database receiving the warningwarning
- Warningprotected final boolean isEndingTransaction()
true
if the transaction is committing, rolling back or preparingprotected final void checkTransactionActive() throws java.sql.SQLException
java.sql.SQLException
- when no transaction is set, or the transaction state is not TransactionState.ACTIVE
protected final void checkDatabaseAttached() throws java.sql.SQLException
java.sql.SQLException
- when no database is set, or the database is not attachedprotected void checkBlobOpen() throws java.sql.SQLException
NOTE: Subclasses may perform additional side effects, like queuing a server-side open for a deferred open blob.
java.sql.SQLException
- when the blob is closed.protected void checkBlobClosed() throws java.sql.SQLException
java.sql.SQLException
- When the blob is open.protected FbTransaction getTransaction()
protected final void clearTransaction()
public FbDatabase getDatabase()
getDatabase
in interface FbBlob
public <T> T getBlobInfo(byte[] requestItems, int bufferLength, InfoProcessor<T> infoProcessor) throws java.sql.SQLException
FbBlob
getBlobInfo
in interface FbBlob
requestItems
- Array of info items to requestbufferLength
- Response buffer length to useinfoProcessor
- Implementation of InfoProcessor
to transform
the info responsejava.sql.SQLException
- For errors retrieving or transforming the response.protected byte[] getKnownBlobInfoItems()
public long length() throws java.sql.SQLException
FbBlob
protected final void errorOccurred(java.sql.SQLException e)
ExceptionListenerDispatcher.errorOccurred(SQLException)
.
If there is a registered deferred exception, it is set as a next exception on e
before notification.
e
- exception to notify to exception listenerspublic final void addExceptionListener(ExceptionListener listener)
ExceptionListenable
Implementations use WeakReference
.
addExceptionListener
in interface ExceptionListenable
listener
- Listener to registerpublic final void removeExceptionListener(ExceptionListener listener)
ExceptionListenable
removeExceptionListener
in interface ExceptionListenable
listener
- Listener to removeprotected final void clearDatabase()
protected BlobParameterBuffer getBlobParameterBuffer()
protected BlobLengthProcessor createBlobLengthProcessor()
BlobLengthProcessor
for this blob.public int getMaximumSegmentSize()
FbBlob
FbBlob.getSegment(int)
and FbBlob.putSegment(byte[])
.
This value is not the segment size (optionally) defined for the column.
getMaximumSegmentSize
in interface FbBlob
protected final void validateBufferLength(byte[] b, int off, int len) throws java.sql.SQLException
off
) and length (len
) against the array (b
).b
- arrayoff
- position in arraylen
- length from off
java.sql.SQLException
- if off < 0
, len < 0
, or if off + len > b.length
Copyright © 2001-2025 Jaybird (Firebird JDBC) team. All rights reserved.