# Clob

public interface **Clob**

|---|---|---|
| Known Indirect Subclasses [NClob](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/NClob.html) |---|---| | [NClob](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/NClob.html) | The mapping in the Java^TM^ programming language for the SQL `NCLOB` type. | |||

The mapping in the Java^TM^ 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 `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/ResultSet.html`,
`https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/CallableStatement.html`, and `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/PreparedStatement.html`, 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.

### Public Method Summary

|---|---|
| abstract void | [free](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#free())() This method frees the `Clob` object and releases the resources the resources that it holds. |
| abstract [InputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/InputStream.html) | [getAsciiStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#getAsciiStream())() Retrieves the `CLOB` value designated by this `Clob` object as an ascii stream. |
| abstract [Reader](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/Reader.html) | [getCharacterStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#getCharacterStream())() Retrieves the `CLOB` value designated by this `Clob` object as a `java.io.Reader` object (or as a stream of characters). |
| abstract [Reader](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/Reader.html) | [getCharacterStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#getCharacterStream(long,%20long))(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. |
| abstract [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [getSubString](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#getSubString(long,%20int))(long pos, int length) Retrieves a copy of the specified substring in the `CLOB` value designated by this `Clob` object. |
| abstract long | [length](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#length())() Retrieves the number of characters in the `CLOB` value designated by this `Clob` object. |
| abstract long | [position](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#position(java.lang.String,%20long))([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) searchstr, long start) Retrieves the character position at which the specified substring `searchstr` appears in the SQL `CLOB` value represented by this `Clob` object. |
| abstract long | [position](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#position(java.sql.Clob,%20long))([Clob](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html) searchstr, long start) Retrieves the character position at which the specified `Clob` object `searchstr` appears in this `Clob` object. |
| abstract [OutputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/OutputStream.html) | [setAsciiStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#setAsciiStream(long))(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`. |
| abstract [Writer](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/Writer.html) | [setCharacterStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#setCharacterStream(long))(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`. |
| abstract int | [setString](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#setString(long,%20java.lang.String,%20int,%20int))(long pos, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) str, int offset, int len) Writes `len` characters of `str`, starting at character `offset`, to the `CLOB` value that this `Clob` represents. |
| abstract int | [setString](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#setString(long,%20java.lang.String))(long pos, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) str) Writes the given Java `String` to the `CLOB` value that this `Clob` object designates at the position `pos`. |
| abstract void | [truncate](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#truncate(long))(long len) Truncates the `CLOB` value that this `Clob` designates to have a length of `len` characters. |

## Public Methods

#### public abstract void
**free**
()

This method frees the `Clob` object and releases the resources the resources
that it 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.

<br />

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if an error occurs releasing the Clob's resources |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract [InputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/InputStream.html)
**getAsciiStream**
()

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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#setAsciiStream(long)`

#### public abstract [Reader](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/Reader.html)
**getCharacterStream**
()

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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#setCharacterStream(long)`

#### public abstract [Reader](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/Reader.html)
**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.

##### 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)
**getSubString**
(long pos, int length)

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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value; if pos is less than 1 or length is less than 0 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract long
**length**
()

Retrieves the number of characters
in the `CLOB` value
designated by this `Clob` object.

##### Returns

- length of the `CLOB` in characters

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the length of the `CLOB` value |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract long
**position**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) searchstr, long start)

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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract long
**position**
([Clob](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html) searchstr, long start)

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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value or if start is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract [OutputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/OutputStream.html)
**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`. 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 accomodate the extra characters.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `CLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#getAsciiStream()`

#### public abstract [Writer](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/Writer.html)
**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`. 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 accomodate the extra characters.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `CLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Clob.html#getCharacterStream()`

#### public abstract int
**setString**
(long pos, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) str, int offset, int len)

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 accomodate the extra characters.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `CLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract int
**setString**
(long pos, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) str)

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 accomodate the extra characters.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `CLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract void
**truncate**
(long len)

Truncates the `CLOB` value that this `Clob`
designates to have a length of `len`
characters.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `CLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`SQLException` while other drivers may support this
operation.

##### Parameters

| len | the length, in characters, to which the `CLOB` value should be truncated |
|---|---|

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `CLOB` value or if len is less than 0 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|