Class EmbedBlob
- java.lang.Object
-
- org.apache.derby.impl.jdbc.ConnectionChild
-
- org.apache.derby.impl.jdbc.EmbedBlob
-
- All Implemented Interfaces:
java.sql.Blob
,EngineLOB
final class EmbedBlob extends ConnectionChild implements java.sql.Blob, EngineLOB
Implements java.sql.Blob (see the JDBC 2.0 spec). A blob sits on top of a BINARY, VARBINARY or LONG VARBINARY column. If its data is small (less than 1 page) it is a byte array taken from the SQLBit class. If it is large (more than 1 page) it is a long column in the database. The long column is accessed as a stream, and is implemented in store as an OverflowInputStream. The Resetable interface allows sending messages to that stream to initialize itself (reopen its container and lock the corresponding row) and to reset itself to the beginning. NOTE: In the case that the data is large, it is represented as a stream. This stream is returned to the user in the getBinaryStream() method. This means that we have limited control over the state of the stream, since the user can read bytes from it at any time. Thus all methods here reset the stream to the beginning before doing any work. CAVEAT: The methods may not behave correctly if a user sets up multiple threads and sucks data from the stream (returned from getBinaryStream()) at the same time as calling the Blob methods.Supports
- JSR169 - no subsetting for java.sql.Blob
- JDBC 2.0
- JDBC 3.0 - no new dependencies on new JDBC 3.0 or JDK 1.4 classes, new update methods can safely be added into implementation.
-
-
Field Summary
Fields Modifier and Type Field Description private LOBStreamControl
control
private boolean
isValid
private int
locator
Locator value for this Blob, used as a handle by the client driver to map operations to the correct Blob on the server side.private boolean
materialized
Tells whether the Blob has been materialized or not.private PositionedStoreStream
myStream
The underlying positionable store stream, if any.private long
streamLength
Length of the stream representing the Blob.private int
streamPositionOffset
Position offset for the stream representing the Blob, if any.-
Fields inherited from class org.apache.derby.impl.jdbc.ConnectionChild
factory, localConn
-
-
Constructor Summary
Constructors Modifier Constructor Description (package private)
EmbedBlob(byte[] blobBytes, EmbedConnection con)
This constructor is used to create a empty Blob object.protected
EmbedBlob(DataValueDescriptor dvd, EmbedConnection con)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private boolean
checkMatch(byte[] pattern, long pos)
Checks if the pattern (starting from the second byte) appears inside the Blob content.private boolean
checkMatch(java.sql.Blob pattern, long pos)
Checks if the pattern (starting from the second byte) appears inside the Blob content.private void
checkValidity()
protected void
finalize()
void
free()
This method frees theBlob
object and releases the resources that it holds.java.io.InputStream
getBinaryStream()
Retrieves theBLOB
designated by thisBlob
instance as a stream.java.io.InputStream
getBinaryStream(long pos, long length)
Returns anInputStream
object that contains a partialBlob
value, starting with the byte specified by pos, which is length bytes in length.byte[]
getBytes(long startPos, int length)
Returns as an array of bytes part or all of theBLOB
value that thisBlob
object designates.int
getLocator()
Return locator for this lob.private java.sql.SQLException
handleMyExceptions(java.lang.Throwable t)
private int
handleStreamValue(java.io.InputStream dvdStream, EmbedConnection con)
Constructs a Blob object on top of a stream.(package private) boolean
isMaterialized()
Returns if blob data is stored locally (using LOBStreamControl).long
length()
Returns the number of bytes in theBLOB
value designated by thisBlob
object.long
position(byte[] pattern, long start)
Determines the byte position at which the specified bytepattern
begins within theBLOB
value that thisBlob
object represents.long
position(java.sql.Blob pattern, long start)
Determines the byte position in theBLOB
value designated by thisBlob
object at whichpattern
begins.private int
read(long pos)
Reads one byte from the Blob at the specified position.java.io.OutputStream
setBinaryStream(long pos)
JDBC 3.0 Retrieves a stream that can be used to write to the BLOB value that this Blob object represents.private long
setBlobPosition(long logicalPos)
Sets the position of the Blob tologicalPos
, where position 0 is the beginning of the Blob content.int
setBytes(long pos, byte[] bytes)
Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.int
setBytes(long pos, byte[] bytes, int offset, int len)
Writes all or part of the given array of byte array to the BLOB value that this Blob object represents and returns the number of bytes written.void
truncate(long len)
JDBC 3.0 Truncates the BLOB value that this Blob object represents to be len bytes in length.-
Methods inherited from class org.apache.derby.impl.jdbc.ConnectionChild
commitIfAutoCommit, commitIfNeeded, getCal, getConnectionSynchronization, getEmbedConnection, getLanguageConnectionContext, getLCC, handleException, needCommit, newSQLException, restoreContextStack, restoreIntrFlagIfSeen, setupContextStack
-
-
-
-
Field Detail
-
materialized
private boolean materialized
Tells whether the Blob has been materialized or not.Materialization happens when the Blob is updated by the user. A materialized Blob is represented either in memory or in a temporary file on disk, depending on size.
A Blob that has not been materialized is represented by a stream into the Derby store, and is read-only.
-
myStream
private PositionedStoreStream myStream
The underlying positionable store stream, if any.If
materialized
istrue
, the stream isnull
.
-
locator
private int locator
Locator value for this Blob, used as a handle by the client driver to map operations to the correct Blob on the server side.- See Also:
getLocator()
-
streamLength
private long streamLength
Length of the stream representing the Blob.Set to -1 when the stream has been
materialized
or the length of the stream is not currently known.
-
streamPositionOffset
private final int streamPositionOffset
Position offset for the stream representing the Blob, if any.This offset accounts for the bytes encoding the stream length at the head of the stream. Data byte
pos
is atpos + streamPositionOffset
in the underlying stream. Set toInteger.MIN_VALUE
if the Blob isn't represented by a store stream.
-
isValid
private boolean isValid
-
control
private LOBStreamControl control
-
-
Constructor Detail
-
EmbedBlob
EmbedBlob(byte[] blobBytes, EmbedConnection con) throws java.sql.SQLException
This constructor is used to create a empty Blob object. It is used by the Connection interface method createBlob().- Parameters:
blobBytes
- A byte array containing the data to be stores in the Blob.con
- The EmbedConnection object associated with this Blob object.- Throws:
java.sql.SQLException
-
EmbedBlob
protected EmbedBlob(DataValueDescriptor dvd, EmbedConnection con) throws StandardException, java.sql.SQLException
- Throws:
StandardException
java.sql.SQLException
-
-
Method Detail
-
handleStreamValue
private int handleStreamValue(java.io.InputStream dvdStream, EmbedConnection con) throws StandardException, java.sql.SQLException
Constructs a Blob object on top of a stream.- Parameters:
dvdStream
- the source streamcon
- the connection owning the Blob- Returns:
- The offset into the stream where the user data begins (used if resetting the stream).
- Throws:
StandardException
- if accessing the stream fails, or if writing data to temporary storage failsjava.sql.SQLException
-
setBlobPosition
private long setBlobPosition(long logicalPos) throws StandardException, java.io.IOException
Sets the position of the Blob tologicalPos
, where position 0 is the beginning of the Blob content.The position is only guaranteed to be valid from the time this method is invoked until the synchronization monitor is released, or until the next invokation of this method.
The position is logical in the sense that it specifies the requested position in the Blob content. This position might be at a different position in the underlying representation, for instance the Derby store stream prepends the Blob content with a length field.
- Parameters:
logicalPos
- requested Blob position, 0-based- Returns:
- The new position, which will be equal to the requested position.
- Throws:
java.io.IOException
- if reading/accessing the Blob failsStandardException
- throws BLOB_POSITION_TOO_LARGE if the requested position is larger than the Blob length, throws other SQL states if resetting the stream fails
-
read
private int read(long pos) throws java.io.IOException, StandardException
Reads one byte from the Blob at the specified position.Depending on the representation, this might result in a read from a byte array, a temporary file on disk or from a Derby store stream.
- Returns:
- the byte at the current position, or -1 if end of file has been reached
- Throws:
java.io.IOException
- if reading from the underlying data representation failsStandardException
-
length
public long length() throws java.sql.SQLException
Returns the number of bytes in theBLOB
value designated by thisBlob
object.- Specified by:
length
in interfacejava.sql.Blob
- Returns:
- length of the
BLOB
in bytes - Throws:
java.sql.SQLException
- if there is an error accessing the length of theBLOB
-
getBytes
public byte[] getBytes(long startPos, int length) throws java.sql.SQLException
Returns as an array of bytes part or all of theBLOB
value that thisBlob
object designates. The byte array contains up tolength
consecutive bytes starting at positionstartPos
. The starting position must be between 1 and the length of the BLOB plus 1. This allows for zero-length BLOB values, from which only zero-length byte arrays can be returned. If a larger length is requested than there are bytes available, characters from the start position to the end of the BLOB are returned.- Specified by:
getBytes
in interfacejava.sql.Blob
- Parameters:
startPos
- the ordinal position of the first byte in theBLOB
value to be extracted; the first byte is at position 1length
- is the number of consecutive bytes to be copied- Returns:
- a byte array containing up to
length
consecutive bytes from theBLOB
value designated by thisBlob
object, starting with the byte at positionstartPos
. - Throws:
java.sql.SQLException
- if there is an error accessing theBLOB
NOTE: If the starting position is the length of the BLOB plus 1, zero bytess are returned regardless of the length requested.
-
getBinaryStream
public java.io.InputStream getBinaryStream() throws java.sql.SQLException
Retrieves theBLOB
designated by thisBlob
instance as a stream.- Specified by:
getBinaryStream
in interfacejava.sql.Blob
- Returns:
- a stream containing the
BLOB
data - Throws:
java.sql.SQLException
- if there is an error accessing theBLOB
-
position
public long position(byte[] pattern, long start) throws java.sql.SQLException
Determines the byte position at which the specified bytepattern
begins within theBLOB
value that thisBlob
object represents. The search forpattern
. begins at positionstart
- Specified by:
position
in interfacejava.sql.Blob
- Parameters:
pattern
- the byte array for which to searchstart
- the position at which to begin searching; the first position is 1- Returns:
- the position at which the pattern appears, else -1.
- Throws:
java.sql.SQLException
- if there is an error accessing theBLOB
-
checkMatch
private boolean checkMatch(byte[] pattern, long pos) throws java.io.IOException, StandardException
Checks if the pattern (starting from the second byte) appears inside the Blob content.At this point, the first byte of the pattern must already have been matched, and
pos
must be pointing at the second byte to compare.- Parameters:
pattern
- the byte array to search for, passed in by the userpos
- the position in the Blob content to start searching from- Returns:
true
if a match is found,false
if not.- Throws:
java.io.IOException
StandardException
-
position
public long position(java.sql.Blob pattern, long start) throws java.sql.SQLException
Determines the byte position in theBLOB
value designated by thisBlob
object at whichpattern
begins. The search begins at positionstart
.- Specified by:
position
in interfacejava.sql.Blob
- Parameters:
pattern
- theBlob
object designating theBLOB
value for which to searchstart
- the position in theBLOB
value at which to begin searching; the first position is 1- Returns:
- the position at which the pattern begins, else -1
- Throws:
java.sql.SQLException
- if there is an error accessing theBLOB
-
checkMatch
private boolean checkMatch(java.sql.Blob pattern, long pos) throws java.io.IOException, StandardException
Checks if the pattern (starting from the second byte) appears inside the Blob content.- Parameters:
pattern
- the Blob to search for, passed in by the userpos
- the position in the Blob (this) content to start searching- Returns:
true
if a match is found,false
if not.- Throws:
java.io.IOException
StandardException
-
handleMyExceptions
private java.sql.SQLException handleMyExceptions(java.lang.Throwable t) throws java.sql.SQLException
- Throws:
java.sql.SQLException
-
finalize
protected void finalize()
- Overrides:
finalize
in classjava.lang.Object
-
setBytes
public int setBytes(long pos, byte[] bytes) throws java.sql.SQLException
Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.- Specified by:
setBytes
in interfacejava.sql.Blob
- Parameters:
pos
- the position in the BLOB object at which to start writingbytes
- the array of bytes to be written to the BLOB value that this Blob object represents- Returns:
- The number of bytes written to the BLOB.
- Throws:
java.sql.SQLException
- if writing the bytes to the BLOB fails- Since:
- 1.4
-
setBytes
public int setBytes(long pos, byte[] bytes, int offset, int len) throws java.sql.SQLException
Writes all or part of the given array of byte array to the BLOB value that this Blob object represents and returns the number of bytes written. Writing starts at position pos in the BLOB value; len bytes from the given byte array are written.- Specified by:
setBytes
in interfacejava.sql.Blob
- Parameters:
pos
- the position in the BLOB object at which to start writingbytes
- the array of bytes to be written to the BLOB value that this Blob object representsoffset
- the offset into the byte array at which to start reading the bytes to be writtenlen
- the number of bytes to be written to the BLOB value from the array of bytes bytes- Returns:
- The number of bytes written to the BLOB.
- Throws:
java.sql.SQLException
- if writing the bytes to the BLOB failsjava.lang.IndexOutOfBoundsException
- iflen
is larger thanbytes.length - offset
- Since:
- 1.4
-
setBinaryStream
public java.io.OutputStream setBinaryStream(long pos) throws java.sql.SQLException
JDBC 3.0 Retrieves a stream that can be used to write to the BLOB value that this Blob object represents. The stream begins at position pos.- Specified by:
setBinaryStream
in interfacejava.sql.Blob
- Parameters:
pos
- - the position in the BLOB object at which to start writing- Returns:
- a java.io.OutputStream object to which data can be written
- Throws:
java.sql.SQLException
- Feature not implemented for now.
-
truncate
public void truncate(long len) throws java.sql.SQLException
JDBC 3.0 Truncates the BLOB value that this Blob object represents to be len bytes in length.- Specified by:
truncate
in interfacejava.sql.Blob
- Parameters:
len
- - the length, in bytes, to which the BLOB value that this Blob object represents should be truncated- Throws:
java.sql.SQLException
- Feature not implemented for now.
-
free
public void free() throws java.sql.SQLException
This method frees theBlob
object and releases the resources that it holds. The object is invalid once thefree
method is called. Iffree
is called multiple times, the subsequent calls tofree
are treated as a no-op.
-
getBinaryStream
public java.io.InputStream getBinaryStream(long pos, long length) throws java.sql.SQLException
Returns anInputStream
object that contains a partialBlob
value, starting with the byte specified by pos, which is length bytes in length.- Specified by:
getBinaryStream
in interfacejava.sql.Blob
- Parameters:
pos
- the offset to the first byte of the partial value to be retrieved. The first byte in theBlob
is at position 1length
- the length in bytes of the partial value to be retrieved- Returns:
- through which the partial
Blob
value can be read. - Throws:
java.sql.SQLException
- if pos is less than 1 or if pos is greater than the number of bytes in theBlob
or ifpos + length
is greater thanBlob.length() +1
-
checkValidity
private void checkValidity() throws java.sql.SQLException
- Throws:
java.sql.SQLException
-
isMaterialized
boolean isMaterialized()
Returns if blob data is stored locally (using LOBStreamControl).- Returns:
- true if materialized else false
-
getLocator
public int getLocator()
Return locator for this lob.- Specified by:
getLocator
in interfaceEngineLOB
- Returns:
- The locator identifying this lob.
-
-