BLOB value. An SQL BLOB is a built-in type
that stores a Binary Large Object as a column value in a row of
a database table. By default drivers implement Blob using
an SQL locator(BLOB), which means that a
Blob object contains a logical pointer to the
SQL BLOB data rather than the data itself.
A Blob object is valid for the duration of the
transaction in which it was created.
Methods in the interfaces java.,
java., and java., such as
getBlob and setBlob allow a programmer to
access an SQL BLOB value.
The Blob interface 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 a pattern of bytes within a
BLOB value. In addition, this interface has methods for updating
a BLOB value.
All methods on the Blob interface must be fully implemented if the
JDBC driver supports the data type.
HSQLDB-Specific Information:
Previous to 2.0, the HSQLDB driver did not implement Blob using an SQL locator(BLOB). That is, an HSQLDB Blob object did not contain a logical pointer to SQL BLOB data; rather it directly contained a representation of the data (a byte array). As a result, an HSQLDB Blob object was itself valid beyond the duration of the transaction in which is was created, although it did not necessarily represent a corresponding value on the database. Also, the interface methods for updating a BLOB value were unsupported, with the exception of the truncate method, in that it could be used to truncate the local value.
Starting with 2.0, the HSQLDB driver fully supports both local and remote
SQL BLOB data implementations, meaning that an HSQLDB Blob object may
contain a logical pointer to remote SQL BLOB data (see JDBCBlobClient) or it may directly contain a local representation of the
data (as implemented in this class). In particular, when the product is built
under JDK 1.6+ and the Blob instance is constructed as a result of calling
JDBCConnection.createBlob(), then the resulting Blob instance is initially
disconnected (is not bound to the transaction scope of the vending Connection
object), the data is contained directly and all interface methods for
updating the BLOB value are supported for local use until the first
invocation of free(); otherwise, an HSQLDB Blob's implementation is
determined at runtime by the driver, it is typically not valid beyond the
duration of the transaction in which is was created, and there no
standard way to query whether it represents a local or remote
value.
| Modifier and Type | Field and Description |
|---|---|
| private boolean | |
| private final boolean | |
| private byte[] | |
| private static final long | |
| private static final long | |
| private static final byte[] |
| Access | Constructor and Description |
|---|---|
| public | JDBCBlob(final byte[]
the octet sequence representing the Blob value data)Constructs a new JDBCBlob instance wrapping the given octet sequence. |
| protected |
| Modifier and Type | Method and Description |
|---|---|
| protected synchronized void | |
| protected void | |
| protected byte[] | |
| public synchronized void | free()
Implements java. This method frees the |
| public InputStream | Returns: a stream containing theBLOB dataImplements java. Retrieves the |
| public InputStream | Returns: InputStream through which
the partial Blob value can be read.the offset to the first byte of the partial value to be
retrieved. The first byte in the pos, long Blob is at position 1.the length in bytes of the partial value to be retrieved length)Implements java. Returns an |
| public byte[] | Returns: a byte array containing up tolength
consecutive bytes from the BLOB value designated
by this Blob object, starting with the
byte at position posthe ordinal position of the first byte in the
pos, final int BLOB value to be extracted; the first byte is at
position 1the number of consecutive bytes to be copied; the value
for length must be 0 or greater length)Implements java. Retrieves all or part of the |
| private synchronized byte[] | |
| public long | Returns: length of theBLOB in bytesImplements java. Returns the number of bytes in the |
| public long | Returns: the position at which the pattern appears, else -1the byte array for which to search pattern, final long the position at which to begin searching; the
first position is 1 start)Implements java. Retrieves the byte position at which the specified byte array
|
| public long | Returns: the position at which the pattern begins, else -1the pattern, long Blob object designating
the BLOB value for which to searchthe position in the start)BLOB value
at which to begin searching; the first position is 1Implements java. Retrieves the byte position in the |
| public OutputStream | Returns: ajava.io.OutputStream object to which data can
be writtenthe position in the pos)BLOB value at which
to start writing; the first position is 1Implements java. Retrieves a stream that can be used to write to the |
| public int | Returns: the number of bytes writtenthe position in the pos, byte[] BLOB object at which
to start writing; the first position is 1the array of bytes to be written to the bytes)BLOB
value that this Blob object representsImplements java. Writes the given array of bytes to the |
| public int | Returns: the number of bytes writtenthe position in the pos, byte[] BLOB object at which
to start writing; the first position is 1the array of bytes to be written to this bytes, int BLOB
objectthe offset into the array offset, int bytes at which
to start reading the bytes to be setthe number of bytes to be written to the len)BLOB
value from the array of bytes bytesImplements java. Writes all or part of the given |
| private synchronized void | |
| public void | truncate(final long
the length, in bytes, to which the len)BLOB value
that this Blob object represents should be truncatedImplements java. Truncates the |
| m_closed | back to summary |
|---|---|
| private boolean m_closed | |
| m_createdByConnection | back to summary |
|---|---|
| private final boolean m_createdByConnection | |
| m_data | back to summary |
|---|---|
| private byte[] m_data | |
| MAX_POS | back to summary |
|---|---|
| private static final long MAX_POS | |
| MIN_POS | back to summary |
|---|---|
| private static final long MIN_POS | |
| NO_BYTES | back to summary |
|---|---|
| private static final byte[] NO_BYTES | |
| JDBCBlob | back to summary |
|---|---|
| public JDBCBlob(final byte[] data) throws 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 external clients never to use this constructor with a byte array object that may later be modified externally.
| |
| JDBCBlob | back to summary |
|---|---|
| protected JDBCBlob() | |
| checkClosed | back to summary |
|---|---|
| protected synchronized void checkClosed() throws SQLException | |
| checkReadonly | back to summary |
|---|---|
| protected void checkReadonly() throws SQLException | |
| data | back to summary |
|---|---|
| protected byte[] data() throws SQLException | |
| free | back to summary |
|---|---|
| public synchronized void free() throws SQLException Implements java. This method frees the
After
| |
| getBinaryStream | back to summary |
|---|---|
| public InputStream getBinaryStream() throws SQLException Implements java. Retrieves the
| |
| getBinaryStream | back to summary |
|---|---|
| public InputStream getBinaryStream(long pos, long length) throws SQLException Implements java. Returns an
| |
| getBytes | back to summary |
|---|---|
| public byte[] getBytes(long pos, final int length) throws SQLException Implements java. Retrieves all or part of the HSQLDB-Specific Information: The official specification above is ambiguous in that it does not precisely indicate the policy to be observed whenpos > 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 second policy.
| |
| getData | back to summary |
|---|---|
| private synchronized byte[] getData() throws SQLException | |
| length | back to summary |
|---|---|
| public long length() throws SQLException Implements java. Returns the number of bytes in the
| |
| position | back to summary |
|---|---|
| public long position(final byte[] pattern, final long start) throws SQLException Implements java. Retrieves the byte position at which the specified byte array
| |
| position | back to summary |
|---|---|
| public long position(final Blob pattern, long start) throws SQLException Implements java. Retrieves the byte position in the
| |
| setBinaryStream | back to summary |
|---|---|
| public OutputStream setBinaryStream(final long pos) throws SQLException Implements java. Retrieves a stream that can be used to write to the Note If the value specified for HSQLDB-Specific Information: Starting with HSQLDB 2.0 this feature is supported.When built under JDK 1.6+ and the Blob instance is constructed as a result of calling JDBCConnection.createBlob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createBlob() constructs disconnected, initially empty Blob instances. To propagate the Blob value to a database in this case, it is required to supply the Blob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Blob instance to an updateXXX method of an updatable ResultSet. Implementation Notes The data written to the stream does not appear in this Blob until the stream is closed
When the stream is closed, if the value specified for Starting with HSQLDB 2.1, JDBCBlob no longer utilizes volatile fields and is effectively thread safe, but still uses local variable snapshot isolation. As such, the synchronization policy still does not strictly enforce serialized read/write access to the underlying data So, if an application may perform concurrent JDBCBlob modifications and the integrity of the application depends on total order Blob modification semantics, then such operations should be synchronized on an appropriate monitor.
| |
| setBytes | back to summary |
|---|---|
| public int setBytes(long pos, byte[] bytes) throws SQLException Implements java. Writes the given array of bytes to the Note If the value specified for HSQLDB-Specific Information: Starting with HSQLDB 2.0 this feature is supported.When built under JDK 1.6+ and the Blob instance is constructed as a result of calling JDBCConnection.createBlob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createBlob() constructs disconnected, initially empty Blob instances. To propagate the Blob value to a database in this case, it is required to supply the Blob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Blob instance to an updateXXX method of an updatable ResultSet. Implementation Notes Starting with HSQLDB 2.1, JDBCBlob no longer utilizes volatile fields and is effectively thread safe, but still uses local variable snapshot isolation. As such, the synchronization policy still does not strictly enforce serialized read/write access to the underlying data So, if an application may perform concurrent JDBCBlob modifications and the integrity of the application depends on total order Blob modification semantics, then such operations should be synchronized on an appropriate monitor.
| |
| setBytes | back to summary |
|---|---|
| public int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException Implements java. Writes all or part of the given Note If the value specified for HSQLDB-Specific Information: Starting with HSQLDB 2.0 this feature is supported.When built under JDK 1.6+ and the Blob instance is constructed as a result of calling JDBCConnection.createBlob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createBlob() constructs disconnected, initially empty Blob instances. To propagate the Blob value to a database in this case, it is required to supply the Blob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Blob instance to an updateXXX method of an updatable ResultSet. Implementation Notes
If the value specified for Starting with HSQLDB 2.1, JDBCBlob no longer utilizes volatile fields and is effectively thread safe, but still uses local variable snapshot isolation. As such, the synchronization policy still does not strictly enforce serialized read/write access to the underlying data So, if an application may perform concurrent JDBCBlob modifications and the integrity of the application depends on total order Blob modification semantics, then such operations should be synchronized on an appropriate monitor.
| |
| setData | back to summary |
|---|---|
| private synchronized void setData(byte[] data) throws SQLException | |
| truncate | back to summary |
|---|---|
| public void truncate(final long len) throws SQLException Implements java. Truncates the Note If the value specified for HSQLDB-Specific Information: Starting with HSQLDB 2.0 this feature is fully supported.When built under JDK 1.6+ and the Blob instance is constructed as a result of calling JDBCConnection.createBlob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createBlob() constructs disconnected, initially empty Blob instances. To propagate the truncated Blob value to a database in this case, it is required to supply the Blob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Blob instance to an updateXXX method of an updateable ResultSet.
| |