Apache Derby Client JDBC Driver 10.17.1.0 · org.apache.derby.client.am.ClientBlob

Modifier and Type	Field and Description
pack-priv InputStream	binaryStream_
pack-priv byte[]	binaryString_
pack-priv int	dataOffset_

Access	Constructor and Description
public	ClientBlob(byte[] binaryString, Agent agent, int dataOffset)
pack-priv	ClientBlob(Agent agent, InputStream binaryStream, int length)
pack-priv	ClientBlob(Agent agent, InputStream the stream to get data from binaryStream) Create a new `Blob` from a stream with unknown length Important Note This constructor is a temporary solution for implementing lengthless overloads in the JDBC4 API.
public	ClientBlob(Agent context for this Blob object (incl. connection) agent, int reference id to Blob value on server locator) Create a `Blob` object for a Blob value stored on the server and indentified by `locator`.

Method Summary

Modifier and Type	Method and Description
private long	binaryStringPosition(byte[] pattern, long start)
public void	free() Implements java.sql.Blob.free. This method frees the `Blob` object and releases the resources that it holds.
public InputStream	getBinaryStream() Implements java.sql.Blob.getBinaryStream. Retrieves the `BLOB` value designated by this `Blob` instance as a stream.
public InputStream	Returns: `InputStream` through which the partial `Blob` value can be read. getBinaryStream(long the offset to the first byte of the partial value to be retrieved. The first byte in the `Blob` is at position 1. pos, long the length in bytes of the partial value to be retrieved length) Implements java.sql.Blob.getBinaryStream. Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length.
pack-priv InputStream	getBinaryStreamX()
public byte[]	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`. getBytes(long the ordinal position of the first byte in the `BLOB` value to be extracted; the first byte is at position 1 pos, int is the number of consecutive bytes to be copied length) Implements java.sql.Blob.getBytes. Returns as an array of bytes part or all of the `BLOB` value that this `Blob` object designates.
private byte[]	getBytesX(long pos, int length)
pack-priv long	Returns: length of Blob in bytes getLocatorLength() Overrides org.apache.derby.client.am.Lob.getLocatorLength. Get the length in bytes of the `Blob` value represented by this locator based <blob> object.
public boolean	isBinaryStream()
public boolean	isBinaryString()
private boolean	isSubString(byte[] pattern, int index)
public long	length() Implements abstract org.apache.derby.client.am.Lob.length. Implements java.sql.Blob.length. Returns the number of bytes in the `BLOB` value designated by this `Blob` object.
protected void	materializeStream() Implements abstract org.apache.derby.client.am.Lob.materializeStream. Materialize the stream used for input to the database.
public long	position(byte[] the byte array for which to search pattern, long the position at which to begin searching; the first position is 1 start) Implements java.sql.Blob.position. Retrieves the byte position at which the specified byte array `pattern` begins within the `BLOB` value that this `Blob` object represents.
public long	position(Blob the `Blob` object designating the `BLOB` value for which to search pattern, long the position in the `BLOB` value at which to begin searching; the first position is 1 start) Implements java.sql.Blob.position. Retrieves the byte position in the `BLOB` value designated by this `Blob` object at which `pattern` begins.
private long	positionX(byte[] pattern, long start)
private long	positionX(Blob pattern, long start)
public OutputStream	setBinaryStream(long the position in the `BLOB` value at which to start writing; the first position is 1 pos) Implements java.sql.Blob.setBinaryStream. Retrieves a stream that can be used to write to the `BLOB` value that this `Blob` object represents.
public int	setBytes(long the position in the `BLOB` object at which to start writing; the first position is 1 pos, byte[] the array of bytes to be written to the `BLOB` value that this `Blob` object represents bytes) Implements java.sql.Blob.setBytes. 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.
public int	setBytes(long the position in the `BLOB` object at which to start writing; the first position is 1 pos, byte[] the array of bytes to be written to this `BLOB` object bytes, int the offset into the array `bytes` at which to start reading the bytes to be set offset, int the number of bytes to be written to the `BLOB` value from the array of bytes `bytes` len) Implements java.sql.Blob.setBytes. Writes all or part of the given `byte` array to the `BLOB` value that this `Blob` object represents and returns the number of bytes written.
pack-priv int	setBytesX(long pos, byte[] bytes, int offset, int len)
public void	truncate(long the length, in bytes, to which the `BLOB` value that this `Blob` object represents should be truncated len) Implements java.sql.Blob.truncate. Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length.

Inherited from org.apache.derby.client.am.Lob:: checkForClosedConnection checkForLocatorValidity checkPosAndLength checkValidity completeLocalCommit completeLocalRollback getAgent getLocator getUpdateCount incrementUpdateCount isLayerBStreamingPossible isLocator listenToUnitOfWork materializeStream setSqlLength sqlLength willBeLayerBStreamed

binaryStream_	back to summary
pack-priv InputStream binaryStream_

binaryString_	back to summary
pack-priv byte[] binaryString_

dataOffset_	back to summary
pack-priv int dataOffset_

ClientBlob	back to summary
public ClientBlob(byte[] binaryString, Agent agent, int dataOffset)

ClientBlob	back to summary
pack-priv ClientBlob(Agent agent, InputStream binaryStream, int length)

ClientBlob	back to summary
pack-priv ClientBlob(Agent agent, InputStream binaryStream) Create a new `Blob` from a stream with unknown length Important Note This constructor is a temporary solution for implementing lengthless overloads in the JDBC4 API. Before a proper solution can be implemented, we need to enable streaming without having to know the stream length in the DRDA protocol. See Jira DERBY-1471 and DERBY-1417 for more details. Shortcomings: This constructor will cause the whole stream to be materialized to determine its length. If the stream is big enough, the client will fail with an OutOfMemoryError. Since this is a temporary solution, state checking is not added to all methods as it would clutter up the class severely. After using the constructor, the `length`-method must be called, which will materialize the stream and determine the length. Do not pass a Blob object created with this constructor to the user! Parameters binaryStream:InputStream the stream to get data from

ClientBlob	back to summary
public ClientBlob(Agent agent, int locator) Create a `Blob` object for a Blob value stored on the server and indentified by `locator`. Parameters agent:Agent context for this Blob object (incl. connection) locator:int reference id to Blob value on server

Method Detail

binaryStringPosition	back to summary
private long binaryStringPosition(byte[] pattern, long start)

free back to summary

free	back to summary
public void free() throws SQLException Implements java.sql.Blob.free. 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. Exceptions SQLException: if an error occurs releasing the Blob's resources

public void free() throws SQLException

Implements java.sql.Blob.free.

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.

Exceptions

SQLException:: if an error occurs releasing the Blob's resources

getBinaryStream back to summary

getBinaryStream	back to summary
public InputStream getBinaryStream() throws SQLException Implements java.sql.Blob.getBinaryStream. Doc from java.sql.Blob.getBinaryStream. Retrieves the `BLOB` value designated by this `Blob` instance as a stream. Returns:InputStream a stream containing the `BLOB` data Exceptions SQLException: if there is an error accessing the `BLOB` value

public InputStream getBinaryStream() throws SQLException

Implements java.sql.Blob.getBinaryStream.

Doc from java.sql.Blob.getBinaryStream.

Retrieves the BLOB value designated by this Blob instance as a stream.

Returns:InputStream

a stream containing the BLOB data

Exceptions

SQLException:: if there is an error accessing the BLOB value

getBinaryStream back to summary

getBinaryStream	back to summary
public InputStream getBinaryStream(long pos, long length) throws SQLException Implements java.sql.Blob.getBinaryStream. Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length. Parameters pos:long the offset to the first byte of the partial value to be retrieved. The first byte in the `Blob` is at position 1. length:long the length in bytes of the partial value to be retrieved Returns:InputStream `InputStream` through which the partial `Blob` value can be read. Exceptions 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`

