- java.lang.Object
-
- org.hsqldb.jdbc.JDBCClobFile
-
- All Implemented Interfaces:
java.sql.Clob
public class JDBCClobFile extends java.lang.Object implements java.sql.ClobA client-side file-based implementation of Clob.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 CLOB 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 JDBCClobFile()Convenience constructor forJDBCClobFile((String)null).JDBCClobFile(java.io.File file)Convenience constructor forJDBCClobFile(file,null).JDBCClobFile(java.io.File file, java.lang.String encoding)Constructs a new JDBCClobFile instance backed by the given File object using the given encoding to read and write file content.JDBCClobFile(java.lang.String encoding)Constructs a new JDBCClobFile instance backed by a File object created by File.createTempFile(TEMP_FILE_PREFIX, TEMP_FILE_SUFFIX), using the given encoding to read and write file content.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidfree()This method frees theClobobject and releases the resources that it holds.java.io.InputStreamgetAsciiStream()Retrieves theCLOBvalue designated by thisClobobject as an ASCII stream.java.io.ReadergetCharacterStream()Retrieves theCLOBvalue designated by thisClobobject as ajava.io.Readerobject (or as a stream of characters).java.io.ReadergetCharacterStream(long pos, long length)Returns aReaderobject that contains a partialClobvalue, starting with the character specified by pos, which is length characters in length.java.lang.StringgetEncoding()java.io.FilegetFile()Retrieves the canonicalFileobject denoting the file that backs this CLOB.java.lang.StringgetSubString(long pos, int length)Retrieves a copy of the specified substring in theCLOBvalue designated by thisClobobject.booleanisDeleteOnFree()Retrieves whether an attempt to delete the backing file is made in response to invocation offree().longlength()Retrieves the number of characters in theCLOBvalue designated by thisClobobject.longposition(char[] pattern, long start)Retrieves the character position at which the specified char[]patternappears in theCLOBvalue represented by thisClobobject.longposition(java.lang.String searchstr, long start)Retrieves the character position at which the specified substringsearchstrappears in the SQLCLOBvalue represented by thisClobobject.longposition(java.sql.Clob pattern, long start)Retrieves the character position at which the specifiedClobobjectsearchstrappears in thisClobobject.java.io.OutputStreamsetAsciiStream(long pos)Retrieves a stream to be used to write Ascii characters to theCLOBvalue that thisClobobject represents, starting at positionpos.java.io.WritersetCharacterStream(long pos)Retrieves a stream to be used to write a stream of Unicode characters to theCLOBvalue that thisClobobject represents, at positionpos.voidsetDeleteOnFree(boolean deleteOnFree)Assigns whether an attempt to delete the backing file is made in response to invocation offree().intsetString(long pos, java.lang.String str)Writes the given JavaStringto theCLOBvalue that thisClobobject designates at the positionpos.intsetString(long pos, java.lang.String str, int offset, int len)Writeslencharacters ofstr, starting at characteroffset, to theCLOBvalue that thisClobrepresents.voidtruncate(long len)Truncates theCLOBvalue that thisClobdesignates to have a length oflencharacters.
-
-
-
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
-
JDBCClobFile
public JDBCClobFile() throws java.sql.SQLExceptionConvenience constructor forJDBCClobFile((String)null).- Throws:
java.sql.SQLException- if the platform encoding is unsupported, the temp file cannot be created or some other error occurs that prevents the construction of a valid instance of this class.
-
JDBCClobFile
public JDBCClobFile(java.lang.String encoding) throws java.sql.SQLExceptionConstructs a new JDBCClobFile instance backed by a File object created by File.createTempFile(TEMP_FILE_PREFIX, TEMP_FILE_SUFFIX), using the given encoding to read and write file content.- Parameters:
encoding- the name of the character encoding used to read and write character data in the underlying file, as well as to determine the character length of and character offsets into the underlying file. Specify null to denote the platform encoding.- Throws:
java.sql.SQLException- if the given encoding is unsupported, the backing temp 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.
-
JDBCClobFile
public JDBCClobFile(java.io.File file) throws java.sql.SQLExceptionConvenience constructor forJDBCClobFile(file,null).- Parameters:
file- that is to back the new CLOB 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; a required system property value cannot be accessed; a security manager exists and its{@link java.lang.SecurityManager#checkRead}method denies read access to the file
-
JDBCClobFile
public JDBCClobFile(java.io.File file, java.lang.String encoding) throws java.sql.SQLExceptionConstructs a new JDBCClobFile instance backed by the given File object using the given encoding to read and write file content.- Parameters:
file- that is to back the new CLOB instance.encoding- the name of the character encoding used to read and write character data in the underlying file, as well as to determine the character length of and character offsets into the underlying file. Specify null to denote the platform encoding.- Throws:
java.sql.SQLException- if the given encoding is unsupported; an I/O error occurs, which is possible because the construction of the canonical pathname may require file-system queries; a required system property value cannot be accessed; 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.SQLExceptionRetrieves the number of characters in theCLOBvalue designated by thisClobobject.- Specified by:
lengthin interfacejava.sql.Clob- Returns:
- length of the
CLOBin characters - Throws:
java.sql.SQLException- if there is an error accessing the length of theCLOBvaluejava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2
-
getSubString
public java.lang.String getSubString(long pos, int length) throws java.sql.SQLExceptionRetrieves a copy of the specified substring in theCLOBvalue designated by thisClobobject. The substring begins at positionposand has up tolengthconsecutive characters.- Specified by:
getSubStringin interfacejava.sql.Clob- Parameters:
pos- the first character of the substring to be extracted. The first character is at position 1.length- the number of consecutive characters to be copied; the value for length must be 0 or greater- Returns:
- a
Stringthat is the specified substring in theCLOBvalue designated by thisClobobject - Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue; 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
-
getCharacterStream
public java.io.Reader getCharacterStream() throws java.sql.SQLExceptionRetrieves theCLOBvalue designated by thisClobobject as ajava.io.Readerobject (or as a stream of characters).- Specified by:
getCharacterStreamin interfacejava.sql.Clob- Returns:
- a
java.io.Readerobject containing theCLOBdata - Throws:
java.sql.SQLException- if there is an error accessing theCLOBvaluejava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2
- See Also:
setCharacterStream(long)
-
getAsciiStream
public java.io.InputStream getAsciiStream() throws java.sql.SQLExceptionRetrieves theCLOBvalue designated by thisClobobject as an ASCII stream.- Specified by:
getAsciiStreamin interfacejava.sql.Clob- Returns:
- a
java.io.InputStreamobject containing theCLOBdata - Throws:
java.sql.SQLException- if there is an error accessing theCLOBvaluejava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2
- See Also:
setAsciiStream(long)
-
position
public long position(char[] pattern, long start) throws java.sql.SQLExceptionRetrieves the character position at which the specified char[]patternappears in theCLOBvalue represented by thisClobobject. The search begins at positionstart.- Parameters:
pattern- the substring for which to searchstart- the position at which to begin searching; the first position is 1- Returns:
- the position at which the substring appears or -1 if it is not present; the first position is 1
- Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method
-
position
public long position(java.lang.String searchstr, long start) throws java.sql.SQLExceptionRetrieves the character position at which the specified substringsearchstrappears in the SQLCLOBvalue represented by thisClobobject. The search begins at positionstart.- Specified by:
positionin interfacejava.sql.Clob- Parameters:
searchstr- the substring for which to searchstart- the position at which to begin searching; the first position is 1- Returns:
- the position at which the substring appears or -1 if it is not present; the first position is 1
- Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue or if pos 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.Clob pattern, long start) throws java.sql.SQLExceptionRetrieves the character position at which the specifiedClobobjectsearchstrappears in thisClobobject. The search begins at positionstart.- Specified by:
positionin interfacejava.sql.Clob- Parameters:
pattern- theClobobject for which to searchstart- the position at which to begin searching; the first position is 1- Returns:
- the position at which the
Clobobject appears or -1 if it is not present; the first position is 1 - Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue or if start is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.2
-
setString
public int setString(long pos, java.lang.String str) throws java.sql.SQLExceptionWrites the given JavaStringto theCLOBvalue that thisClobobject designates at the positionpos. The string will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing the given string, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw aSQLExceptionwhile other drivers may support this operation.- Specified by:
setStringin interfacejava.sql.Clob- Parameters:
pos- the position at which to start writing to theCLOBvalue that thisClobobject represents; The first position is 1str- the string to be written to theCLOBvalue that thisClobdesignates- Returns:
- the number of characters written
- Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4
-
setString
public int setString(long pos, java.lang.String str, int offset, int len) throws java.sql.SQLExceptionWriteslencharacters ofstr, starting at characteroffset, to theCLOBvalue that thisClobrepresents. The string will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing the given string, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw aSQLExceptionwhile other drivers may support this operation.- Specified by:
setStringin interfacejava.sql.Clob- Parameters:
pos- the position at which to start writing to thisCLOBobject; The first position is 1str- the string to be written to theCLOBvalue that thisClobobject representsoffset- the offset intostrto start reading the characters to be writtenlen- the number of characters to be written- Returns:
- the number of characters written
- Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4
-
setAsciiStream
public java.io.OutputStream setAsciiStream(long pos) throws java.sql.SQLExceptionRetrieves a stream to be used to write Ascii characters to theCLOBvalue that thisClobobject represents, starting at positionpos. Characters written to the stream will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing characters to the stream, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw aSQLExceptionwhile other drivers may support this operation.- Specified by:
setAsciiStreamin interfacejava.sql.Clob- Parameters:
pos- the position at which to start writing to thisCLOBobject; The first position is 1- Returns:
- the stream to which ASCII encoded characters can be written
- Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4
- See Also:
getAsciiStream()
-
setCharacterStream
public java.io.Writer setCharacterStream(long pos) throws java.sql.SQLExceptionRetrieves a stream to be used to write a stream of Unicode characters to theCLOBvalue that thisClobobject represents, at positionpos. Characters written to the stream will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing characters to the stream, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw aSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
When the value specified forposis greater then the length+1, anSQLExceptionis thrown.- Specified by:
setCharacterStreamin interfacejava.sql.Clob- Parameters:
pos- the position at which to start writing to theCLOBvalue; The first position is 1- Returns:
- a stream to which Unicode encoded characters can be written
- Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4
- See Also:
getCharacterStream()
-
truncate
public void truncate(long len) throws java.sql.SQLExceptionTruncates theCLOBvalue that thisClobdesignates to have a length oflencharacters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw aSQLExceptionwhile other drivers may support this operation.- Specified by:
truncatein interfacejava.sql.Clob- Parameters:
len- the length, in characters, to which theCLOBvalue should be truncated- Throws:
java.sql.SQLException- if there is an error accessing theCLOBvalue 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 theClobobject 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.- Specified by:
freein interfacejava.sql.Clob- Throws:
java.sql.SQLException- if an error occurs releasing the Clob's resourcesjava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4
-
getCharacterStream
public java.io.Reader getCharacterStream(long pos, long length) throws java.sql.SQLExceptionReturns aReaderobject that contains a partialClobvalue, starting with the character specified by pos, which is length characters in length.- Specified by:
getCharacterStreamin interfacejava.sql.Clob- Parameters:
pos- the offset to the first character of the partial value to be retrieved. The first character in the Clob is at position 1.length- the length in characters of the partial value to be retrieved.- Returns:
Readerthrough which the partialClobvalue can be read.- Throws:
java.sql.SQLException- if pos is less than 1 or if pos is greater than the number of characters in theClobor if pos + length is greater than the number of characters in theClobjava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.6
-
getFile
public java.io.File getFile()
Retrieves the canonicalFileobject denoting the file that backs this CLOB.- Returns:
- the file that backs this CLOB.
-
getEncoding
public java.lang.String getEncoding()
- Returns:
- the name of the character encoding used to read and write character data in the underlying files, as well as to determine the character length and character offsets into the underlying file
-
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
-
-