Class jdbcBlob
- java.lang.Object
-
- org.hsqldb.jdbc.jdbcBlob
-
- All Implemented Interfaces:
java.sql.Blob
public class jdbcBlob extends java.lang.Object implements java.sql.Blob
The representation (mapping) in the JavaTM programming language of an SQL BLOB value.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
Constructors Constructor Description jdbcBlob(byte[] data)
Constructs a new jdbcBlob instance wrapping the given octet sequence.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
free()
java.io.InputStream
getBinaryStream()
Retrieves theBLOB
value designated by thisBlob
instance as a stream.java.io.InputStream
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
position(java.sql.Blob pattern, long start)
Retrieves the byte position in theBLOB
value designated by thisBlob
object at whichpattern
begins.java.io.OutputStream
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 Detail
-
jdbcBlob
public jdbcBlob(byte[] data) throws java.sql.SQLException
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:
java.sql.SQLException
- if the argument is null
-
-
Method Detail
-
length
public long length() throws java.sql.SQLException
Returns the number of bytes in theBLOB
value designated by thisBlob
object.- Specified by:
length
in interfacejava.sql.Blob
- Returns:
- length of the
BLOB
in bytes - Throws:
java.sql.SQLException
- if there is an error accessing the length of theBLOB
- Since:
- JDK 1.2, HSQLDB 1.7.2
-
getBytes
public byte[] getBytes(long pos, int length) throws java.sql.SQLException
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 interfacejava.sql.Blob
- 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:
java.sql.SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
setBytes(long, byte[])
-
getBinaryStream
public java.io.InputStream getBinaryStream() throws java.sql.SQLException
Retrieves theBLOB
value designated by thisBlob
instance as a stream.- Specified by:
getBinaryStream
in interfacejava.sql.Blob
- Returns:
- a stream containing the
BLOB
data - Throws:
java.sql.SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
setBinaryStream(long)
-
position
public long position(byte[] pattern, long start) throws java.sql.SQLException
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 interfacejava.sql.Blob
- 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:
java.sql.SQLException
- if there is an error accessing theBLOB
- Since:
- JDK 1.2, HSQLDB 1.7.2
-
position
public long position(java.sql.Blob pattern, long start) throws java.sql.SQLException
Retrieves the byte position in theBLOB
value designated by thisBlob
object at whichpattern
begins. The search begins at positionstart
.- Specified by:
position
in interfacejava.sql.Blob
- 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:
java.sql.SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
-
setBytes
public int setBytes(long pos, byte[] bytes) throws java.sql.SQLException
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 interfacejava.sql.Blob
- 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:
java.sql.SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
getBytes(long, int)
-
setBytes
public int setBytes(long pos, byte[] bytes, int offset, int len) throws java.sql.SQLException
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 interfacejava.sql.Blob
- 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:
java.sql.SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
getBytes(long, int)
-
setBinaryStream
public java.io.OutputStream setBinaryStream(long pos) throws java.sql.SQLException
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 interfacejava.sql.Blob
- 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:
java.sql.SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
getBinaryStream()
-
truncate
public void truncate(long len) throws java.sql.SQLException
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 interfacejava.sql.Blob
- Parameters:
len
- the length, in bytes, to which theBLOB
value that thisBlob
object represents should be truncated- Throws:
java.sql.SQLException
- if there is an error accessing theBLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
-
free
public void free() throws java.sql.SQLException
- Specified by:
free
in interfacejava.sql.Blob
- Throws:
java.sql.SQLException
-
getBinaryStream
public java.io.InputStream getBinaryStream(long pos, long length) throws java.sql.SQLException
- Specified by:
getBinaryStream
in interfacejava.sql.Blob
- Throws:
java.sql.SQLException
-
-