Class SerialBlob
- java.lang.Object
-
- javax.sql.rowset.serial.SerialBlob
- All Implemented Interfaces:
-
Serializable
,Cloneable
,Blob
public class SerialBlob extends Object implements Blob, Serializable, Cloneable
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.
- Since:
- 1.5
- See Also:
- Serialized Form
Constructor Summary
Constructor | Description |
---|---|
SerialBlob(byte[] b) | Constructs a |
SerialBlob(Blob blob) | Constructs a |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
Object | clone() | Returns a clone of this |
boolean | equals(Object obj) | Compares this SerialBlob to the specified object. |
void | free() | This method frees the |
InputStream | getBinaryStream() | Returns this |
InputStream | getBinaryStream(long pos,
long length) | Returns an |
byte[] | getBytes(long pos,
int length) | Copies the specified number of bytes, starting at the given position, from this |
int | hashCode() | Returns a hash code for this |
long | length() | Retrieves the number of bytes in this |
long | position(byte[] pattern,
long start) | Returns the position in this |
long | position(Blob pattern,
long start) | Returns the position in this |
OutputStream | setBinaryStream(long pos) | Retrieves a stream that can be used to write to the |
int | setBytes(long pos,
byte[] bytes) | Writes the given array of bytes to the |
int | setBytes(long pos,
byte[] bytes,
int offset,
int length) | Writes all or part of the given |
void | truncate(long length) | Truncates the |
Methods declared in class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
Constructor Detail
SerialBlob
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
- thebyte
array containing the data for theBlob
object to be serialized - Throws:
-
SerialException
- if an error occurs during serialization -
SQLException
- if a SQL errors occurs
SerialBlob
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
- theBlob
object from which thisSerialBlob
object is to be constructed; cannot be null. - Throws:
-
SerialException
- if an error occurs during serialization -
SQLException
- if theBlob
passed to this to this constructor is anull
. - See Also:
Blob
Method Detail
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 interfaceBlob
- Parameters:
-
pos
- the ordinal position of the first byte in thisSerialBlob
object to be copied; numbering starts at1
; must not be less than1
and must be less than or equal to the length of thisSerialBlob
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; iffree
had previously been called on this object - 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 interfaceBlob
- Returns:
- a
long
indicating the length in bytes of thisSerialBlob
object's array of bytes - Throws:
-
SerialException
- if an error occurs; iffree
had previously been called on this object
getBinaryStream
public InputStream getBinaryStream() throws SerialException
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.
- Specified by:
-
getBinaryStream
in interfaceBlob
- Returns:
- a
java.io.InputStream
object that contains thisSerialBlob
object's array of bytes - Throws:
-
SerialException
- if an error occurs; iffree
had previously been called on this object - See Also:
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 interfaceBlob
- Parameters:
-
pattern
- the pattern of bytes for which to search -
start
- the position of the byte in thisSerialBlob
object from which to begin the search; the first position is1
; must not be less than1
nor greater than the length of thisSerialBlob
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 at1
- Throws:
-
SerialException
- if an error occurs when serializing the blob; iffree
had previously been called on this object -
SQLException
- if there is an error accessing theBLOB
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 interfaceBlob
- Parameters:
-
pattern
- theBlob
object for which to search; -
start
- the position of the byte in thisSerialBlob
object from which to begin the search; the first position is1
; must not be less than1
nor greater than the length of thisSerialBlob
object - Returns:
- the position in this
SerialBlob
object where the givenBlob
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 at1
- Throws:
-
SerialException
- if an error occurs when serializing the blob; iffree
had previously been called on this object -
SQLException
- if there is an error accessing theBLOB
value from the database
setBytes
public int setBytes(long pos, byte[] bytes) throws SerialException, 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 interfaceBlob
- Parameters:
-
pos
- the position in the SQLBLOB
value at which to start writing. The first position is1
; must not be less than1
nor greater than the length of thisSerialBlob
object. -
bytes
- the array of bytes to be written to theBLOB
value that thisBlob
object represents - Returns:
- the number of bytes written
- Throws:
-
SerialException
- if there is an error accessing theBLOB
value; or if an invalid position is set; if an invalid offset value is set; iffree
had previously been called on this object -
SQLException
- if there is an error accessing theBLOB
value from the database - See Also:
getBytes(long, int)
setBytes
public int setBytes(long pos, byte[] bytes, int offset, int length) throws SerialException, SQLException
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 interfaceBlob
- Parameters:
-
pos
- the position in theBLOB
object at which to start writing. The first position is1
; must not be less than1
nor greater than the length of thisSerialBlob
object. -
bytes
- the array of bytes to be written to theBLOB
value -
offset
- the offset in thebyte
array at which to start reading the bytes. The first offset position is0
; must not be less than0
nor greater than the length of thebyte
array -
length
- the number of bytes to be written to theBLOB
value from the array of bytes bytes. - Returns:
- the number of bytes written
- Throws:
-
SerialException
- if there is an error accessing theBLOB
value; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than theSerialBlob
length; or the combined values of the length and offset is greater than the Blob buffer; iffree
had previously been called on this object -
SQLException
- if there is an error accessing theBLOB
value from the database. - See Also:
getBytes(long, int)
setBinaryStream
public OutputStream setBinaryStream(long pos) throws SerialException, SQLException
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.
- Specified by:
-
setBinaryStream
in interfaceBlob
- Parameters:
-
pos
- the position in theBLOB
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 theBLOB
value -
SerialException
- if the SerialBlob in not instantiated with aBlob
object that supportssetBinaryStream()
; iffree
had previously been called on this object - 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 interfaceBlob
- Parameters:
-
length
- the length, in bytes, to which theBLOB
value that thisBlob
object represents should be truncated - Throws:
-
SerialException
- if there is an error accessing the Blob value; or the length to truncate is greater that the SerialBlob length; iffree
had previously been called on this object
getBinaryStream
public InputStream getBinaryStream(long pos, long length) throws 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 interfaceBlob
- Parameters:
-
pos
- the offset to the first byte of the partial value to be retrieved. The first byte in theBlob
is at position 1 -
length
- the length in bytes of the partial value to be retrieved - Returns:
-
InputStream
through which the partialBlob
value can be read. - Throws:
-
SQLException
- if pos is less than 1 or if pos is greater than the number of bytes in theBlob
or if pos + length is greater than the number of bytes in theBlob
-
SerialException
- if thefree
method had been previously called on this object - Since:
- 1.6
free
public void free() throws SQLException
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.
- Specified by:
-
free
in interfaceBlob
- Throws:
-
SQLException
- if an error occurs releasing the Blob's resources - Since:
- 1.6
equals
public boolean equals(Object obj)
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.
- Overrides:
-
equals
in classObject
- Parameters:
-
obj
- The object to compare thisSerialBlob
against - Returns:
-
true
if the given object represents aSerialBlob
equivalent to this SerialBlob,false
otherwise - See Also:
-
Object.hashCode()
,HashMap
hashCode
public int hashCode()
Returns a hash code for this SerialBlob
.
- Overrides:
-
hashCode
in classObject
- Returns:
- a hash code value for this object.
- See Also:
-
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
clone
public 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.