org.apache.derby.impl.jdbc
Class EmbedBlob

java.lang.Object
  extended by org.apache.derby.impl.jdbc.ConnectionChild
      extended by 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


Field Summary
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
(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
private  boolean checkMatch(java.sql.Blob pattern, long pos)
          Checks if the pattern (starting from the second byte) appears inside the Blob content.
private  boolean checkMatch(byte[] 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 the Blob object and releases the resources that it holds.
 java.io.InputStream getBinaryStream()
          Retrieves the BLOB designated by this Blob instance as a stream.
 java.io.InputStream getBinaryStream(long pos, long length)
          Returns an InputStream object that contains a partial Blob 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 the BLOB value that this Blob 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 the BLOB value designated by this Blob object.
 long position(java.sql.Blob pattern, long start)
          Determines the byte position in the BLOB value designated by this Blob object at which pattern begins.
 long position(byte[] pattern, long start)
          Determines the byte position at which the specified byte pattern begins within the BLOB value that this Blob object represents.
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 to logicalPos, 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, handleException, needCommit, newSQLException, newSQLException, newSQLException, restoreContextStack, setupContextStack
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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 is true, the stream is null.


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 at pos + streamPositionOffset in the underlying stream. Set to Integer.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
Throws:
StandardException
Method Detail

handleStreamValue

private int handleStreamValue(java.io.InputStream dvdStream,
                              EmbedConnection con)
                       throws StandardException
Constructs a Blob object on top of a stream.

Parameters:
dvdStream - the source stream
con - 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 fails

setBlobPosition

private long setBlobPosition(long logicalPos)
                      throws StandardException,
                             java.io.IOException
Sets the position of the Blob to logicalPos, 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 fails
StandardException - 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 fails
StandardException

length

public long length()
            throws java.sql.SQLException
Returns the number of bytes in the BLOB value designated by this Blob object.

Specified by:
length in interface java.sql.Blob
Returns:
length of the BLOB in bytes
Throws:
java.sql.SQLException - if there is an error accessing the length of the BLOB

getBytes

public byte[] getBytes(long startPos,
                       int length)
                throws java.sql.SQLException
Returns as an array of bytes part or all of the BLOB value that this Blob object designates. The byte array contains up to length consecutive bytes starting at position startPos. 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 interface java.sql.Blob
Parameters:
startPos - the ordinal position of the first byte in the BLOB value to be extracted; the first byte is at position 1
length - is the number of consecutive bytes to be copied
Returns:
a byte array containing up to length consecutive bytes from the BLOB value designated by this Blob object, starting with the byte at position startPos.
Throws:
java.sql.SQLException - if there is an error accessing the BLOB 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 the BLOB designated by this Blob instance as a stream.

Specified by:
getBinaryStream in interface java.sql.Blob
Returns:
a stream containing the BLOB data
Throws:
java.sql.SQLException - if there is an error accessing the BLOB

position

public long position(byte[] pattern,
                     long start)
              throws java.sql.SQLException
Determines the byte position at which the specified byte pattern begins within the BLOB value that this Blob object represents. The search for patternstart

Specified by:
position in interface java.sql.Blob
Parameters:
pattern - the byte array for which to search
start - 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 the BLOB

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 user
pos - 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 the BLOB value designated by this Blob object at which pattern begins. The search begins at position start.

Specified by:
position in interface java.sql.Blob
Parameters:
pattern - the Blob object designating the BLOB value for which to search
start - the position in the BLOB 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 the BLOB

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 user
pos - 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 class java.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 interface java.sql.Blob
Parameters:
pos - the position in the BLOB object at which to start writing
bytes - 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 interface java.sql.Blob
Parameters:
pos - the position in the BLOB object at which to start writing
bytes - the array of bytes to be written to the BLOB value that this Blob object represents
offset - the offset into the byte array at which to start reading the bytes to be written
len - 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 fails
java.lang.IndexOutOfBoundsException - if len is larger than bytes.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 interface java.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 interface java.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 the Blob object and releases the resources that it holds. The object is invalid once the free method is called. If free is called multiple times, the subsequent calls to free are treated as a no-op.

Specified by:
free in interface java.sql.Blob
Specified by:
free in interface EngineLOB
Throws:
java.sql.SQLException - if an error occurs releasing the Blob's resources

getBinaryStream

public java.io.InputStream getBinaryStream(long pos,
                                           long length)
                                    throws java.sql.SQLException
Returns an InputStream object that contains a partial Blob value, starting with the byte specified by pos, which is length bytes in length.

Specified by:
getBinaryStream in interface java.sql.Blob
Parameters:
pos - the offset to the first byte of the partial value to be retrieved. The first byte in the Blob is at position 1
length - 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 the Blob or if pos + length is greater than Blob.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 interface EngineLOB
Returns:
The locator identifying this lob.

Built on Thu 2012-03-29 21:53:33+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.