-
- All Known Subinterfaces:
NClob
- All Known Implementing Classes:
SerialClob
public interface ClobThe mapping in the Java™ programming language for the SQLCLOBtype. An SQLCLOBis 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 aClobobject using an SQLlocator(CLOB), which means that aClobobject contains a logical pointer to the SQLCLOBdata rather than the data itself. AClobobject is valid for the duration of the transaction in which it was created.The
Clobinterface provides methods for getting the length of an SQLCLOB(Character Large Object) value, for materializing aCLOBvalue on the client, and for searching for a substring orCLOBobject within aCLOBvalue. Methods in the interfacesResultSet,CallableStatement, andPreparedStatement, such asgetClobandsetCloballow a programmer to access an SQLCLOBvalue. In addition, this interface has methods for updating aCLOBvalue.All methods on the
Clobinterface must be fully implemented if the JDBC driver supports the data type.- Since:
- 1.2
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidfree()This method releases the resources that theClobobject holds.InputStreamgetAsciiStream()Retrieves theCLOBvalue designated by thisClobobject as an ascii stream.ReadergetCharacterStream()Retrieves theCLOBvalue designated by thisClobobject as ajava.io.Readerobject (or as a stream of characters).ReadergetCharacterStream(long pos, long length)Returns aReaderobject that contains a partialClobvalue, starting with the character specified by pos, which is length characters in length.StringgetSubString(long pos, int length)Retrieves a copy of the specified substring in theCLOBvalue designated by thisClobobject.longlength()Retrieves the number of characters in theCLOBvalue designated by thisClobobject.longposition(String searchstr, long start)Retrieves the character position at which the specified substringsearchstrappears in the SQLCLOBvalue represented by thisClobobject.longposition(Clob searchstr, long start)Retrieves the character position at which the specifiedClobobjectsearchstrappears in thisClobobject.OutputStreamsetAsciiStream(long pos)Retrieves a stream to be used to write Ascii characters to theCLOBvalue that thisClobobject represents, starting at positionpos.WritersetCharacterStream(long pos)Retrieves a stream to be used to write a stream of Unicode characters to theCLOBvalue that thisClobobject represents, at positionpos.intsetString(long pos, String str)Writes the given JavaStringto theCLOBvalue that thisClobobject designates at the positionpos.intsetString(long pos, String str, int offset, int len)Writeslencharacters ofstr, starting at characteroffset, to theCLOBvalue that thisClobrepresents.voidtruncate(long len)Truncates theCLOBvalue that thisClobdesignates to have a length oflencharacters.
-
-
-
Method Detail
-
length
long length() throws SQLExceptionRetrieves the number of characters in theCLOBvalue designated by thisClobobject.- Returns:
- length of the
CLOBin characters - Throws:
SQLException- if there is an error accessing the length of theCLOBvalueSQLFeatureNotSupportedException- 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 theCLOBvalue designated by thisClobobject. The substring begins at positionposand has up tolengthconsecutive 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
Stringthat is the specified substring in theCLOBvalue designated by thisClobobject - Throws:
SQLException- if there is an error accessing theCLOBvalue; if pos is less than 1 or length is less than 0SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
-
getCharacterStream
Reader getCharacterStream() throws SQLException
Retrieves theCLOBvalue designated by thisClobobject as ajava.io.Readerobject (or as a stream of characters).- Returns:
- a
java.io.Readerobject containing theCLOBdata - Throws:
SQLException- if there is an error accessing theCLOBvalueSQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
- See Also:
setCharacterStream(long)
-
getAsciiStream
InputStream getAsciiStream() throws SQLException
Retrieves theCLOBvalue designated by thisClobobject as an ascii stream.- Returns:
- a
java.io.InputStreamobject containing theCLOBdata - Throws:
SQLException- if there is an error accessing theCLOBvalueSQLFeatureNotSupportedException- 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 substringsearchstrappears in the SQLCLOBvalue represented by thisClobobject. The search begins at positionstart.- 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 theCLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- 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 specifiedClobobjectsearchstrappears in thisClobobject. The search begins at positionstart.- Parameters:
searchstr- theClobobject for which to searchstart- the position at which to begin searching; the first position is 1- Returns:
- the position at which the
Clobobject appears or -1 if it is not present; the first position is 1 - Throws:
SQLException- if there is an error accessing theCLOBvalue or if start is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.2
-
setString
int setString(long pos, String str) throws SQLExceptionWrites the given JavaStringto theCLOBvalue that thisClobobject designates at the positionpos. The string will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing the given string, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
pos- the position at which to start writing to theCLOBvalue that thisClobobject represents; the first position is 1.str- the string to be written to theCLOBvalue that thisClobdesignates- Returns:
- the number of characters written
- Throws:
SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.4
-
setString
int setString(long pos, String str, int offset, int len) throws SQLExceptionWriteslencharacters ofstr, starting at characteroffset, to theCLOBvalue that thisClobrepresents. The string will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing the given string, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
pos- the position at which to start writing to thisCLOBobject; The first position is 1str- the string to be written to theCLOBvalue that thisClobobject representsoffset- the offset intostrto 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 theCLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- 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 theCLOBvalue that thisClobobject represents, starting at positionpos. Characters written to the stream will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing characters to the stream, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
pos- the position at which to start writing to thisCLOBobject; The first position is 1- Returns:
- the stream to which ASCII encoded characters can be written
- Throws:
SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- 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 theCLOBvalue that thisClobobject represents, at positionpos. Characters written to the stream will overwrite the existing characters in theClobobject starting at the positionpos. If the end of theClobvalue is reached while writing characters to the stream, then the length of theClobvalue will be increased to accommodate the extra characters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
pos- the position at which to start writing to theCLOBvalue; The first position is 1- Returns:
- a stream to which Unicode encoded characters can be written
- Throws:
SQLException- if there is an error accessing theCLOBvalue or if pos is less than 1SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.4
- See Also:
getCharacterStream()
-
truncate
void truncate(long len) throws SQLExceptionTruncates theCLOBvalue that thisClobdesignates to have a length oflencharacters.Note: If the value specified for
posis greater than the length+1 of theCLOBvalue then the behavior is undefined. Some JDBC drivers may throw anSQLExceptionwhile other drivers may support this operation.- Parameters:
len- the length, in characters, to which theCLOBvalue should be truncated- Throws:
SQLException- if there is an error accessing theCLOBvalue or if len is less than 0SQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.4
-
free
void free() throws SQLException
This method releases the resources that theClobobject holds. The object is invalid once thefreemethod is called.After
freehas been called, any attempt to invoke a method other thanfreewill result in aSQLExceptionbeing thrown. Iffreeis called multiple times, the subsequent calls tofreeare treated as a no-op.- Throws:
SQLException- if an error occurs releasing the Clob's resourcesSQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.6
-
getCharacterStream
Reader getCharacterStream(long pos, long length) throws SQLException
Returns aReaderobject that contains a partialClobvalue, 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:
Readerthrough which the partialClobvalue 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 theClobSQLFeatureNotSupportedException- if the JDBC driver does not support this method- Since:
- 1.6
-
-