Interface Clob
- All Known Subinterfaces:
NClob
- All Known Implementing Classes:
SerialClob
public interface Clob
The mapping in the Java™ programming language for the SQL 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 ResultSet
, CallableStatement
, and PreparedStatement
, 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.
- Since:
- 1.2
Method Summary
Modifier and Type | Method | Description |
---|---|---|
void | free() | This method releases the resources that the |
InputStream | getAsciiStream() | Retrieves the |
Reader | getCharacterStream() | Retrieves the |
Reader | getCharacterStream(long pos,
long length) | Returns a |
String | getSubString(long pos,
int length) | Retrieves a copy of the specified substring in the |
long | length() | Retrieves the number of characters in the |
long | position(String searchstr,
long start) | Retrieves the character position at which the specified substring |
long | position(Clob searchstr,
long start) | Retrieves the character position at which the specified |
OutputStream | setAsciiStream(long pos) | Retrieves a stream to be used to write Ascii characters to the |
Writer | setCharacterStream(long pos) | Retrieves a stream to be used to write a stream of Unicode characters to the |
int | setString(long pos,
String str) | Writes the given Java |
int | setString(long pos,
String str,
int offset,
int len) | Writes |
void | truncate(long len) | Truncates the |
Method Detail
length
long length() throws SQLException
Retrieves the number of characters in the CLOB
value designated by this Clob
object.
- Returns:
- length of the
CLOB
in characters - Throws:
-
SQLException
- if there is an error accessing the length of theCLOB
value -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.2
getSubString
String getSubString(long pos, int length) throws SQLException
Retrieves a copy of the specified substring in the CLOB
value designated by this Clob
object. The substring begins at position pos
and has up to length
consecutive characters.
- 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 0 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.2
getCharacterStream
Reader getCharacterStream() throws SQLException
Retrieves the CLOB
value designated by this Clob
object as a java.io.Reader
object (or as a stream of characters).
- Returns:
- a
java.io.Reader
object containing theCLOB
data - Throws:
-
SQLException
- if there is an error accessing theCLOB
value -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.2
- See Also:
setCharacterStream(long)
getAsciiStream
InputStream getAsciiStream() throws SQLException
Retrieves the CLOB
value designated by this Clob
object as an ascii stream.
- Returns:
- a
java.io.InputStream
object containing theCLOB
data - Throws:
-
SQLException
- if there is an error accessing theCLOB
value -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.2
- See Also:
setAsciiStream(long)
position
long position(String searchstr, long start) throws SQLException
Retrieves the character position at which the specified substring searchstr
appears in the SQL CLOB
value represented by this Clob
object. The search begins at position start
.
- Parameters:
-
searchstr
- the substring for which to search -
start
- 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 1 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.2
position
long position(Clob searchstr, long start) throws SQLException
Retrieves the character position at which the specified Clob
object searchstr
appears in this Clob
object. The search begins at position start
.
- Parameters:
-
searchstr
- theClob
object for which to search -
start
- 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 1 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.2
setString
int setString(long pos, String str) throws SQLException
Writes the given Java String
to the CLOB
value that this Clob
object designates at the position pos
. The string will overwrite the existing characters in the Clob
object starting at the position pos
. If the end of the Clob
value is reached while writing the given string, then the length of the Clob
value will be increased to accommodate the extra characters.
Note: If the value specified for pos
is greater than the length+1 of the CLOB
value then the behavior is undefined. Some JDBC drivers may throw an SQLException
while other drivers may support this operation.
- Parameters:
-
pos
- the position at which to start writing to theCLOB
value that thisClob
object represents; the first position is 1. -
str
- 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 1 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.4
setString
int setString(long pos, String str, int offset, int len) throws SQLException
Writes len
characters of str
, starting at character offset
, to the CLOB
value that this Clob
represents. The string will overwrite the existing characters in the Clob
object starting at the position pos
. If the end of the Clob
value is reached while writing the given string, then the length of the Clob
value will be increased to accommodate the extra characters.
Note: If the value specified for pos
is greater than the length+1 of the CLOB
value then the behavior is undefined. Some JDBC drivers may throw an SQLException
while other drivers may support this operation.
- Parameters:
-
pos
- the position at which to start writing to thisCLOB
object; The first position is 1 -
str
- the string to be written to theCLOB
value that thisClob
object represents -
offset
- the offset intostr
to start reading the characters to be written -
len
- 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 1 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.4
setAsciiStream
OutputStream setAsciiStream(long pos) throws SQLException
Retrieves a stream to be used to write Ascii characters to the CLOB
value that this Clob
object represents, starting at position pos
. Characters written to the stream will overwrite the existing characters in the Clob
object starting at the position pos
. If the end of the Clob
value is reached while writing characters to the stream, then the length of the Clob
value will be increased to accommodate the extra characters.
Note: If the value specified for pos
is greater than the length+1 of the CLOB
value then the behavior is undefined. Some JDBC drivers may throw an SQLException
while other drivers may support this operation.
- 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 1 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.4
- See Also:
getAsciiStream()
setCharacterStream
Writer setCharacterStream(long pos) throws SQLException
Retrieves a stream to be used to write a stream of Unicode characters to the CLOB
value that this Clob
object represents, at position pos
. Characters written to the stream will overwrite the existing characters in the Clob
object starting at the position pos
. If the end of the Clob
value is reached while writing characters to the stream, then the length of the Clob
value will be increased to accommodate the extra characters.
Note: If the value specified for pos
is greater than the length+1 of the CLOB
value then the behavior is undefined. Some JDBC drivers may throw an SQLException
while other drivers may support this operation.
- 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 1 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.4
- See Also:
getCharacterStream()
truncate
void truncate(long len) throws SQLException
Truncates the CLOB
value that this Clob
designates to have a length of len
characters.
Note: If the value specified for pos
is greater than the length+1 of the CLOB
value then the behavior is undefined. Some JDBC drivers may throw an SQLException
while other drivers may support this operation.
- 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 0 -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.4
free
void free() throws SQLException
This method releases the resources that the Clob
object holds. The object is invalid once the free
method is called.
After free
has been called, any attempt to invoke a method other than free
will result in a SQLException
being thrown. If free
is called multiple times, the subsequent calls to free
are treated as a no-op.
- Throws:
-
SQLException
- if an error occurs releasing the Clob's resources -
SQLFeatureNotSupportedException
- if the JDBC driver does not support this method - Since:
- 1.6
getCharacterStream
Reader getCharacterStream(long pos, long length) throws SQLException
Returns a Reader
object that contains a partial Clob
value, starting with the character specified by pos, which is length characters in length.
- 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