Module java.sql
Package java.sql

# 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