Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Methods](https://developer.android.com/reference/java/sql/Clob#pubmethods)

# Clob

` public interface Clob `   
` `

|---|
| java.sql.Clob |

Known indirect subclasses [NClob](https://developer.android.com/reference/java/sql/NClob) [NClob](https://developer.android.com/reference/java/sql/NClob) 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://developer.android.com/reference/java/sql/ResultSet`, `https://developer.android.com/reference/java/sql/CallableStatement`, and `https://developer.android.com/reference/java/sql/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.

## Summary

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

## Public methods

### free

Added in [API level 9](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 />

<br />

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if an error occurs releasing the Clob's resources |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### getAsciiStream

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract InputStream getAsciiStream ()
```

Retrieves the `CLOB` value designated by this `Clob` object as an ascii stream.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/InputStream` | a `java.io.InputStream` object containing the `CLOB` data <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Clob#setAsciiStream(long)`

### getCharacterStream

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract Reader getCharacterStream ()
```

Retrieves the `CLOB` value designated by this `Clob` object as a `java.io.Reader` object (or as a stream of characters).

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/Reader` | a `java.io.Reader` object containing the `CLOB` data <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Clob#setCharacterStream(long)`

### getCharacterStream

Added in [API level 9](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the offset to the first character of the partial value to be retrieved. The first character in the Clob is at position 1. <br /> |
| `length` | `long`: the length in characters of the partial value to be retrieved. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/Reader` | `Reader` through which the partial `Clob` value can be read. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/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` |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### getSubString

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract String 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the first character of the substring to be extracted. The first character is at position 1. <br /> |
| `length` | `int`: the number of consecutive characters to be copied; the value for length must be 0 or greater <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/String` | a `String` that is the specified substring in the `CLOB` value designated by this `Clob` object <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value; if pos is less than 1 or length is less than 0 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### length

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract long length ()
```

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

<br />

| Returns ||
|---|---|
| `long` | length of the `CLOB` in characters <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the length of the `CLOB` value |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### position

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract 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. The search begins at position `start`.

<br />

| Parameters ||
|---|---|
| `searchstr` | `String`: the substring for which to search <br /> |
| `start` | `long`: the position at which to begin searching; the first position is 1 <br /> |

| Returns ||
|---|---|
| `long` | the position at which the substring appears or -1 if it is not present; the first position is 1 <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### position

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract long position (Clob 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`.

<br />

| Parameters ||
|---|---|
| `searchstr` | `Clob`: the `Clob` object for which to search <br /> |
| `start` | `long`: the position at which to begin searching; the first position is 1 <br /> |

| Returns ||
|---|---|
| `long` | the position at which the `Clob` object appears or -1 if it is not present; the first position is 1 <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value or if start is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### setAsciiStream

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract 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`. 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the position at which to start writing to this `CLOB` object; The first position is 1 <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/OutputStream` | the stream to which ASCII encoded characters can be written <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Clob#getAsciiStream()`

### setCharacterStream

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract 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`. 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the position at which to start writing to the `CLOB` value; The first position is 1 <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/Writer` | a stream to which Unicode encoded characters can be written <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Clob#getCharacterStream()`

### setString

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract 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. 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the position at which to start writing to this `CLOB` object; The first position is 1 <br /> |
| `str` | `String`: the string to be written to the `CLOB` value that this `Clob` object represents <br /> |
| `offset` | `int`: the offset into `str` to start reading the characters to be written <br /> |
| `len` | `int`: the number of characters to be written <br /> |

| Returns ||
|---|---|
| `int` | the number of characters written <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### setString

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract int setString (long pos, 
                String 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the position at which to start writing to the `CLOB` value that this `Clob` object represents; The first position is 1 <br /> |
| `str` | `String`: the string to be written to the `CLOB` value that this `Clob` designates <br /> |

| Returns ||
|---|---|
| `int` | the number of characters written <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### truncate

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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.

<br />

| Parameters ||
|---|---|
| `len` | `long`: the length, in characters, to which the `CLOB` value should be truncated <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `CLOB` value or if len is less than 0 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |