Class jdbcBlob
- All Implemented Interfaces:
Blob
Provides methods for getting the length of an SQL BLOB (Binary Large Object) value, for materializing a BLOB value on the client, and for determining the position of an octet sequence (byte pattern) within a BLOB value.
HSQLDB-Specific Information:
Including 1.8.x, the HSQLDB driver does not implement Blob using an SQL locator(BLOB). That is, an HSQLDB Blob object does not contain a logical pointer to SQL BLOB data; rather it directly contains a representation of the data (a byte array). As a result, an HSQLDB Blob object is itself valid beyond the duration of the transaction in which is was created, although it does not necessarily represent a corresponding value on the database.
Currently, the interface methods for updating a BLOB value are unsupported. However, the truncate method is supported for local use.
- Since:
- JDK 1.2, HSQLDB 1.7.2
- Author:
- james house jhouse@part.net, boucherb@users
-
Constructor Summary
ConstructorsConstructorDescriptionjdbcBlob
(byte[] data) Constructs a new jdbcBlob instance wrapping the given octet sequence. -
Method Summary
Modifier and TypeMethodDescriptionvoid
free()
Retrieves theBLOB
value designated by thisBlob
instance as a stream.getBinaryStream
(long pos, long length) byte[]
getBytes
(long pos, int length) Retrieves all or part of theBLOB
value that thisBlob
object represents, as an array of bytes.long
length()
Returns the number of bytes in theBLOB
value designated by thisBlob
object.long
position
(byte[] pattern, long start) Retrieves the byte position at which the specified byte arraypattern
begins within theBLOB
value that thisBlob
object represents.long
Retrieves the byte position in theBLOB
value designated by thisBlob
object at whichpattern
begins.setBinaryStream
(long pos) Retrieves a stream that can be used to write to theBLOB
value that thisBlob
object represents.int
setBytes
(long pos, byte[] bytes) Writes the given array of bytes to theBLOB
value that thisBlob
object represents, starting at positionpos
, and returns the number of bytes written.int
setBytes
(long pos, byte[] bytes, int offset, int len) Writes all or part of the givenbyte
array to theBLOB
value that thisBlob
object represents and returns the number of bytes written.void
truncate
(long len) Truncates theBLOB
value that thisBlob
object represents to belen
bytes in length.
-
Constructor Details
-
jdbcBlob
Constructs a new jdbcBlob instance wrapping the given octet sequence.This constructor is used internally to retrieve result set values as Blob objects, yet it must be public to allow access from other packages. As such (in the interest of efficiency) this object maintains a reference to the given octet sequence rather than making a copy; special care should be taken by extenal clients never to use this constructor with a byte array object that may later be modified extenally.
- Parameters:
data
- the octet sequence representing the Blob value- Throws:
SQLException
- if the argument is null
-
-
Method Details
-
length
Returns the number of bytes in theBLOB
value designated by thisBlob
object.- Specified by:
length
in interfaceBlob
- Returns:
- length of the
BLOB
in bytes - Throws:
SQLException
- if there is an error accessing the length of theBLOB
- Since:
- JDK 1.2, HSQLDB 1.7.2
-
getBytes
Retrieves all or part of theBLOB
value that thisBlob
object represents, as an array of bytes. Thisbyte
array contains up tolength
consecutive bytes starting at positionpos
.HSQLDB-Specific Information:
The official specification above is ambiguous in that it does not precisely indicate the policy to be observed when pos > this.length() - length. One policy would be to retrieve the octets from pos to this.length(). Another would be to throw an exception. HSQLDB observes the later policy.
- Specified by:
getBytes
in interfaceBlob
- Parameters:
pos
- the ordinal position of the first byte in theBLOB
value to be extracted; the first byte is at position 1length
- the number of consecutive bytes to be copied- Returns:
- a byte array containing up to
length
consecutive bytes from theBLOB
value designated by thisBlob
object, starting with the byte at positionpos
- Throws:
SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
-
getBinaryStream
Retrieves theBLOB
value designated by thisBlob
instance as a stream.- Specified by:
getBinaryStream
in interfaceBlob
- Returns:
- a stream containing the
BLOB
data - Throws:
SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
-
position
Retrieves the byte position at which the specified byte arraypattern
begins within theBLOB
value that thisBlob
object represents. The search forpattern
begins at positionstart
.- Specified by:
position
in interfaceBlob
- Parameters:
pattern
- the byte array for which to searchstart
- the position at which to begin searching; the first position is 1- Returns:
- the position at which the pattern appears, else -1
- Throws:
SQLException
- if there is an error accessing theBLOB
- Since:
- JDK 1.2, HSQLDB 1.7.2
-
position
Retrieves the byte position in theBLOB
value designated by thisBlob
object at whichpattern
begins. The search begins at positionstart
.- Specified by:
position
in interfaceBlob
- Parameters:
pattern
- theBlob
object designating theBLOB
value for which to searchstart
- the position in theBLOB
value at which to begin searching; the first position is 1- Returns:
- the position at which the pattern begins, else -1
- Throws:
SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
-
setBytes
Writes the given array of bytes to theBLOB
value that thisBlob
object represents, starting at positionpos
, and returns the number of bytes written.HSQLDB-Specific Information:
HSLQDB 1.7.2 does not support this feature.
Calling this method always throws an
SQLException
.- Specified by:
setBytes
in interfaceBlob
- Parameters:
pos
- the position in theBLOB
object at which to start writingbytes
- the array of bytes to be written to theBLOB
value that thisBlob
object represents- Returns:
- the number of bytes written
- Throws:
SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
-
setBytes
Writes all or part of the givenbyte
array to theBLOB
value that thisBlob
object represents and returns the number of bytes written. Writing starts at positionpos
in theBLOB
value;len
bytes from the given byte array are written.HSQLDB-Specific Information:
HSLQDB 1.7.2 does not support this feature.
Calling this method always throws an
SQLException
.- Specified by:
setBytes
in interfaceBlob
- Parameters:
pos
- the position in theBLOB
object at which to start writingbytes
- the array of bytes to be written to thisBLOB
objectoffset
- the offset into the arraybytes
at which to start reading the bytes to be setlen
- the number of bytes to be written to theBLOB
value from the array of bytesbytes
- Returns:
- the number of bytes written
- Throws:
SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
-
setBinaryStream
Retrieves a stream that can be used to write to theBLOB
value that thisBlob
object represents. The stream begins at positionpos
.HSQLDB-Specific Information:
HSQLDB 1.7.2 does not support this feature.
Calling this method always throws an
SQLException
.- 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- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
-
truncate
Truncates theBLOB
value that thisBlob
object represents to belen
bytes in length.HSQLDB-Specific Information:
This operation affects only the client-side value; it has no effect upon the value as it is stored in the database.
- Specified by:
truncate
in interfaceBlob
- Parameters:
len
- the length, in bytes, to which theBLOB
value that thisBlob
object represents should be truncated- Throws:
SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
-
free
- Specified by:
free
in interfaceBlob
- Throws:
SQLException
-
getBinaryStream
- Specified by:
getBinaryStream
in interfaceBlob
- Throws:
SQLException
-