public InputStream getBinaryStream(long pos, long length) throws SQLException

Implements java.sql.Blob.getBinaryStream.

Returns an InputStream object that contains a partial Blob value, starting with the byte specified by pos, which is length bytes in length.

Parameters

pos:long: the offset to the first byte of the partial value to be retrieved. The first byte in the Blob is at position 1.
length:long: the length in bytes of the partial value to be retrieved

Returns:InputStream

InputStream through which the partial Blob value can be read.

Exceptions

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

getBinaryStreamX	back to summary
pack-priv InputStream getBinaryStreamX() throws SqlException

getBytes back to summary

getBytes	back to summary
public byte[] getBytes(long pos, int length) throws SQLException Implements java.sql.Blob.getBytes. 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 `pos`. 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. Parameters pos:long the ordinal position of the first byte in the `BLOB` value to be extracted; the first byte is at position 1 length:int is the number of consecutive bytes to be copied Returns:byte[] 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`. Exceptions 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.

public byte[] getBytes(long pos, int length) throws SQLException

Implements java.sql.Blob.getBytes.

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 pos. 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.

Parameters

pos:long: the ordinal position of the first byte in the BLOB value to be extracted; the first byte is at position 1
length:int: is the number of consecutive bytes to be copied

Returns:byte[]

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.

Exceptions

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.

getBytesX	back to summary
private byte[] getBytesX(long pos, int length) throws SqlException

getLocatorLength back to summary

getLocatorLength	back to summary
pack-priv long getLocatorLength() throws SqlException Overrides org.apache.derby.client.am.Lob.getLocatorLength. Get the length in bytes of the `Blob` value represented by this locator based object. A stored procedure call will be made to get it from the server. Returns:long length of Blob in bytes

pack-priv long getLocatorLength() throws SqlException

Overrides org.apache.derby.client.am.Lob.getLocatorLength.

Get the length in bytes of the Blob value represented by this locator based object. A stored procedure call will be made to get it from the server.

Returns:long: length of Blob in bytes

isBinaryStream	back to summary
public boolean isBinaryStream()

isBinaryString	back to summary
public boolean isBinaryString()

isSubString	back to summary
private boolean isSubString(byte[] pattern, int index)

length back to summary

length	back to summary
public long length() throws SQLException Implements abstract org.apache.derby.client.am.Lob.length. Implements java.sql.Blob.length. Doc from java.sql.Blob.length. Returns the number of bytes in the `BLOB` value designated by this `Blob` object. Returns:long length of the `BLOB` in bytes Exceptions SQLException: if there is an error accessing the length of the `BLOB`

public long length() throws SQLException

Implements abstract org.apache.derby.client.am.Lob.length.

Implements java.sql.Blob.length.

Doc from java.sql.Blob.length.

Returns the number of bytes in the BLOB value designated by this Blob object.

Returns:long

length of the BLOB in bytes

Exceptions

SQLException:: if there is an error accessing the length of the BLOB

materializeStream	back to summary
protected void materializeStream() throws SqlException Implements abstract org.apache.derby.client.am.Lob.materializeStream. Materialize the stream used for input to the database. Exceptions SqlException: on error

materializeStream

back to summary

protected void materializeStream() throws SqlException

Implements abstract org.apache.derby.client.am.Lob.materializeStream.

Materialize the stream used for input to the database.

Exceptions

SqlException:: on error

position back to summary

position	back to summary
public long position(byte[] pattern, long start) throws SQLException Implements java.sql.Blob.position. Doc from java.sql.Blob.position. Retrieves the byte position at which the specified byte array `pattern` begins within the `BLOB` value that this `Blob` object represents. The search for `pattern` begins at position `start`. Parameters pattern:byte[] the byte array for which to search start:long the position at which to begin searching; the first position is 1 Returns:long the position at which the pattern appears, else -1 Exceptions SQLException: if there is an error accessing the `BLOB` or if start is less than 1

public long position(byte[] pattern, long start) throws SQLException

Implements java.sql.Blob.position.

Doc from java.sql.Blob.position.

Retrieves the byte position at which the specified byte array pattern begins within the BLOB value that this Blob object represents. The search for pattern begins at position start.

Parameters

pattern:byte[]: the byte array for which to search
start:long: the position at which to begin searching; the first position is 1

Returns:long

the position at which the pattern appears, else -1

Exceptions

SQLException:: if there is an error accessing the BLOB or if start is less than 1

position back to summary

position	back to summary
public long position(Blob pattern, long start) throws SQLException Implements java.sql.Blob.position. Doc from java.sql.Blob.position. Retrieves the byte position in the `BLOB` value designated by this `Blob` object at which `pattern` begins. The search begins at position `start`. Parameters pattern:Blob the `Blob` object designating the `BLOB` value for which to search start:long the position in the `BLOB` value at which to begin searching; the first position is 1 Returns:long the position at which the pattern begins, else -1 Exceptions SQLException: if there is an error accessing the `BLOB` value or if start is less than 1

public long position(Blob pattern, long start) throws SQLException

Implements java.sql.Blob.position.

Doc from java.sql.Blob.position.

Retrieves the byte position in the BLOB value designated by this Blob object at which pattern begins. The search begins at position start.

Parameters

pattern:Blob: the Blob object designating the BLOB value for which to search
start:long: the position in the BLOB value at which to begin searching; the first position is 1

Returns:long

the position at which the pattern begins, else -1

Exceptions

SQLException:: if there is an error accessing the BLOB value or if start is less than 1

positionX	back to summary
private long positionX(byte[] pattern, long start) throws SqlException

positionX	back to summary
private long positionX(Blob pattern, long start) throws SqlException

setBinaryStream back to summary

setBinaryStream	back to summary
public OutputStream setBinaryStream(long pos) throws SQLException Implements java.sql.Blob.setBinaryStream. Doc from java.sql.Blob.setBinaryStream. Retrieves a stream that can be used to write to the `BLOB` value that this `Blob` object represents. The stream begins at position `pos`. The bytes written to the stream will overwrite the existing bytes in the `Blob` object starting at the position `pos`. If the end of the `Blob` value is reached while writing to the stream, then the length of the `Blob` value will be increased to accommodate the extra bytes. Note If the value specified for `pos` is greater than the length+1 of the `BLOB` value then the behavior is undefined. Some JDBC drivers may throw an `SQLException` while other drivers may support this operation. Parameters pos:long the position in the `BLOB` value at which to start writing; the first position is 1 Returns:OutputStream a `java.io.OutputStream` object to which data can be written Exceptions SQLException: if there is an error accessing the `BLOB` value or if pos is less than 1

public OutputStream setBinaryStream(long pos) throws SQLException

Implements java.sql.Blob.setBinaryStream.

Doc from java.sql.Blob.setBinaryStream.

Retrieves a stream that can be used to write to the BLOB value that this Blob object represents. The stream begins at position pos. The bytes written to the stream will overwrite the existing bytes in the Blob object starting at the position pos. If the end of the Blob value is reached while writing to the stream, then the length of the Blob value will be increased to accommodate the extra bytes.

Note

If the value specified for pos is greater than the length+1 of the BLOB value then the behavior is undefined. Some JDBC drivers may throw an SQLException while other drivers may support this operation.

Parameters

pos:long: the position in the BLOB value at which to start writing; the first position is 1

Returns:OutputStream

a java.io.OutputStream object to which data can be written

Exceptions

SQLException:: if there is an error accessing the BLOB value or if pos is less than 1

setBytes back to summary

setBytes	back to summary
public int setBytes(long pos, byte[] bytes) throws SQLException Implements java.sql.Blob.setBytes. Doc from java.sql.Blob.setBytes. 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. The array of bytes will overwrite the existing bytes in the `Blob` object starting at the position `pos`. If the end of the `Blob` value is reached while writing the array of bytes, then the length of the `Blob` value will be increased to accommodate the extra bytes. Note If the value specified for `pos` is greater than the length+1 of the `BLOB` value then the behavior is undefined. Some JDBC drivers may throw an `SQLException` while other drivers may support this operation. Parameters pos:long the position in the `BLOB` object at which to start writing; the first position is 1 bytes:byte[] the array of bytes to be written to the `BLOB` value that this `Blob` object represents Returns:int the number of bytes written Exceptions SQLException: if there is an error accessing the `BLOB` value or if pos is less than 1

public int setBytes(long pos, byte[] bytes) throws SQLException

Implements java.sql.Blob.setBytes.

Doc from java.sql.Blob.setBytes.

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. The array of bytes will overwrite the existing bytes in the Blob object starting at the position pos. If the end of the Blob value is reached while writing the array of bytes, then the length of the Blob value will be increased to accommodate the extra bytes.

Note

Parameters

pos:long: the position in the BLOB object at which to start writing; the first position is 1
bytes:byte[]: the array of bytes to be written to the BLOB value that this Blob object represents

Returns:int

the number of bytes written

Exceptions

SQLException:: if there is an error accessing the BLOB value or if pos is less than 1

setBytes back to summary

setBytes	back to summary
public int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException Implements java.sql.Blob.setBytes. Doc from java.sql.Blob.setBytes. Writes all or part of the given `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. The array of bytes will overwrite the existing bytes in the `Blob` object starting at the position `pos`. If the end of the `Blob` value is reached while writing the array of bytes, then the length of the `Blob` value will be increased to accommodate the extra bytes. Note If the value specified for `pos` is greater than the length+1 of the `BLOB` value then the behavior is undefined. Some JDBC drivers may throw an `SQLException` while other drivers may support this operation. Parameters pos:long the position in the `BLOB` object at which to start writing; the first position is 1 bytes:byte[] the array of bytes to be written to this `BLOB` object offset:int the offset into the array `bytes` at which to start reading the bytes to be set len:int the number of bytes to be written to the `BLOB` value from the array of bytes `bytes` Returns:int the number of bytes written Exceptions SQLException: if there is an error accessing the `BLOB` value or if pos is less than 1

