- java.lang.Object
-
- org.hsqldb.jdbc.JDBCClob
-
- All Implemented Interfaces:
java.sql.Clob
- Direct Known Subclasses:
JDBCNClob
public class JDBCClob extends java.lang.Object implements java.sql.ClobThe mapping in the Java programming language for the SQLCLOBtype. An SQLCLOBis a built-in type that stores a Character Large Object as a column value in a row of a database table. By default drivers implement aClobobject using an SQLlocator(CLOB), which means that aClobobject contains a logical pointer to the SQLCLOBdata rather than the data itself. AClobobject is valid for the duration of the transaction in which it was created.The
Clobinterface provides methods for getting the length of an SQLCLOB(Character Large Object) value, for materializing aCLOBvalue on the client, and for searching for a substring orCLOBobject within aCLOBvalue. Methods in the interfacesResultSet,CallableStatement, andPreparedStatement, such asgetClobandsetCloballow a programmer to access an SQLCLOBvalue. In addition, this interface has methods for updating aCLOBvalue.All methods on the
Clobinterface 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 Clob using an SQL locator(CLOB). That is, an HSQLDB Clob object did not contain a logical pointer to SQL CLOB data; rather it directly contained a representation of the data (a String). As a result, an HSQLDB Clob 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 CLOB 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 CLOB data implementations, meaning that an HSQLDB Clob object may contain a logical pointer to remote SQL CLOB data (see
JDBCClobClient) 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 Clob instance is constructed as a result of calling JDBCConnection.createClob(), then the resulting Clob 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 CLOB value are supported for local use until the first invocation of free(); otherwise, an HSQLDB Clob'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:
- Campbell Burnet (campbell-burnet@users dot sourceforge.net)
-
-
Constructor Summary
Constructors Constructor Description JDBCClob(java.lang.String data)Constructs a new, read-only JDBCClob object wrapping the given character sequence.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidfree()This method releases the resources that theClobobject 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.StringgetSubString(long pos, int length)Retrieves a copy of the specified substring in theCLOBvalue designated by thisClobobject.longlength()Retrieves the number of characters in theCLOBvalue designated 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 searchstr, 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.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.intsetStringBuffer(long pos, java.lang.StringBuffer sb, int offset, int len)Behavior is identical tosetString(long, java.lang.String, int, int).voidtruncate(long len)Truncates theCLOBvalue that thisClobdesignates to have a length oflencharacters.
-
-
-
Constructor Detail
-
JDBCClob
public JDBCClob(java.lang.String data) throws java.sql.SQLExceptionConstructs a new, read-only JDBCClob object wrapping the given character sequence.This constructor is used internally to retrieve result set values as Clob 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 String object rather than making a copy and so it is gently suggested (in the interest of effective memory management) that external clients using this constructor either take pause to consider the implications or at least take care to provide a String object whose internal character buffer is not much larger than required to represent the value.
- Parameters:
data- the character sequence representing the Clob value- Throws:
java.sql.SQLException- if the argument is null
-
-
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, HSQLDB 1.7.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.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 characters frompostothis.length(). Another would be to throw an exception. This class observes the second policy.Note
This method uses
String.substring(int, int).Depending on implementation (typically JDK 6 and earlier releases), the returned value may be sharing the underlying (and possibly much larger) character buffer. Depending on factors such as hardware acceleration for array copies, the average length and number of sub-strings taken, and so on, this may or may not result in faster operation and non-trivial memory savings. On the other hand, Oracle / OpenJDK 7, it was decided that the memory leak implications outweigh the benefits of buffer sharing for most use cases on modern hardware.
It is left up to any client of this method to determine if this is a potential factor relative to the target runtime and to decide how to handle space-time trade-offs (i.e. whether to make an isolated copy of the returned substring or risk that more memory remains allocated than is absolutely required).
- 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, HSQLDB 1.7.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, HSQLDB 1.7.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, HSQLDB 1.7.2
- See Also:
setAsciiStream(long)
-
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 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.Clob searchstr, 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:
searchstr- 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, HSQLDB 1.7.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 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 Clob instance is constructed as a result of calling JDBCConnection.createClob(), this operation affects only the client-side value; it has no effect upon a value stored in the database because JDBCConnection.createClob() constructs disconnected, initially empty Clob instances. To propagate the Clob value to a database in this case, it is required to supply the Clob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Clob instance to an updateXXX method of an updateable ResultSet.
Implementation Notes:
No attempt is made to ensure precise thread safety. Instead, volatile member field and local variable snapshot isolation semantics are implemented. This is expected to eliminate most issues related to race conditions, with the possible exception of concurrent invocation of free().
In general, if an application may perform concurrent JDBCClob modifications and the integrity of the application depends on total order Clob modification semantics, then such operations should be synchronized on an appropriate monitor.
When the value specified for
posis greater then the length+1, then the CLOB value is extended in length to accept the written characters and the undefined region up to @{code pos} is filled with with space (' ') characters.- Specified by:
setStringin interfacejava.sql.Clob- Parameters:
pos- the position at which to start writing to theCLOBvalue that thisClobobject represents; the first position is 1.str- 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, HSQLDB 1.7.2
-
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 anSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
Starting with HSQLDB 2.0 this feature is supported.When the Clob instance is constructed as a result of calling JDBCConnection.createClob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createClob() constructs disconnected, initially empty Clob instances. To propagate the Clob value to a database in this case, it is required to supply the Clob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Clob instance to an updateXXX method of an updateable ResultSet.
Implementation Notes:
If the value specified for
posis greater than the length of theCLOBvalue, then theCLOBvalue is extended in length to accept the written characters and the undefined region up toposis filled with space (' ') characters.No attempt is made to ensure precise thread safety. Instead, volatile member field and local variable snapshot isolation semantics are implemented. This is expected to eliminate most issues related to race conditions, with the possible exception of concurrent invocation of free().
In general, if an application may perform concurrent JDBCClob modifications and the integrity of the application depends on total order Clob modification semantics, then such operations should be synchronized on an appropriate monitor.
- 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, HSQLDB 1.7.2
-
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 anSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
Starting with HSQLDB 2.0 this feature is supported.When the Clob instance is constructed as a result of calling JDBCConnection.createClob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createClob() constructs disconnected, initially empty Clob instances. To propagate the Clob value to a database in this case, it is required to supply the Clob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Clob instance to an updateXXX method of an updatable ResultSet.
Implementation Notes:
The data written to the stream does not appear in this Clob until the stream is closed.
When the stream is closed, if the value specified for
posis greater than the length of theCLOBvalue, then theCLOBvalue is extended in length to accept the written characters and the undefined region up toposis filled with space (' ') characters.Also, no attempt is made to ensure precise thread safety. Instead, volatile member field and local variable snapshot isolation semantics are implemented. This is expected to eliminate most issues related to race conditions, with the possible exception of concurrent invocation of free().
In general, if an application may perform concurrent JDBCClob modifications and the integrity of the application depends on total order Clob modification semantics, then such operations should be synchronized on an appropriate monitor.
- 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, HSQLDB 1.7.2
- 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:
Starting with HSQLDB 2.0 this feature is supported.When the Clob instance is constructed as a result of calling JDBCConnection.createClob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createClob() constructs disconnected, initially empty Clob instances. To propagate the Clob value to a database in this case, it is required to supply the Clob instance to an updating or inserting setXXX method of a Prepared or Callable Statement, or to supply the Clob instance to an updateXXX method of an updateable ResultSet.
Implementation Notes:
The data written to the stream does not appear in this Clob until the stream is closed.
When the stream is closed, if the value specified for
posis greater than the length of theCLOBvalue, then theCLOBvalue is extended in length to accept the written characters and the undefined region up toposis filled with space (' ') characters.Also, no attempt is made to ensure precise thread safety. Instead, volatile member field and local variable snapshot isolation semantics are implemented. This is expected to eliminate most issues related to race conditions, with the possible exception of concurrent invocation of free().
In general, if an application may perform concurrent JDBCClob modifications and the integrity of the application depends on total order Clob modification semantics, then such operations should be synchronized on an appropriate monitor.
- 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 ifposis less than 1java.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.4, HSQLDB 1.7.2
- 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 anSQLExceptionwhile other drivers may support this operation.HSQLDB-Specific Information:
Starting with HSQLDB 2.0 this feature is fully supported.When the Clob instance is constructed as a result of calling JDBCConnection.createClob(), this operation affects only the client-side value; it has no effect upon a value stored in a database because JDBCConnection.createClob() constructs disconnected, initially empty Blob instances. To propagate the truncated Clob value to a database in this case, it is required to supply the Clob 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.
Implementation Notes:
HSQLDB throws an SQLException if the specified
lenis greater than the value returned bylength.- 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, HSQLDB 1.7.2
-
free
public void free() throws java.sql.SQLExceptionThis method releases the resources that theClobobject 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.6, HSQLDB 2.0
-
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 theClob; or if pos + length is greater than the number of characters in theClobjava.sql.SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- JDK 1.6, HSQLDB 2.0
-
setStringBuffer
public int setStringBuffer(long pos, java.lang.StringBuffer sb, int offset, int len) throws java.sql.SQLExceptionBehavior is identical tosetString(long, java.lang.String, int, int).- Parameters:
pos- the position at which to start writing to thisCLOBobject; The first position is 1sb- the buffer to be written to theCLOBvalue that thisClobobject representsoffset- the offset intosbto 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 1
-
-