Class SerialBlob

A serialized mapping in the Java programming language of an SQL
BLOB value.

The SerialBlob class provides a constructor for creating
an instance from a Blob object. Note that the
Blob
object should have brought the SQL BLOB value's data over
to the client before a SerialBlob object
is constructed from it. The data of an SQL BLOB value can
be materialized on the client as an array of bytes (using the method
Blob.getBytes) or as a stream of uninterpreted bytes
(using the method Blob.getBinaryStream).

SerialBlob methods make it possible to make a copy of a
SerialBlob object as an array of bytes or as a stream.
They also make it possible to locate a given pattern of bytes or a
Blob object within a SerialBlob object
and to update or truncate a Blob object.

Thread safety

A SerialBlob is not safe for use by multiple concurrent threads. If a
SerialBlob is to be used by more than one thread then access to the SerialBlob
should be controlled by appropriate synchronization.

SerialBlob

Constructs a SerialBlob object that is a serialized
version of the given Blob object.

The new SerialBlob object is initialized with the
data from the Blob object; therefore, the
Blob object should have previously brought the
SQL BLOB value's data over to the client from
the database. Otherwise, the new SerialBlob object
will contain no data.

Parameters:

blob - the Blob object from which this
SerialBlob object is to be constructed;
cannot be null.

pos - the ordinal position of the first byte in this
SerialBlob object to be copied;
numbering starts at 1; must not be less
than 1 and must be less than or equal
to the length of this SerialBlob object

length - the number of bytes to be copied

Returns:

an array of bytes that is a copy of a region of this
SerialBlob object, starting at the given
position and containing the given number of consecutive bytes

Throws:

SerialException - if the given starting position is out of bounds;
if free had previously been called on this object

start - the position of the byte in this
SerialBlob object from which to begin
the search; the first position is 1;
must not be less than 1 nor greater than
the length of this SerialBlob object

Returns:

the position in this SerialBlob object
where the given pattern begins, starting at the specified
position; -1 if the pattern is not found
or the given starting position is out of bounds; position
numbering for the return value starts at 1

Throws:

SerialException - if an error occurs when serializing the blob;
if free had previously been called on this object

SQLException - if there is an error accessing the BLOB
value from the database

start - the position of the byte in this
SerialBlob object from which to begin
the search; the first position is 1;
must not be less than 1 nor greater than
the length of this SerialBlob object

Returns:

the position in this SerialBlob object
where the given Blob object begins, starting
at the specified position; -1 if the pattern is
not found or the given starting position is out of bounds;
position numbering for the return value starts at 1

Throws:

SerialException - if an error occurs when serializing the blob;
if free had previously been called on this object

SQLException - if there is an error accessing the BLOB
value from the database

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.

pos - the position in the BLOB object at which
to start writing. The first position is 1;
must not be less than 1 nor greater than
the length of this SerialBlob object.

bytes - the array of bytes to be written to the BLOB
value

offset - the offset in the byte array at which
to start reading the bytes. The first offset position is
0; must not be less than 0 nor greater
than the length of the byte array

length - the number of bytes to be written to the
BLOB value from the array of bytes bytes.

Returns:

the number of bytes written

Throws:

SerialException - if there is an error accessing the
BLOB value; if an invalid position is set; if an
invalid offset value is set; if number of bytes to be written
is greater than the SerialBlob length; or the combined
values of the length and offset is greater than the Blob buffer;
if free had previously been called on this object

SQLException - if there is an error accessing the BLOB
value from the database.

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. This method forwards the
setBinaryStream() call to the underlying Blob in
the event that this SerialBlob object is instantiated with a
Blob. If this SerialBlob is instantiated with
a byte array, a SerialException is thrown.

clone

Returns a clone of this SerialBlob. The copy will contain a
reference to a clone of the internal byte array, not a reference
to the original internal byte array of this SerialBlob object.
The underlying Blob object will be set to null.