Class jdbcClob
- All Implemented Interfaces:
Clob
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.
HSQLDB-Specific Information:
Including 1.8.x, the HSQLDB driver does not implement Clob using an SQL locator(CLOB). That is, an HSQLDB Clob object does not contain a logical pointer to SQL CLOB data; rather it directly contains an immutable representation of the data (a String object). As a result, an HSQLDB Clob object itself is valid beyond the duration of the transaction in which is was created, although it does not necessarily represent a corresponding value on the database.
Currently, the interface methods for updating a CLOB value are unsupported. However, the truncate method is supported for local use.
- Since:
- JDK 1.2, HSQLDB 1.7.2
- Author:
- boucherb@users
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
free()
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) getSubString
(long pos, int length) Retrieves a copy of the specified substring in theCLOB
value designated by thisClob
object.long
length()
Retrieves the number of characters in theCLOB
value designated 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
.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.
-
Constructor Details
-
jdbcClob
Constructs a new 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 extenal 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:
SQLException
- if the argument is null
-
-
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
value- Since:
- JDK 1.2, HSQLDB 1.7.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.HSQLDB-Specific Information:
The official specification above is ambiguous in that it does not precisely indicate the policy to be observed when pos > this.length() - length. One policy would be to retrieve the characters from pos to this.length(). Another would be to throw an exception. HSQLDB observes the later policy.
- 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- 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- Since:
- JDK 1.2, HSQLDB 1.7.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
value- Since:
- JDK 1.2, HSQLDB 1.7.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
value- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
-
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- Since:
- JDK 1.2, HSQLDB 1.7.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:
searchstr
- 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- Since:
- JDK 1.2, HSQLDB 1.7.2
-
setString
Writes the given JavaString
to theCLOB
value that thisClob
object designates at the positionpos
.HSQLDB-Specific Information:
HSLQDB 1.7.2 does not support this feature.
Calling this method always throws an
SQLException
.- Specified by:
setString
in interfaceClob
- Parameters:
pos
- the position at which to start writing to theCLOB
value that thisClob
object representsstr
- 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- Since:
- JDK 1.4, HSQLDB 1.7.2
-
setString
Writeslen
characters ofstr
, starting at characteroffset
, to theCLOB
value that thisClob
represents.HSQLDB-Specific Information:
HSLQDB 1.7.2 does not support this feature.
Calling this method always throws an
SQLException
.- Specified by:
setString
in interfaceClob
- Parameters:
pos
- the position at which to start writing to thisCLOB
objectstr
- 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- Since:
- JDK 1.4, HSQLDB 1.7.2
-
setAsciiStream
Retrieves a stream to be used to write Ascii characters to theCLOB
value that thisClob
object represents, starting at positionpos
.HSQLDB-Specific Information:
HSLQDB 1.7.2 does not support this feature.
Calling this method always throws an
SQLException
.- Specified by:
setAsciiStream
in interfaceClob
- Parameters:
pos
- the position at which to start writing to thisCLOB
object- Returns:
- the stream to which ASCII encoded characters can be written
- Throws:
SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- 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
.HSQLDB-Specific Information:
HSLQDB 1.7.2 does not support this feature.
Calling this method always throws an
SQLException
.- Specified by:
setCharacterStream
in interfaceClob
- Parameters:
pos
- the position at which to start writing to theCLOB
value- Returns:
- a stream to which Unicode encoded characters can be written
- Throws:
SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
-
truncate
Truncates theCLOB
value that thisClob
designates to have a length oflen
characters.HSQLDB-Specific Information:
This operation affects only the client-side value; it has no effect upon the value as it is stored in the database.
- Specified by:
truncate
in interfaceClob
- Parameters:
len
- the length, in bytes, to which theCLOB
value should be truncated- Throws:
SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
-
free
- Specified by:
free
in interfaceClob
- Throws:
SQLException
-
getCharacterStream
- Specified by:
getCharacterStream
in interfaceClob
- Throws:
SQLException
-