MemoryClob (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.util, class: MemoryClob

# Class MemoryClob

java.lang.Object
org.apache.cayenne.util.MemoryClob

All Implemented Interfaces:
  `Clob`

public class MemoryClob extends Object implements Clob
A Clob implementation that stores contents in memory.

This implementation is based on jdbcClob from HSQLDB (copyright HSQL Development Group).

Since:
  1.2

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MemoryClob(String data)`
  Constructs a new jdbcClob object wrapping the given character sequence.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `free()`
  `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)`
  `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.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### MemoryClob

    public MemoryClob(String data)
    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:
      `CayenneRuntimeException` - if the argument is null

- ## Method Details

  - ### length

    public long length() throws SQLException
    Retrieves the number of characters in the `CLOB` value designated by this `Clob` object.
    Specified by:
      `length` in interface `Clob`
    Returns:
      length of the `CLOB` in characters
    Throws:
      `SQLException` - if there is an error accessing the length of the `CLOB` value

  - ### 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.
    Specified by:
      `getSubString` in interface `Clob`
    Throws:
      `SQLException`

  - ### 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).
    Specified by:
      `getCharacterStream` in interface `Clob`
    Returns:
      a `java.io.Reader` object containing the `CLOB` data
    Throws:
      `SQLException` - if there is an error accessing the `CLOB` value

  - ### getAsciiStream

    public InputStream getAsciiStream() throws SQLException
    Retrieves the `CLOB` value designated by this `Clob` object as an ascii stream.
    Specified by:
      `getAsciiStream` in interface `Clob`
    Returns:
      a `java.io.InputStream` object containing the `CLOB` data
    Throws:
      `SQLException` - if there is an error accessing the `CLOB` value

  - ### 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`.
    Specified by:
      `position` in interface `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:
      `SQLException` - if there is an error accessing the `CLOB` value

  - ### 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`.
    Specified by:
      `position` in interface `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:
      `SQLException` - if there is an error accessing the `CLOB` value

  - ### 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`. Calling this method always throws an `SQLException`.
    Specified by:
      `setString` in interface `Clob`
    Throws:
      `SQLException`

  - ### 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. Calling this method always throws an `SQLException`.
    Specified by:
      `setString` in interface `Clob`
    Throws:
      `SQLException`

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

    Calling this method always throws an `SQLException`.

    Specified by:
      `setAsciiStream` in interface `Clob`
    Throws:
      `SQLException`

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

    Calling this method always throws an `SQLException`.

    Specified by:
      `setCharacterStream` in interface `Clob`
    Throws:
      `SQLException`

  - ### truncate

    public void truncate(long len) throws SQLException
    Truncates the `CLOB` value that this `Clob` designates to have a length of `len` characters.

    Specified by:
      `truncate` in interface `Clob`
    Throws:
      `SQLException`

  - ### free

    public void free() throws SQLException
    Specified by:
      `free` in interface `Clob`
    Throws:
      `SQLException`
    Since:
      3.0

  - ### getCharacterStream

    public Reader getCharacterStream(long pos, long length) throws SQLException
    Specified by:
      `getCharacterStream` in interface `Clob`
    Throws:
      `SQLException`
    Since:
      3.0