javax.sql.rowset.serial
Class SerialBlob

java.lang.Object
  javax.sql.rowset.serial.SerialBlob

All Implemented Interfaces:

Blob, Cloneable, Serializable

public class SerialBlob

extends Object

implements Blob, Serializable, Cloneable

A serializable 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.

See Also:

Serialized Form

Constructor Summary
SerialBlob(Blob blob)           Constructs a SerialBlob object that is a serializable version of the given Blob object.

 

Method Summary
InputStream	getBinaryStream()           Returns this SerialBlob object as an input stream.
byte[]	getBytes(long pos, int length)           Copies the specified number of bytes, starting at the given position, from this SerialBlob object to another array of bytes.
long	length()           Retrieves the number of bytes in this SerialBlob object's array of bytes.
long	position(Blob pattern, long start)           Returns the position in this SerialBlob object where the given Blob object begins, starting the search at the specified position.
long	position(byte[] pattern, long start)           Returns the position in this SerialBlob object where the given pattern of bytes begins, starting the search at the specified position.
OutputStream	setBinaryStream(long pos)           Retrieves a stream that can be used to write to the BLOB value that this Blob object represents.
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 length)           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.
void	truncate(long length)           Truncates the BLOB value that this Blob object represents to be len bytes in length.

 

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Constructor Detail

SerialBlob

public SerialBlob(Blob blob)
           throws SerialException,
                  SQLException

Constructs a SerialBlob object that is a serializable 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

Throws:

SerialException - if an error occurs

SQLException

See Also:

Blob

getBytes

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

Copies the specified number of bytes, starting at the given position, from this SerialBlob object to another array of bytes.

Note that if the given number of bytes to be copied is larger than the length of this SerialBlob object's array of bytes, the given number will be shortened to the array's length.

Specified by:

getBytes in interface Blob

Parameters:

pos - the ordinal position of the first byte in this SerialBlob object to be copied; numbering starts at 0; must not be less than 0 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

See Also:

Blob.setBytes(long, byte[])

length

public long length()
            throws SerialException

Retrieves the number of bytes in this SerialBlob object's array of bytes.

Specified by:

length in interface Blob

Returns:

a long indicating the length in bytes of this SerialBlob object's array of bytes

Throws:

SerialException - if an error occurs

getBinaryStream

public InputStream getBinaryStream()
                            throws SerialException

Returns this SerialBlob object as an input stream.

Specified by:

getBinaryStream in interface Blob

Returns:

a java.io.InputStream object that contains this SerialBlob object's array of bytes

Throws:

SerialException - if an error occurs

See Also:

Blob.setBinaryStream(long)

position

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

Returns the position in this SerialBlob object where the given pattern of bytes begins, starting the search at the specified position.

Specified by:

position in interface Blob

Parameters:

pattern - the pattern of bytes for which to search;

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 to serialise the blob.

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

position

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

Returns the position in this SerialBlob object where the given Blob object begins, starting the search at the specified position.

Specified by:

position in interface Blob

Parameters:

pattern - the Blob object for which to search;

start - the position of the byte in this SerialBlob object from which to begin the search; the first position is 0; must not be less than 0 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

SQLException - if there is an error accessing the BLOB value

setBytes

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

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

Throws:

SQLException - if there is an error accessing the BLOB value

SerialException

See Also:

getBytes(long, int)

setBytes

public int setBytes(long pos,
                    byte[] bytes,
                    int offset,
                    int length)
             throws SerialException

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.

Specified by:

setBytes in interface Blob

Parameters:

pos - the position in the BLOB object at which to start writing

bytes - the array of bytes to be written to this BLOB object

offset - the offset into the array bytes at which to start reading the bytes to be set

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:

SQLException - if there is an error accessing the BLOB value

SerialException

See Also:

getBytes(long, int)

setBinaryStream

public OutputStream setBinaryStream(long pos)
                             throws SerialException

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 Blob

Parameters:

pos - the position in the BLOB value at which to start writing

Returns:

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

Throws:

SQLException - if there is an error accessing the BLOB value

SerialException

See Also:

getBinaryStream()

truncate

public void truncate(long length)
              throws SerialException

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

Specified by:

truncate in interface Blob

Parameters:

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

Throws:

SQLException - if there is an error accessing the BLOB value

SerialException