# 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 `Clob` object holds.
`InputStream`
`getAsciiStream()`
Retrieves the `CLOB` value designated by this `Clob` object as an ascii stream.
`Reader`
`getCharacterStream()`
Retrieves the `CLOB` value designated by this `Clob` object as a `java.io.Reader` object (or as a stream of characters).
`Reader`
`getCharacterStream(long pos, long length)`
Returns a `Reader` object that contains a partial `Clob` value, starting with the character specified by pos, which is length characters in length.
`String`
`getSubString(long pos, int length)`
Retrieves a copy of the specified substring in the `CLOB` value designated by this `Clob` object.
`long`
`length()`
Retrieves the number of characters in the `CLOB` value designated by this `Clob` object.
`long`
`position(String searchstr, long start)`
Retrieves the character position at which the specified substring `searchstr` appears in the SQL `CLOB` value represented by this `Clob` object.
`long`
`position(Clob searchstr, long start)`
Retrieves the character position at which the specified `Clob` object `searchstr` appears in this `Clob` object.
`OutputStream`
`setAsciiStream(long pos)`
Retrieves a stream to be used to write Ascii characters to the `CLOB` value that this `Clob` object represents, starting at position `pos`.
`Writer`
`setCharacterStream(long pos)`
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`.
`int`
`setString(long pos, String str)`
Writes the given Java `String` to the `CLOB` value that this `Clob` object designates at the position `pos`.
`int`
`setString(long pos, String str, int offset, int len)`
Writes `len` characters of `str`, starting at character `offset`, to the `CLOB` value that this `Clob` represents.
`void`
`truncate(long len)`
Truncates the `CLOB` value that this `Clob` designates to have a length of `len` characters.

## Method Details

### 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 the `CLOB` 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 the `CLOB` value designated by this `Clob` object
Throws:
  `SQLException` - if there is an error accessing the `CLOB` 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 the `CLOB` data
Throws:
  `SQLException` - if there is an error accessing the `CLOB` 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 the `CLOB` data
Throws:
  `SQLException` - if there is an error accessing the `CLOB` 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 the `CLOB` 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` - the `Clob` 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 the `CLOB` 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 the `CLOB` value that this `Clob` object represents; the first position is 1.
  `str` - the string to be written to the `CLOB` value that this `Clob` designates
Returns:
  the number of characters written
Throws:
  `SQLException` - if there is an error accessing the `CLOB` 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 this `CLOB` object; The first position is 1
  `str` - the string to be written to the `CLOB` value that this `Clob` object represents
  `offset` - the offset into `str` 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 the `CLOB` 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 this `CLOB` 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 the `CLOB` 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 the `CLOB` 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 the `CLOB` 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 the `CLOB` value should be truncated
Throws:
  `SQLException` - if there is an error accessing the `CLOB` 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 partial `Clob` value can be read.
Throws:
  `SQLException` - if pos is less than 1; or if pos is greater than the number of characters in the `Clob`; or if pos + length is greater than the number of characters in the `Clob`
  `SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
Since:
  1.6