public int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException

Implements java.sql.Blob.setBytes.

Doc from java.sql.Blob.setBytes.

Writes all or part of the given 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. The array of bytes will overwrite the existing bytes in the Blob object starting at the position pos. If the end of the Blob value is reached while writing the array of bytes, then the length of the Blob value will be increased to accommodate the extra bytes.

Note

Parameters

pos:long: the position in the BLOB object at which to start writing; the first position is 1
bytes:byte[]: the array of bytes to be written to this BLOB object
offset:int: the offset into the array bytes at which to start reading the bytes to be set
len:int: the number of bytes to be written to the BLOB value from the array of bytes bytes

Returns:int

the number of bytes written

Exceptions

SQLException:: if there is an error accessing the BLOB value or if pos is less than 1

setBytesX	back to summary
pack-priv int setBytesX(long pos, byte[] bytes, int offset, int len) throws SqlException

truncate back to summary

truncate	back to summary
public void truncate(long len) throws SQLException Implements java.sql.Blob.truncate. Doc from java.sql.Blob.truncate. Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length. Note If the value specified for `pos` is greater than the length+1 of the `BLOB` value then the behavior is undefined. Some JDBC drivers may throw an `SQLException` while other drivers may support this operation. Parameters len:long the length, in bytes, to which the `BLOB` value that this `Blob` object represents should be truncated Exceptions SQLException: if there is an error accessing the `BLOB` value or if len is less than 0

public void truncate(long len) throws SQLException

Implements java.sql.Blob.truncate.

Doc from java.sql.Blob.truncate.

Truncates the BLOB value that this Blob object represents to be len bytes in length.

Note

Parameters

len:long: the length, in bytes, to which the BLOB value that this Blob object represents should be truncated

Exceptions

SQLException:: if there is an error accessing the BLOB value or if len is less than 0

public Class ClientBlob

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail