- java.lang.Object
-
- org.hsqldb.jdbc.JDBCBlobFile
-
- All Implemented Interfaces:
java.sql.Blob
public class JDBCBlobFile extends java.lang.Object implements java.sql.BlobA client-side file-based implementation of Blob.HSQLDB-Specific Information:
Starting with 2.1, in addition to HSQLDB driver support for both client-side in-memory and remote SQL CLOB data implementations, this class is provided to expose efficient, relatively high-performance BLOB operations over client accessible files.Design Notes
Although it is possible to implement a transactional version of this class, the present implementation directly propagates changes to the underlying file such that changes become visible as soon as they are either implicitly or explicitly flushed to disk.
- Since:
- HSQLDB 2.1
- Author:
- Campbell Burnet (campbell-burnet@users dot sourceforge.net)
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.StringTEMP_FILE_PREFIXstatic java.lang.StringTEMP_FILE_SUFFIX
-
Constructor Summary
Constructors Constructor Description JDBCBlobFile()Convenience constructor; equivalent to JDBCBlobFile(true);JDBCBlobFile(boolean deleteOnFree)Constructs a new instance backed by a File object created in response to invoking File.createTempFile(TEMP_FILE_PREFIX,TEMP_FILE_SUFFIX).JDBCBlobFile(java.io.File file)Convenience constructor; equivalent to JDBCBlobFile(file, false);JDBCBlobFile(java.io.File file, boolean deleteOnFree)Constructs a new instance backed by the given File object.
-
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.java.io.FilegetFile()Retrieves the canonicalFileobject denoting the file that backs this BLOB.booleanisDeleteOnFree()Retrieves whether an attempt to delete the backing file is made in response to invocation offree().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.voidsetDeleteOnFree(boolean deleteOnFree)Assigns whether an attempt to delete the backing file is made in response to invocation offree().voidtruncate(long len)Truncates theBLOBvalue that thisBlobobject represents to belenbytes in length.
-
-
-
Field Detail
-
TEMP_FILE_PREFIX
public static final java.lang.String TEMP_FILE_PREFIX
- See Also:
- Constant Field Values
-
TEMP_FILE_SUFFIX
public static final java.lang.String TEMP_FILE_SUFFIX
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
JDBCBlobFile
public JDBCBlobFile() throws java.sql.SQLExceptionConvenience constructor; equivalent to JDBCBlobFile(true);- Throws:
java.sql.SQLException- If a file could not be created or if a security manager exists and its{@link java.lang.SecurityManager#checkWrite(java.lang.String)}method does not allow a file to be created.
-
JDBCBlobFile
public JDBCBlobFile(boolean deleteOnFree) throws java.sql.SQLExceptionConstructs a new instance backed by a File object created in response to invoking File.createTempFile(TEMP_FILE_PREFIX,TEMP_FILE_SUFFIX).- Parameters:
deleteOnFree- Assigns whether an attempt to delete the backing file is to be made in response to invocation offree().- Throws:
java.sql.SQLException- If a file could not be created or if a security manager exists and its{@link java.lang.SecurityManager#checkWrite(java.lang.String)}method does not allow a file to be created.
-
JDBCBlobFile
public JDBCBlobFile(java.io.File file) throws java.sql.SQLExceptionConvenience constructor; equivalent to JDBCBlobFile(file, false);- Parameters:
file- used to back this BLOB instance.- Throws:
java.sql.SQLException- If an I/O error occurs, which is possible because the construction of the canonical pathname may require file system queries; if a required system property value cannot be accessed, or if a security manager exists and its{@link java.lang.SecurityManager#checkRead}method denies read access to the file
-
JDBCBlobFile
public JDBCBlobFile(java.io.File file, boolean deleteOnFree) throws java.sql.SQLExceptionConstructs a new instance backed by the given File object.- Parameters:
file- used to back this BLOB instance.deleteOnFree- Assigns whether an attempt to delete the backing file is to be made in response to invocation offree().- Throws:
java.sql.SQLException- If an I/O error occurs, which is possible because the construction of the canonical pathname may require file system queries; if a required system property value cannot be accessed, or if a security manager exists and its{@link java.lang.SecurityManager#checkRead}method denies read access to the file
-
-
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
-
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.- 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
- 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
- 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
-
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
-
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 aSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
This operation affects only the content of the underlying file; it has no effect upon a value stored in a database. To propagate the updated Blob value to a database, 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.- 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
- 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 aSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
This operation affects only the content of the underlying file; it has no effect upon a value stored in a database. To propagate the updated Blob value to a database, 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.- 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
- 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 aSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
Data written to the returned stream affects only the content of the underlying file; it has no effect upon a value stored in a database. To propagate the updated Blob value to a database, 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:
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
- 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 aSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
This operation affects only the length of the underlying file; it has no effect upon a value stored in a database. To propagate the truncated Blob value to a database, 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.- 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
-
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 aSQLExceptionbeing thrown. Iffreeis called multiple times, the subsequent calls tofreeare treated as a no-op.HSQLDB-Specific Information:
This operation closes any input and/or output streams obtained viagetBinaryStream(),getBinaryStream(long, long)orsetBinaryStream(long).Additionally, if the property
isDeleteOnFree()is true, then an attempt is made to delete the backing file.- 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
- See Also:
setDeleteOnFree(boolean),isDeleteOnFree()
-
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 1length- 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
-
getFile
public java.io.File getFile()
Retrieves the canonicalFileobject denoting the file that backs this BLOB.- Returns:
- the file that backs this BLOB.
-
isDeleteOnFree
public boolean isDeleteOnFree()
Retrieves whether an attempt to delete the backing file is made in response to invocation offree().- Returns:
- true if backing file deletion is attempted; otherwise false.
-
setDeleteOnFree
public void setDeleteOnFree(boolean deleteOnFree)
Assigns whether an attempt to delete the backing file is made in response to invocation offree().- Parameters:
deleteOnFree- the new value to assign
-
-