- java.lang.Object
-
- org.hsqldb.jdbc.JDBCBlob
-
- All Implemented Interfaces:
java.sql.Blob
public class JDBCBlob extends java.lang.Object implements java.sql.BlobThe representation (mapping) in the Java programming language of an SQLBLOBvalue. An SQLBLOBis a built-in type that stores a Binary Large Object as a column value in a row of a database table. By default drivers implementBlobusing an SQLlocator(BLOB), which means that aBlobobject contains a logical pointer to the SQLBLOBdata rather than the data itself. ABlobobject is valid for the duration of the transaction in which it was created.Methods in the interfaces
ResultSet,CallableStatement, andPreparedStatement, such asgetBlobandsetBloballow a programmer to access an SQLBLOBvalue. TheBlobinterface provides methods for getting the length of an SQLBLOB(Binary Large Object) value, for materializing aBLOBvalue on the client, and for determining the position of a pattern of bytes within aBLOBvalue. In addition, this interface has methods for updating aBLOBvalue.All methods on the
Blobinterface 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.- Since:
- JDK 1.2, HSQLDB 1.7.2
- Author:
- james house (jhouse@part.net), Campbell Burnet (campbell-burnet@users dot sourceforge.net)
-
-
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 voidfree()This method frees theBlobobject and releases the resources that it holds.java.io.InputStreamgetBinaryStream()Retrieves theBLOBvalue designated by thisBlobinstance as a stream.java.io.InputStreamgetBinaryStream(long pos, long length)Returns anInputStreamobject that contains a partialBlobvalue, starting with the byte specified by pos, which is length bytes in length.byte[]getBytes(long pos, int length)Retrieves all or part of theBLOBvalue that thisBlobobject represents, as an array of bytes.longlength()Returns the number of bytes in theBLOBvalue designated by thisBlobobject.longposition(byte[] pattern, long start)Retrieves the byte position at which the specified byte arraypatternbegins within theBLOBvalue that thisBlobobject represents.longposition(java.sql.Blob pattern, long start)Retrieves the byte position in theBLOBvalue designated by thisBlobobject at whichpatternbegins.java.io.OutputStreamsetBinaryStream(long pos)Retrieves a stream that can be used to write to theBLOBvalue that thisBlobobject represents.intsetBytes(long pos, byte[] bytes)Writes the given array of bytes to theBLOBvalue that thisBlobobject represents, starting at positionpos, and returns the number of bytes written.intsetBytes(long pos, byte[] bytes, int offset, int len)Writes all or part of the givenbytearray to theBLOBvalue that thisBlobobject represents and returns the number of bytes written.voidtruncate(long len)Truncates theBLOBvalue that thisBlobobject represents to belenbytes in length.
-
-
-
Constructor Detail
-
JDBCBlob
public JDBCBlob(byte[] data) throws java.sql.SQLExceptionConstructs 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.
- 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.SQLExceptionReturns the number of bytes in theBLOBvalue designated by thisBlobobject.- Specified by:
lengthin interfacejava.sql.Blob- Returns:
- length of the
BLOBin bytes - Throws:
java.sql.SQLException- if there is an error accessing the length of theBLOBjava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2, HSQLDB 1.7.2
-
getBytes
public byte[] getBytes(long pos, int length) throws java.sql.SQLExceptionRetrieves all or part of theBLOBvalue that thisBlobobject represents, as an array of bytes. Thisbytearray contains up tolengthconsecutive 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 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.- Specified by:
getBytesin interfacejava.sql.Blob- Parameters:
pos- the ordinal position of the first byte in theBLOBvalue to be extracted; the first byte is at position 1length- the number of consecutive bytes to be copied; the value for length must be 0 or greater- Returns:
- a byte array containing up to
lengthconsecutive bytes from theBLOBvalue designated by thisBlobobject, starting with the byte at positionpos - Throws:
java.sql.SQLException- if there is an error accessing theBLOBvalue; if pos is less than 1 or length is less than 0java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
setBytes(long, byte[])
-
getBinaryStream
public java.io.InputStream getBinaryStream() throws java.sql.SQLExceptionRetrieves theBLOBvalue designated by thisBlobinstance as a stream.- Specified by:
getBinaryStreamin interfacejava.sql.Blob- Returns:
- a stream containing the
BLOBdata - Throws:
java.sql.SQLException- if there is an error accessing theBLOBvaluejava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
setBinaryStream(long)
-
position
public long position(byte[] pattern, long start) throws java.sql.SQLExceptionRetrieves the byte position at which the specified byte arraypatternbegins within theBLOBvalue that thisBlobobject represents. The search forpatternbegins at positionstart.- Specified by:
positionin 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 theBLOBor if start is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2, HSQLDB 1.7.2
-
position
public long position(java.sql.Blob pattern, long start) throws java.sql.SQLExceptionRetrieves the byte position in theBLOBvalue designated by thisBlobobject at whichpatternbegins. The search begins at positionstart.- Specified by:
positionin interfacejava.sql.Blob- Parameters:
pattern- theBlobobject designating theBLOBvalue for which to searchstart- the position in theBLOBvalue 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 theBLOBvalue or if start is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2, HSQLDB 1.7.2
-
setBytes
public int setBytes(long pos, byte[] bytes) throws java.sql.SQLExceptionWrites the given array of bytes to theBLOBvalue that thisBlobobject represents, starting at positionpos, and returns the number of bytes written. The array of bytes will overwrite the existing bytes in theBlobobject starting at the positionpos. If the end of theBlobvalue is reached while writing the array of bytes, then the length of theBlobvalue will be increased to accommodate the extra bytes.Note: If the value specified for
posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.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.
- Specified by:
setBytesin interfacejava.sql.Blob- Parameters:
pos- the position in theBLOBobject at which to start writing; the first position is 1bytes- the array of bytes to be written to theBLOBvalue that thisBlobobject represents- Returns:
- the number of bytes written
- Throws:
java.sql.SQLException- if there is an error accessing theBLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- 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.SQLExceptionWrites all or part of the givenbytearray to theBLOBvalue that thisBlobobject represents and returns the number of bytes written. Writing starts at positionposin theBLOBvalue;lenbytes from the given byte array are written. The array of bytes will overwrite the existing bytes in theBlobobject starting at the positionpos. If the end of theBlobvalue is reached while writing the array of bytes, then the length of theBlobvalue will be increased to accommodate the extra bytes.Note: If the value specified for
posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.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
posis greater than the length of theBLOBvalue, then theBLOBvalue is extended in length to accept the written octets and the undefined region up toposis filled with (byte)0.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.
- Specified by:
setBytesin interfacejava.sql.Blob- Parameters:
pos- the position in theBLOBobject at which to start writing; the first position is 1bytes- the array of bytes to be written to thisBLOBobjectoffset- the offset into the arraybytesat which to start reading the bytes to be setlen- the number of bytes to be written to theBLOBvalue from the array of bytesbytes- Returns:
- the number of bytes written
- Throws:
java.sql.SQLException- if there is an error accessing theBLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
getBytes(long, int)
-
setBinaryStream
public java.io.OutputStream setBinaryStream(long pos) throws java.sql.SQLExceptionRetrieves a stream that can be used to write to theBLOBvalue that thisBlobobject represents. The stream begins at positionpos. The bytes written to the stream will overwrite the existing bytes in theBlobobject starting at the positionpos. If the end of theBlobvalue is reached while writing to the stream, then the length of theBlobvalue will be increased to accommodate the extra bytes.Note: If the value specified for
posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.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
posis greater than the length of theBLOBvalue, then theBLOBvalue is extended in length to accept the written octets and the undefined region up toposis filled with (byte)0.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.
- Specified by:
setBinaryStreamin interfacejava.sql.Blob- Parameters:
pos- the position in theBLOBvalue at which to start writing; the first position is 1- Returns:
- a
java.io.OutputStreamobject to which data can be written - Throws:
java.sql.SQLException- if there is an error accessing theBLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
getBinaryStream()
-
truncate
public void truncate(long len) throws java.sql.SQLExceptionTruncates theBLOBvalue that thisBlobobject represents to belenbytes in length.Note: If the value specified for
posis greater than the length+1 of theBLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.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.
- Specified by:
truncatein interfacejava.sql.Blob- Parameters:
len- the length, in bytes, to which theBLOBvalue that thisBlobobject represents should be truncated- Throws:
java.sql.SQLException- if there is an error accessing theBLOBvalue or if len is less than 0java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4, HSQLDB 1.7.2
-
free
public void free() throws java.sql.SQLExceptionThis method frees theBlobobject and releases the resources that it holds. The object is invalid once thefreemethod is called.After
freehas been called, any attempt to invoke a method other thanfreewill result in anSQLExceptionbeing thrown. Iffreeis called multiple times, the subsequent calls tofreeare treated as a no-op.- Specified by:
freein interfacejava.sql.Blob- Throws:
java.sql.SQLException- if an error occurs releasing the Blob's resourcesjava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.6, HSQLDB 2.0
-
getBinaryStream
public java.io.InputStream getBinaryStream(long pos, long length) throws java.sql.SQLExceptionReturns anInputStreamobject that contains a partialBlobvalue, starting with the byte specified by pos, which is length bytes in length.- Specified by:
getBinaryStreamin interfacejava.sql.Blob- Parameters:
pos- the offset to the first byte of the partial value to be retrieved. The first byte in theBlobis at position 1.length- the length in bytes of the partial value to be retrieved- Returns:
InputStreamthrough which the partialBlobvalue can be read.- Throws:
java.sql.SQLException- if pos is less than 1 or if pos is greater than the number of bytes in theBlobor if pos + length is greater than the number of bytes in theBlobjava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.6, HSQLDB 2.0
-
-