![]() | Documentation Contents |
A Clob object represents the
Java programming language mapping of an SQL CLOB
(Character Large Object). 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. Methods in the interfaces
ResultSet, CallableStatement, and
PreparedStatement allow a programmer to access the
SQL3 type CLOB in the same way that more basic SQL
types are accessed. In other words, an application using the JDBC
2.0 API uses methods such as getClob and
setClob for a CLOB value the same way it
uses getInt and setInt for an
INTEGER value or getString and
setString for a CHAR or
VARCHAR value.
The default is for a JDBC driver to
implement the Clob interface using the SQL type
LOCATOR(CLOB) behind the scenes. A
LOCATOR(CLOB) designates an SQL CLOB
residing on a database server, and operations on the locator
achieve the same results as operations on the CLOB
itself. This means that a client can operate on a Clob
instance without ever having to materialize the CLOB
data on the client machine. The driver uses
LOCATOR(CLOB) behind the scenes, making its use
completely transparent to the JDBC programmer.
The standard behavior for a
Clob instance is to remain valid until the transaction
in which it was created is either committed or rolled back.
The interface Clob provides
methods for getting the length of an SQL CLOB value,
for materializing the data in a CLOB value on the
client, and for searching for a substring or CLOB
object within a CLOB value.
The following code fragment illustrates
creating a Clob object, where rs is a
ResultSet object:
Clob clob = rs.getClob(1);
The variable clob can now be
used to operate on the CLOB value that is stored in
the first column of the result set rs.
Programmers can invoke methods in the JDBC
API on a Clob object as if they were operating on the
SQL CLOB value it designates. However, if they want to
operate on a Clob object as an object in the Java
programming language, they must first materialize the data of the
CLOB object on the client. The Clob
interface provides three methods for materializing a
Clob object as an object in the Java programming
language:
Clob notes = rs.getClob("NOTES");
java.io.InputStream in = notes.getAsciiStream();
byte b = in.read();
// in contains the characters in the CLOB value designated by
// notes as Ascii bytes; b contains the first character as an Ascii
// byte
java.io.Reader reader = notes.getCharacterStream(); int c = Reader.read(); // c contains the first character in the CLOB that notes designates
String substring = notes.getSubString(10, 5); // substring contains five characters, starting with the tenth // character of the CLOB value that notes designates long len = notes.length(); String substring = notes.getSubString(1, len); // substring contains all of the characters in the CLOB object that // notes designates
To store a Clob object in the
database, it is passed as a parameter to the
PreparedStatement method setClob. For
example, the following code fragment stores the Clob
object notes by passing it as the first input
parameter to the PreparedStatement object
pstmt:
Clob notes = rs.getClob("NOTES");
PreparedStatement pstmt = con.prepareStatement(
"UPDATE SALES_STATS SET COMMENTS = ? WHERE SALES > 500000");
pstmt.setClob(1, notes);
pstmt.executeUpdate();
The CLOB value designated by
notes is now stored in the table
SALES_STATS in column COMMENTS in every
row where the value in the column SALES is greater
than 500000.
package java.sql;
public interface java.sql.Clob {
long length() throws SQLException;
InputStream getAsciiStream() throws SQLException;
Reader getCharacterStream() throws SQLException;
String getSubString(long pos, int length) throws SQLException;
long position(String searchstr, long start) throws SQLException;
long position(Clob searchstr, long start) throws SQLException;
}
InputStream getAsciiStream() throws SQLException
Materializes theCLOBvalue designated by thisClobobject as a stream of Ascii bytes.an
InputStreamobject with all the data in theCLOBvalue designated by thisClobobject as Ascii bytesjava.io.InputStream in = clob.getAsciiStream(); byte b = in.read(); // in has all of the characters in the CLOB value designated by // clob as Ascii bytes; b designates the first character as an Ascii // byte
Reader getCharacterStream() throws SQLException
Materializes theCLOBvalue designated by thisClobobject as a stream of Unicode characters.a
Readerobject with all the data in theCLOBvalue designated by thisClobobject as Unicode charactersReader read = clob.getCharacterStream(); // read has all the data in the CLOB value designated by clob // as Unicode characters
length getSubString(long pos, int length) throws SQLException
Returns a copy of the portion of theCLOBvalue represented by thisClobobject that starts at positionposand has up tolengthconsecutive characters.
pos the position of the first charto extract from theCLOBvalue designated by thisClobobject; the initial position is1length the number of consecutive characters to be copied a
Stringobject containing a copy of up tolengthconsecutive characters from theCLOBvalue represented by thisClobobject, starting with thecharat positionposString substr = clob.getSubString(1, 100); // substr contains the first 100 characters in the CLOB value // designated by clob (those in positions 1 through 100, inclusive)
long length() throws SQLExceptions
Returns the number of characters in theCLOBvalue designated by thisClobobject.the length in characters of the
CLOBvalue that thisClobobject representsClob clob = rs.getClob(3); long len = clob.length(); // len contains the number of characters in the CLOB value // designated by clob
long position(Clob searchstr, long start) throws SQLException
Determines the character position at which theClobobjectsearchstrbegins within theCLOBvalue that thisClobobject represents. The search begins at positionstart.
searchstr the Clobobject for which to searchstart the position at which to begin searching; the first character is at position 1the position at which the
Clobobjectsearchstrbegins, which will bestartor larger if the search, starting at positionstart, is successful;-1otherwiseClob clob2 = rs.getClob(4); long beginning = clob.position(clob2, 1024); // if clob2 is contained in clob starting at position 1024 or later, // beginning will contain the position at which clob2 begins
long position(String searchstr, long start) throws SQLException
Determines the position at which theStringsearchstrbegins within theCLOBvalue that thisClobobject represents. The search begins at positionstart.
searchstr the string for which to search start the position at which to begin searching; the first character is at position 1the position at which the
Stringobjectsearchstrbegins, which will bestartor larger if the search, starting at positionstart, is successful;-1otherwiseString searchstr= clob.getSubString(5, 100); long beginning = clob.position(searchstr, 1024); // if searchstr is contained in clob from position 1024 on, beginning // will contain the position at which searchstr begins
Copyright © 1993, 2010, Oracle and/or its affiliates. All rights reserved. Please send comments using this Feedback page. |
Java Technology |