## org.hsqldb.jdbc
Class jdbcClob

    java.lang.Object
      org.hsqldb.jdbc.jdbcClob

All Implemented Interfaces:
  java.sql.Clob

public final class jdbcClob
extends java.lang.Object
implements java.sql.Clob

The mapping in the JavaTM programming language for the SQL CLOB type.

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.

### HSQLDB-Specific Information:

Including 1.8.x, the HSQLDB driver does not implement Clob using an SQL locator(CLOB). That is, an HSQLDB Clob object does not contain a logical pointer to SQL CLOB data; rather it directly contains an immutable representation of the data (a String object). As a result, an HSQLDB Clob object itself is valid beyond the duration of the transaction in which is was created, although it does not necessarily represent a corresponding value on the database.

Currently, the interface methods for updating a CLOB value are unsupported. However, the truncate method is supported for local use.

Since:
  JDK 1.2, HSQLDB 1.7.2
Author:
  boucherb@users

Constructor Summary
`jdbcClob(java.lang.String data)` Constructs a new jdbcClob object wrapping the given character sequence.

Method Summary
`java.io.InputStream` `getAsciiStream()` Retrieves the `CLOB` value designated by this `Clob` object as an ascii stream.
`java.io.Reader` `getCharacterStream()` Retrieves the `CLOB` value designated by this `Clob` object as a `java.io.Reader` object (or as a stream of characters).
`java.lang.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(java.sql.Clob searchstr, long start)` Retrieves the character position at which the specified `Clob` object `searchstr` appears in this `Clob` object.
`long` `position(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.
`java.io.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`.
`java.io.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, java.lang.String str)` Writes the given Java `String` to the `CLOB` value that this `Clob` object designates at the position `pos`.
`int` `setString(long pos, 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.
`void` `truncate(long len)` Truncates the `CLOB` value that this `Clob` designates to have a length of `len` characters.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### jdbcClob

    public jdbcClob(java.lang.String data)
             throws java.sql.SQLException

  Constructs a new jdbcClob object wrapping the given character sequence.

  This constructor is used internally to retrieve result set values as Clob objects, yet it must be public to allow access from other packages. As such (in the interest of efficiency) this object maintains a reference to the given String object rather than making a copy and so it is gently suggested (in the interest of effective memory management) that extenal clients using this constructor either take pause to consider the implications or at least take care to provide a String object whose internal character buffer is not much larger than required to represent the value.

Parameters:
  `data` - the character sequence representing the Clob value
Throws:
  `java.sql.SQLException` - if the argument is null

Method Detail

### length

    public long length()
                throws java.sql.SQLException

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

  Specified by:
    `length` in interface `java.sql.Clob`
  Returns:
    length of the `CLOB` in characters
  Throws:
    `java.sql.SQLException` - if there is an error accessing the length of the `CLOB` value
  Since:
    JDK 1.2, HSQLDB 1.7.2

### getSubString

    public java.lang.String getSubString(long pos,
                                         int length)
                                  throws java.sql.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.

  ### HSQLDB-Specific Information:

  The official specification above is ambiguous in that it does not precisely indicate the policy to be observed when pos > this.length() - length. One policy would be to retrieve the characters from pos to this.length(). Another would be to throw an exception. HSQLDB observes the later policy.

  Specified by:
    `getSubString` in interface `java.sql.Clob`
  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:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.2, HSQLDB 1.7.2

### getCharacterStream

    public java.io.Reader getCharacterStream()
                                      throws java.sql.SQLException

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

  Specified by:
    `getCharacterStream` in interface `java.sql.Clob`
  Returns:
    a `java.io.Reader` object containing the `CLOB` data
  Throws:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.2, HSQLDB 1.7.2
  See Also:
    `setCharacterStream(long)`

### getAsciiStream

    public java.io.InputStream getAsciiStream()
                                       throws java.sql.SQLException

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

  Specified by:
    `getAsciiStream` in interface `java.sql.Clob`
  Returns:
    a `java.io.InputStream` object containing the `CLOB` data
  Throws:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.2, HSQLDB 1.7.2
  See Also:
    `setAsciiStream(long)`

### position

    public long position(java.lang.String searchstr,
                         long start)
                  throws java.sql.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`.

  Specified by:
    `position` in interface `java.sql.Clob`
  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:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.2, HSQLDB 1.7.2

### position

    public long position(java.sql.Clob searchstr,
                         long start)
                  throws java.sql.SQLException

  Retrieves the character position at which the specified `Clob` object `searchstr` appears in this `Clob` object. The search begins at position `start`.

  Specified by:
    `position` in interface `java.sql.Clob`
  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:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.2, HSQLDB 1.7.2

### setString

    public int setString(long pos,
                         java.lang.String str)
                  throws java.sql.SQLException

  Writes the given Java `String` to the `CLOB` value that this `Clob` object designates at the position `pos`.

  ### HSQLDB-Specific Information:

  HSLQDB 1.7.2 does not support this feature.

  Calling this method always throws an `SQLException`.

  Specified by:
    `setString` in interface `java.sql.Clob`
  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:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.4, HSQLDB 1.7.2

### setString

    public int setString(long pos,
                         java.lang.String str,
                         int offset,
                         int len)
                  throws java.sql.SQLException

  Writes `len` characters of `str`, starting at character `offset`, to the `CLOB` value that this `Clob` represents.

  ### HSQLDB-Specific Information:

  HSLQDB 1.7.2 does not support this feature.

  Calling this method always throws an `SQLException`.

  Specified by:
    `setString` in interface `java.sql.Clob`
  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:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.4, HSQLDB 1.7.2

### setAsciiStream

    public java.io.OutputStream setAsciiStream(long pos)
                                        throws java.sql.SQLException

  Retrieves a stream to be used to write Ascii characters to the `CLOB` value that this `Clob` object represents, starting at position `pos`.

  ### HSQLDB-Specific Information:

  HSLQDB 1.7.2 does not support this feature.

  Calling this method always throws an `SQLException`.

  Specified by:
    `setAsciiStream` in interface `java.sql.Clob`
  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:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.4, HSQLDB 1.7.2
  See Also:
    `getAsciiStream()`

### setCharacterStream

    public java.io.Writer setCharacterStream(long pos)
                                      throws java.sql.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`.

  ### HSQLDB-Specific Information:

  HSLQDB 1.7.2 does not support this feature.

  Calling this method always throws an `SQLException`.

  Specified by:
    `setCharacterStream` in interface `java.sql.Clob`
  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:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.4, HSQLDB 1.7.2
  See Also:
    `getCharacterStream()`

### truncate

    public void truncate(long len)
                  throws java.sql.SQLException

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

  ### HSQLDB-Specific Information:

  This operation affects only the client-side value; it has no effect upon the value as it is stored in the database.

  Specified by:
    `truncate` in interface `java.sql.Clob`
  Parameters:
    `len` - the length, in bytes, to which the `CLOB` value should be truncated
  Throws:
    `java.sql.SQLException` - if there is an error accessing the `CLOB` value
  Since:
    JDK 1.4, HSQLDB 1.7.2

Copyright © 2001 - 2005 HSQL Development Group. All Rights Reserved.