CLOB type.
An SQL CLOB is 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 a Clob object using an SQL
locator(CLOB), which means that a Clob object
contains a logical pointer to the SQL CLOB data rather than
the data itself. A Clob object is valid for the duration
of the transaction in which it was created.
The Clob interface provides methods for getting the
length of an SQL CLOB (Character Large Object) value,
for materializing a CLOB value on the client, and for
searching for a substring or CLOB object within a
CLOB value.
Methods in the interfaces java.,
java., and java., such as
getClob and setClob allow a programmer to
access an SQL CLOB value. In addition, this interface
has methods for updating a CLOB value.
All methods on the Clob interface 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.
| Modifier and Type | Field and Description |
|---|---|
| private boolean | |
| private final boolean | |
| private String | |
| private static final long | |
| private static final long |
| Access | Constructor and Description |
|---|---|
| public | |
| protected |
| Modifier and Type | Method and Description |
|---|---|
| protected synchronized void | |
| protected void | |
| public synchronized void | |
| public InputStream | Returns: ajava.io.InputStream object containing the
CLOB dataImplements java. Retrieves the |
| public Reader | Returns: ajava.io.Reader object containing the
CLOB dataImplements java. Retrieves the |
| public Reader | Returns: Reader through which
the partial Clob value can be read.the offset to the first character of the partial value to
be retrieved. The first character in the Clob is at position 1. pos, long the length in characters of the partial value to be retrieved. length)Implements java. Returns a |
| pack-priv synchronized String | |
| public String | Returns: aString that is the specified substring in
the CLOB value designated by this Clob objectthe first character of the substring to be extracted.
The first character is at position 1. pos, final int the number of consecutive characters to be copied;
the value for length must be 0 or greater length)Implements java. Retrieves a copy of the specified substring
in the |
| public long | Returns: length of theCLOB in charactersImplements java. Retrieves the number of characters
in the |
| public long | Returns: the position at which the substring appears or -1 if it is not present; the first position is 1the substring for which to search searchstr, long the position at which to begin searching;
the first position is 1 start)Implements java. Retrieves the character position at which the specified substring
|
| public long | Returns: the position at which theClob object appears
or -1 if it is not present; the first position is 1the searchstr, final long Clob object for which to searchthe position at which to begin searching; the first
position is 1 start)Implements java. Retrieves the character position at which the specified
|
| public OutputStream | Returns: the stream to which ASCII encoded characters can be writtenthe position at which to start writing to this
pos)CLOB object; The first position is 1Implements java. Retrieves a stream to be used to write Ascii characters to the
|
| public Writer | Returns: a stream to which Unicode encoded characters can be writtenthe position at which to start writing to the
pos)CLOB value; The first position is 1Implements java. Retrieves a stream to be used to write a stream of Unicode characters
to the |
| private synchronized void | |
| public int | Returns: the number of characters writtenthe position at which to start writing to the pos, String CLOB
value that this Clob object represents;
the first position is 1.the string to be written to the str)CLOB
value that this Clob designatesImplements java. Writes the given Java |
| public int | Returns: the number of characters writtenthe position at which to start writing to this
pos, final String CLOB object; The first position is 1the string to be written to the str, final int CLOB
value that this Clob object representsthe offset into offset, final int str to start reading
the characters to be writtenthe number of characters to be written len)Implements java. Writes |
| public int | Returns: the number of characters writtenthe position at which to start writing to this
pos, final StringBuffer CLOB object; The first position is 1the buffer to be written to the sb, final int CLOB
value that this Clob object representsthe offset into offset, final int sb to start reading
the characters to be writtenthe number of characters to be written len)Behavior is identical to |
| public void | truncate(final long
the length, in characters, to which the len)CLOB value
should be truncatedImplements java. Truncates the |
| m_closed | back to summary |
|---|---|
| private boolean m_closed | |
| m_createdByConnection | back to summary |
|---|---|
| private final boolean m_createdByConnection | |
| m_data | back to summary |
|---|---|
| private String m_data | |
| MAX_POS | back to summary |
|---|---|
| private static final long MAX_POS | |
| MIN_POS | back to summary |
|---|---|
| private static final long MIN_POS | |
| JDBCClob | back to summary |
|---|---|
| public JDBCClob(final String data) throws SQLException Constructs 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.
| |
| JDBCClob | back to summary |
|---|---|
| protected JDBCClob() Constructs a new, empty (zero-length), read/write JDBCClob object. | |
| checkClosed | back to summary |
|---|---|
| protected synchronized void checkClosed() throws SQLException | |
| checkReadonly | back to summary |
|---|---|
| protected void checkReadonly() throws SQLException | |
| free | back to summary |
|---|---|
| public synchronized void free() throws SQLException Implements java. This method releases the resources that the
After
| |
| getAsciiStream | back to summary |
|---|---|
| public InputStream getAsciiStream() throws SQLException Implements java. Retrieves the
| |
| getCharacterStream | back to summary |
|---|---|
| public Reader getCharacterStream() throws SQLException Implements java. Retrieves the
| |
| getCharacterStream | back to summary |
|---|---|
| public Reader getCharacterStream(long pos, long length) throws SQLException Implements java. Returns a
| |
| getData | back to summary |
|---|---|
| pack-priv synchronized String getData() throws SQLException | |
| getSubString | back to summary |
|---|---|
| public String getSubString(final long pos, final int length) throws SQLException Implements java. Retrieves a copy of the specified substring
in the 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 from pos to this.length(). Another would
be to throw an exception. This class observes the second policy. Note
This method uses 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).
| |
| length | back to summary |
|---|---|
| public long length() throws SQLException Implements java. Retrieves the number of characters
in the
| |
| position | back to summary |
|---|---|
| public long position(final String searchstr, long start) throws SQLException Implements java. Retrieves the character position at which the specified substring
| |
| position | back to summary |
|---|---|
| public long position(final Clob searchstr, final long start) throws SQLException Implements java. Retrieves the character position at which the specified
| |
| setAsciiStream | back to summary |
|---|---|
| public OutputStream setAsciiStream(final long pos) throws SQLException Implements java. Retrieves a stream to be used to write Ascii characters to the
Note If the value specified for 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 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.
| |
| setCharacterStream | back to summary |
|---|---|
| public Writer setCharacterStream(final long pos) throws SQLException Implements java. Retrieves a stream to be used to write a stream of Unicode characters
to the Note If the value specified for 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 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.
| |
| setData | back to summary |
|---|---|
| private synchronized void setData(String data) throws SQLException | |
| setString | back to summary |
|---|---|
| public int setString(long pos, String str) throws SQLException Implements java. Writes the given Java Note If the value specified for 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
| |
| setString | back to summary |
|---|---|
| public int setString(final long pos, final String str, final int offset, final int len) throws SQLException Implements java. Writes Note If the value specified for 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 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.
| |
| setStringBuffer | back to summary |
|---|---|
| public int setStringBuffer(final long pos, final StringBuffer sb, final int offset, final int len) throws SQLException Behavior is identical to
| |
| truncate | back to summary |
|---|---|
| public void truncate(final long len) throws SQLException Implements java. Truncates the Note If the value specified for 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
| |