Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.sql
Interface Clob

All Known Subinterfaces:
  NClob

All Known Implementing Classes:
  SerialClob

    public interface Clob

The mapping in the JavaTM 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
`void` | `free()` This method frees the `Clob` object and releases the resources the resources that it 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(Clob searchstr, long start)` Retrieves the character position at which the specified `Clob` object `searchstr` appears in 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.
`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 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` - 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 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` - 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 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` - 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 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` - 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 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` - 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 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.

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 1993, 2010, Oracle and/or its affiliates. All rights reserved.