Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.sql
Interface Clob

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.

Since:
  1.2

Method Summary
`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).
`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

    public 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
  Since:
    1.2

### getSubString

    public 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
  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
  Since:
    1.2

### getCharacterStream

    public 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
  Since:
    1.2
  See Also:
    `setCharacterStream(long)`

### getAsciiStream

    public 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
  Since:
    1.2
  See Also:
    `setAsciiStream(long)`

### position

    public 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
  Since:
    1.2

### position

    public 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
  Since:
    1.2

### setString

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

  Parameters:
    `pos` - the position at which to start writing to the `CLOB` value that this `Clob` object represents
    `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
  Since:
    1.4

### setString

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

  Parameters:
    `pos` - the position at which to start writing to this `CLOB` object
    `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
  Since:
    1.4

### setAsciiStream

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

  Parameters:
    `pos` - the position at which to start writing to this `CLOB` object
  Returns:
    the stream to which ASCII encoded characters can be written
  Throws:
    `SQLException` - if there is an error accessing the `CLOB` value
  Since:
    1.4
  See Also:
    `getAsciiStream()`

### setCharacterStream

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

  Parameters:
    `pos` - the position at which to start writing to the `CLOB` value
  Returns:
    a stream to which Unicode encoded characters can be written
  Throws:
    `SQLException` - if there is an error accessing the `CLOB` value
  Since:
    1.4
  See Also:
    `getCharacterStream()`

### truncate

    public void truncate(long len)
                  throws SQLException

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

  Parameters:
    `len` - the length, in bytes, to which the `CLOB` value should be truncated
  Throws:
    `SQLException` - if there is an error accessing the `CLOB` value
  Since:
    1.4

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
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 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.