APIdia Launch Partner
Top Description Fields Constructors Methods
javax.sql.rowset.serial

public Class SerialBlob

extends Object
implements Blob, Serializable, Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable, java.io.Serializable, java.sql.Blob, java.lang.AutoCloseable
Imports
java.sql.*, java.io.*, java.lang.reflect.*, java.util.Arrays

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.

Author
Jonathan Bruce
Since
1.5

Field Summary

Modifier and TypeField and Description
private Blob
private byte[]
buf

A serialized array of uninterpreted bytes representing the value of this SerialBlob object.

private long
len

The number of bytes in this SerialBlob object's array of bytes.

private long
origLen

The original number of bytes in this SerialBlob object's array of bytes when it was first established.

pack-priv static final long
serialVersionUID

The identifier that assists in the serialization of this SerialBlob object.

Constructor Summary

AccessConstructor and Description
public
SerialBlob(byte[]
the byte array containing the data for the Blob object to be serialized
b
)

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

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

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

Method Summary

Modifier and TypeMethod and Description
public Object

Returns:

a clone of this SerialBlob
clone
()

Overrides java.lang.Object.clone.

Returns a clone of this SerialBlob.

public boolean

Returns:

true if the given object represents a SerialBlob equivalent to this SerialBlob, false otherwise
equals
(Object
The object to compare this SerialBlob against
obj
)

Overrides java.lang.Object.equals.

Compares this SerialBlob to the specified object.

public void
free()

Implements java.sql.Blob.free.

This method frees the SerialBlob object and releases the resources that it holds.

public InputStream

Returns:

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

Implements java.sql.Blob.getBinaryStream.

Returns this SerialBlob object as an input 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.

public byte[]

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
getBytes
(long
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
pos
,
int
the number of bytes to be copied
length
)

Implements java.sql.Blob.getBytes.

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

public int

Returns:

a hash code value for this object.
hashCode
()

Overrides java.lang.Object.hashCode.

Returns a hash code for this SerialBlob.

private void
isValid()

Check to see if this object had previously had its free method called

public long

Returns:

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

Implements java.sql.Blob.length.

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

public long

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
position
(byte[]
the pattern of bytes for which to search
pattern
,
long
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
start
)

Implements java.sql.Blob.position.

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

public long

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
position
(Blob
the Blob object for which to search;
pattern
,
long
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
start
)

Implements java.sql.Blob.position.

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

private void
readObject(ObjectInputStream
the ObjectInputStream to read from.
s
)

readObject is called to restore the state of the SerialBlob from a stream.

public OutputStream

Returns:

a java.io.OutputStream object to which data can be written
setBinaryStream
(long
the position in the BLOB value at which to start writing
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

Returns:

the number of bytes written
setBytes
(long
the position in the SQL BLOB value at which to start writing. The first position is 1; must not be less than 1 nor greater than the length+1 of this SerialBlob object.
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

Returns:

the number of bytes written
setBytes
(long
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+1 of this SerialBlob object.
pos
,
byte[]
the array of bytes to be written to the BLOB value
bytes
,
int
the offset into the array bytes at which to start reading the bytes to be set. The first offset position is 0; must not be less than 0 nor greater than the length of the array bytes
offset
,
int
the number of bytes to be written to the BLOB value from the array of bytes bytes
length
)

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.

public void
truncate(long
the length, in bytes, to which the BLOB value that this Blob object represents should be truncated
length
)

Implements java.sql.Blob.truncate.

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

private void
writeObject(ObjectOutputStream
the ObjectOutputStream to write to.
s
)

writeObject is called to save the state of the SerialBlob to a stream.

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

blobback to summary
private Blob blob
Annotations
@SuppressWarnings:serial
bufback to summary
private byte[] buf

A serialized array of uninterpreted bytes representing the value of this SerialBlob object.

lenback to summary
private long len

The number of bytes in this SerialBlob object's array of bytes.

origLenback to summary
private long origLen

The original number of bytes in this SerialBlob object's array of bytes when it was first established.

serialVersionUIDback to summary
pack-priv static final long serialVersionUID

The identifier that assists in the serialization of this SerialBlob object.

Constructor Detail

SerialBlobback to summary
public SerialBlob(byte[] b) throws SerialException, SQLException

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

The new SerialBlob object is initialized with the data from the byte array, thus allowing disconnected RowSet objects to establish serialized Blob objects without touching the data source.

Parameters
b:byte[]

the byte array containing the data for the Blob object to be serialized

Exceptions
SerialException:
if an error occurs during serialization
SQLException:
if a SQL errors occurs
SerialBlobback to summary
public SerialBlob(Blob blob) throws SerialException, SQLException

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

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

Exceptions
SerialException:
if an error occurs during serialization
SQLException:
if the Blob passed to this to this constructor is a null.
See Also
java.sql.Blob

Method Detail

cloneback to summary
public Object clone()

Overrides java.lang.Object.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.

Returns:Object

a clone of this SerialBlob

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Compares this SerialBlob to the specified object. The result is true if and only if the argument is not null and is a SerialBlob object that represents the same sequence of bytes as this object.

Parameters
obj:Object

The object to compare this SerialBlob against

Returns:boolean

true if the given object represents a SerialBlob equivalent to this SerialBlob, false otherwise

freeback to summary
public void free() throws SQLException

Implements java.sql.Blob.free.

This method frees the SerialBlob 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
Since
1.6
getBinaryStreamback to summary
public InputStream getBinaryStream() throws SerialException

Implements java.sql.Blob.getBinaryStream.

Returns this SerialBlob object as an input stream. Unlike the related method, setBinaryStream, a stream is produced regardless of whether the SerialBlob was created with a Blob object or a byte array.

Returns:InputStream

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

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
See Also
setBinaryStream
getBinaryStreamback 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 the number of bytes in the Blob
SerialException:
if the free method had been previously called on this object
Since
1.6
getBytesback to summary
public byte[] getBytes(long pos, int length) throws SerialException

Implements java.sql.Blob.getBytes.

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.

Parameters
pos:long

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

the number of bytes to be copied

Returns:byte[]

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

Exceptions
SerialException:
if the given starting position is out of bounds; if free had previously been called on this object
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code for this SerialBlob.

Returns:int

a hash code value for this object.

isValidback to summary
private void isValid() throws SerialException

Check to see if this object had previously had its free method called

lengthback to summary
public long length() throws SerialException

Implements java.sql.Blob.length.

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

Returns:long

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

Exceptions
SerialException:
if an error occurs; if free had previously been called on this object
positionback to summary
public long position(byte[] pattern, long start) throws SerialException, SQLException

Implements java.sql.Blob.position.

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

Parameters
pattern:byte[]

the pattern of bytes for which to search

start:long

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

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

Exceptions
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
positionback to summary
public long position(Blob pattern, long start) throws SerialException, SQLException

Implements java.sql.Blob.position.

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

Parameters
pattern:Blob

the Blob object for which to search;

start:long

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

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

Exceptions
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
readObjectback to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

readObject is called to restore the state of the SerialBlob from a stream.

Parameters
s:ObjectInputStream

the ObjectInputStream to read from.

Exceptions
IOException:
if an I/O error occurs.
ClassNotFoundException:
if the class of a serialized object could not be found.
setBinaryStreamback to summary
public OutputStream setBinaryStream(long pos) throws SerialException, SQLException

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

Parameters
pos:long

the position in the BLOB value at which to start writing

Returns:OutputStream

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

Exceptions
SerialException:
if the SerialBlob in not instantiated with a Blob object that supports setBinaryStream(); if free had previously been called on this object
SQLException:
if there is an error accessing the BLOB value
See Also
getBinaryStream
setBytesback to summary
public int setBytes(long pos, byte[] bytes) throws SerialException, SQLException

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.

Parameters
pos:long

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

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
SerialException:
if there is an error accessing the BLOB value; or if an invalid position is set; if free had previously been called on this object
SQLException:
if there is an error accessing the BLOB value from the database
See Also
getBytes
setBytesback to summary
public int setBytes(long pos, byte[] bytes, int offset, int length) throws SerialException, SQLException

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. Writing starts at position pos in the BLOB value; length bytes from the given byte array are written.

Parameters
pos:long

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+1 of this SerialBlob object.

bytes:byte[]

the array of bytes to be written to the BLOB value

offset:int

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

length: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
SerialException:
if there is an error accessing the BLOB value; if an invalid position is set; if an invalid offset value is set; or the combined values of the length and offset is greater than the length of bytes; if free had previously been called on this object
SQLException:
if there is an error accessing the BLOB value from the database.
See Also
getBytes
truncateback to summary
public void truncate(long length) throws SerialException

Implements java.sql.Blob.truncate.

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

Parameters
length:long

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

Exceptions
SerialException:
if there is an error accessing the Blob value; or the length to truncate is greater that the SerialBlob length; if free had previously been called on this object
writeObjectback to summary
private void writeObject(ObjectOutputStream s) throws IOException

writeObject is called to save the state of the SerialBlob to a stream.

Parameters
s:ObjectOutputStream

the ObjectOutputStream to write to.

Exceptions
IOException:
if an I/O error occurs.