- All Implemented Interfaces:
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 -
Constructor Summary
ConstructorsConstructorDescriptionConvenience constructor forJDBCClobFile((String)null)
.JDBCClobFile
(File file) Convenience constructor forJDBCClobFile(file,null)
.JDBCClobFile
(File file, String encoding) Constructs a new JDBCClobFile instance backed by the given File object using the given encoding to read and write file content.JDBCClobFile
(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
Modifier and TypeMethodDescriptionvoid
free()
This method frees theClob
object and releases the resources that it holds.Retrieves theCLOB
value designated by thisClob
object as an ASCII stream.Retrieves theCLOB
value designated by thisClob
object as ajava.io.Reader
object (or as a stream of characters).getCharacterStream
(long pos, long length) Returns aReader
object that contains a partialClob
value, starting with the character specified by pos, which is length characters in length.getFile()
Retrieves the canonicalFile
object denoting the file that backs this CLOB.getSubString
(long pos, int length) Retrieves a copy of the specified substring in theCLOB
value designated by thisClob
object.boolean
Retrieves whether an attempt to delete the backing file is made in response to invocation offree()
.long
length()
Retrieves the number of characters in theCLOB
value designated by thisClob
object.long
position
(char[] pattern, long start) Retrieves the character position at which the specified char[]pattern
appears in theCLOB
value represented by thisClob
object.long
Retrieves the character position at which the specified substringsearchstr
appears in the SQLCLOB
value represented by thisClob
object.long
Retrieves the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object.setAsciiStream
(long pos) Retrieves a stream to be used to write Ascii characters to theCLOB
value that thisClob
object represents, starting at positionpos
.setCharacterStream
(long pos) Retrieves a stream to be used to write a stream of Unicode characters to theCLOB
value that thisClob
object represents, at positionpos
.void
setDeleteOnFree
(boolean deleteOnFree) Assigns whether an attempt to delete the backing file is made in response to invocation offree()
.int
Writes the given JavaString
to theCLOB
value that thisClob
object designates at the positionpos
.int
Writeslen
characters ofstr
, starting at characteroffset
, to theCLOB
value that thisClob
represents.void
truncate
(long len) Truncates theCLOB
value that thisClob
designates to have a length oflen
characters.
-
Field Details
-
TEMP_FILE_PREFIX
- See Also:
-
TEMP_FILE_SUFFIX
- See Also:
-
-
Constructor Details
-
JDBCClobFile
Convenience constructor forJDBCClobFile((String)null)
.- Throws:
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
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.- 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:
SQLException
- if the given encoding is unsupported, the backing temp file could not be created or if a security manager exists and its
method does not allow a file to be created.SecurityManager.checkWrite(java.lang.String)
-
JDBCClobFile
Convenience constructor forJDBCClobFile(file,null)
.- Parameters:
file
- that is to back the new CLOB instance.- Throws:
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
method denies read access to the fileSecurityManager.checkRead(java.io.FileDescriptor)
-
JDBCClobFile
Constructs 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:
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
method denies read access to the fileSecurityManager.checkRead(java.io.FileDescriptor)
-
-
Method Details
-
length
Retrieves the number of characters in theCLOB
value designated by thisClob
object.- Specified by:
length
in interfaceClob
- Returns:
- length of the
CLOB
in characters - Throws:
SQLException
- if there is an error accessing the length of theCLOB
valueSQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.2
-
getSubString
Retrieves a copy of the specified substring in theCLOB
value designated by thisClob
object. The substring begins at positionpos
and has up tolength
consecutive characters.- Specified by:
getSubString
in interfaceClob
- 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
String
that is the specified substring in theCLOB
value designated by thisClob
object - Throws:
SQLException
- if there is an error accessing theCLOB
value; if pos is less than 1 or length is less than 0SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.2
-
getCharacterStream
Retrieves theCLOB
value designated by thisClob
object as ajava.io.Reader
object (or as a stream of characters).- Specified by:
getCharacterStream
in interfaceClob
- Returns:
- a
java.io.Reader
object containing theCLOB
data - Throws:
SQLException
- if there is an error accessing theCLOB
valueSQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.2
- See Also:
-
getAsciiStream
Retrieves theCLOB
value designated by thisClob
object as an ASCII stream.- Specified by:
getAsciiStream
in interfaceClob
- Returns:
- a
java.io.InputStream
object containing theCLOB
data - Throws:
SQLException
- if there is an error accessing theCLOB
valueSQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.2
- See Also:
-
position
Retrieves the character position at which the specified char[]pattern
appears in theCLOB
value represented by thisClob
object. 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:
SQLException
- if there is an error accessing theCLOB
value or if pos is less than 1SQLFeatureNotSupportedException
- if the JDBC driver does not support this method
-
position
Retrieves the character position at which the specified substringsearchstr
appears in the SQLCLOB
value represented by thisClob
object. The search begins at positionstart
.- Specified by:
position
in interfaceClob
- 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:
SQLException
- if there is an error accessing theCLOB
value or if pos is less than 1SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.2
-
position
Retrieves the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object. The search begins at positionstart
.- Specified by:
position
in interfaceClob
- Parameters:
pattern
- theClob
object for which to searchstart
- the position at which to begin searching; the first position is 1- Returns:
- the position at which the
Clob
object appears or -1 if it is not present; the first position is 1 - Throws:
SQLException
- if there is an error accessing theCLOB
value or if start is less than 1SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.2
-
setString
Writes the given JavaString
to theCLOB
value that thisClob
object designates at the positionpos
. The string will overwrite the existing characters in theClob
object starting at the positionpos
. If the end of theClob
value is reached while writing the given string, then the length of theClob
value will be increased to accommodate the extra characters.Note: If the value specified for
pos
is greater than the length+1 of theCLOB
value then the behavior is undefined. Some JDBC drivers may throw aSQLException
while other drivers may support this operation.- Specified by:
setString
in interfaceClob
- Parameters:
pos
- the position at which to start writing to theCLOB
value that thisClob
object represents; The first position is 1str
- the string to be written to theCLOB
value that thisClob
designates- Returns:
- the number of characters written
- Throws:
SQLException
- if there is an error accessing theCLOB
value or if pos is less than 1SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.4
-
setString
Writeslen
characters ofstr
, starting at characteroffset
, to theCLOB
value that thisClob
represents. The string will overwrite the existing characters in theClob
object starting at the positionpos
. If the end of theClob
value is reached while writing the given string, then the length of theClob
value will be increased to accommodate the extra characters.Note: If the value specified for
pos
is greater than the length+1 of theCLOB
value then the behavior is undefined. Some JDBC drivers may throw aSQLException
while other drivers may support this operation.- Specified by:
setString
in interfaceClob
- Parameters:
pos
- the position at which to start writing to thisCLOB
object; The first position is 1str
- the string to be written to theCLOB
value that thisClob
object representsoffset
- the offset intostr
to start reading the characters to be writtenlen
- the number of characters to be written- Returns:
- the number of characters written
- Throws:
SQLException
- if there is an error accessing theCLOB
value or if pos is less than 1SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.4
-
setAsciiStream
Retrieves a stream to be used to write Ascii characters to theCLOB
value that thisClob
object represents, starting at positionpos
. Characters written to the stream will overwrite the existing characters in theClob
object starting at the positionpos
. If the end of theClob
value is reached while writing characters to the stream, then the length of theClob
value will be increased to accommodate the extra characters.Note: If the value specified for
pos
is greater than the length+1 of theCLOB
value then the behavior is undefined. Some JDBC drivers may throw aSQLException
while other drivers may support this operation.- Specified by:
setAsciiStream
in interfaceClob
- Parameters:
pos
- the position at which to start writing to thisCLOB
object; The first position is 1- Returns:
- the stream to which ASCII encoded characters can be written
- Throws:
SQLException
- if there is an error accessing theCLOB
value or if pos is less than 1SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.4
- See Also:
-
setCharacterStream
Retrieves a stream to be used to write a stream of Unicode characters to theCLOB
value that thisClob
object represents, at positionpos
. Characters written to the stream will overwrite the existing characters in theClob
object starting at the positionpos
. If the end of theClob
value is reached while writing characters to the stream, then the length of theClob
value will be increased to accommodate the extra characters.Note: If the value specified for
pos
is greater than the length+1 of theCLOB
value then the behavior is undefined. Some JDBC drivers may throw aSQLException
while other drivers may support this operation.HSQLDB-Specific Information:
When the value specified for
pos
is greater then the length+1, anSQLException
is thrown.- Specified by:
setCharacterStream
in interfaceClob
- Parameters:
pos
- the position at which to start writing to theCLOB
value; The first position is 1- Returns:
- a stream to which Unicode encoded characters can be written
- Throws:
SQLException
- if there is an error accessing theCLOB
value or if pos is less than 1SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.4
- See Also:
-
truncate
Truncates theCLOB
value that thisClob
designates to have a length oflen
characters.Note: If the value specified for
pos
is greater than the length+1 of theCLOB
value then the behavior is undefined. Some JDBC drivers may throw aSQLException
while other drivers may support this operation.- Specified by:
truncate
in interfaceClob
- Parameters:
len
- the length, in characters, to which theCLOB
value should be truncated- Throws:
SQLException
- if there is an error accessing theCLOB
value or if len is less than 0SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.4
-
free
This method frees theClob
object and releases the resources that it holds. The object is invalid once thefree
method is called.After
free
has been called, any attempt to invoke a method other thanfree
will result in aSQLException
being thrown. Iffree
is called multiple times, the subsequent calls tofree
are treated as a no-op.- Specified by:
free
in interfaceClob
- Throws:
SQLException
- if an error occurs releasing the Clob's resourcesSQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- JDK 1.4
-
getCharacterStream
Returns aReader
object that contains a partialClob
value, starting with the character specified by pos, which is length characters in length.- Specified by:
getCharacterStream
in interfaceClob
- 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:
Reader
through which the partialClob
value can be read.- Throws:
SQLException
- if pos is less than 1 or if pos is greater than the number of characters in theClob
or if pos + length is greater than the number of characters in theClob
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method- Since:
- 1.6
-
getFile
Retrieves the canonicalFile
object denoting the file that backs this CLOB.- Returns:
- the file that backs this CLOB.
-
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
-