Class jdbcClob
- java.lang.Object
-
- org.hsqldb.jdbc.jdbcClob
-
- All Implemented Interfaces:
java.sql.Clob
public final class jdbcClob extends java.lang.Object implements java.sql.Clob
The mapping in the JavaTM programming language for the SQL CLOB type.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 Constructor Description jdbcClob(java.lang.String data)
Constructs a new jdbcClob object wrapping the given character sequence.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
free()
java.io.InputStream
getAsciiStream()
Retrieves theCLOB
value designated by thisClob
object as an ascii stream.java.io.Reader
getCharacterStream()
Retrieves theCLOB
value designated by thisClob
object as ajava.io.Reader
object (or as a stream of characters).java.io.Reader
getCharacterStream(long pos, long length)
java.lang.String
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
position(java.lang.String searchstr, long start)
Retrieves the character position at which the specified substringsearchstr
appears in the SQLCLOB
value represented by thisClob
object.long
position(java.sql.Clob searchstr, long start)
Retrieves the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object.java.io.OutputStream
setAsciiStream(long pos)
Retrieves a stream to be used to write Ascii characters to theCLOB
value that thisClob
object represents, starting at positionpos
.java.io.Writer
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
setString(long pos, java.lang.String str)
Writes the given JavaString
to theCLOB
value that thisClob
object designates at the positionpos
.int
setString(long pos, java.lang.String str, int offset, int len)
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 Detail
-
jdbcClob
public jdbcClob(java.lang.String data) throws java.sql.SQLException
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:
java.sql.SQLException
- if the argument is null
-
-
Method Detail
-
length
public long length() throws java.sql.SQLException
Retrieves the number of characters in theCLOB
value designated by thisClob
object.- Specified by:
length
in interfacejava.sql.Clob
- Returns:
- length of the
CLOB
in characters - Throws:
java.sql.SQLException
- if there is an error accessing the length of theCLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
-
getSubString
public java.lang.String getSubString(long pos, int length) throws java.sql.SQLException
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 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- Returns:
- a
String
that is the specified substring in theCLOB
value designated by thisClob
object - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
-
getCharacterStream
public java.io.Reader getCharacterStream() throws java.sql.SQLException
Retrieves theCLOB
value designated by thisClob
object as ajava.io.Reader
object (or as a stream of characters).- Specified by:
getCharacterStream
in interfacejava.sql.Clob
- Returns:
- a
java.io.Reader
object containing theCLOB
data - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
- See Also:
setCharacterStream(long)
-
getAsciiStream
public java.io.InputStream getAsciiStream() throws java.sql.SQLException
Retrieves theCLOB
value designated by thisClob
object as an ascii stream.- Specified by:
getAsciiStream
in interfacejava.sql.Clob
- Returns:
- a
java.io.InputStream
object containing theCLOB
data - Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value- 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.SQLException
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 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 theCLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
-
position
public long position(java.sql.Clob searchstr, long start) throws java.sql.SQLException
Retrieves the character position at which the specifiedClob
objectsearchstr
appears in thisClob
object. The search begins at positionstart
.- Specified by:
position
in interfacejava.sql.Clob
- 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:
java.sql.SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.2, HSQLDB 1.7.2
-
setString
public int setString(long pos, java.lang.String str) throws java.sql.SQLException
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 interfacejava.sql.Clob
- 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:
java.sql.SQLException
- if there is an error accessing theCLOB
value- 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.SQLException
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 interfacejava.sql.Clob
- 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:
java.sql.SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
-
setAsciiStream
public java.io.OutputStream setAsciiStream(long pos) throws java.sql.SQLException
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 interfacejava.sql.Clob
- Parameters:
pos
- the position at which to start writing to thisCLOB
object- Returns:
- the stream to which ASCII encoded characters can be written
- Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
getAsciiStream()
-
setCharacterStream
public java.io.Writer setCharacterStream(long pos) throws java.sql.SQLException
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 interfacejava.sql.Clob
- Parameters:
pos
- the position at which to start writing to theCLOB
value- Returns:
- a stream to which Unicode encoded characters can be written
- Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
- See Also:
getCharacterStream()
-
truncate
public void truncate(long len) throws java.sql.SQLException
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 interfacejava.sql.Clob
- Parameters:
len
- the length, in bytes, to which theCLOB
value should be truncated- Throws:
java.sql.SQLException
- if there is an error accessing theCLOB
value- Since:
- JDK 1.4, HSQLDB 1.7.2
-
free
public void free() throws java.sql.SQLException
- Specified by:
free
in interfacejava.sql.Clob
- Throws:
java.sql.SQLException
-
getCharacterStream
public java.io.Reader getCharacterStream(long pos, long length) throws java.sql.SQLException
- Specified by:
getCharacterStream
in interfacejava.sql.Clob
- Throws:
java.sql.SQLException
-
-