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 Detail

    - #### 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