Module org.hsqldb
Package org.hsqldb.jdbc

## Class JDBCClobFile

- java.lang.Object
- - org.hsqldb.jdbc.JDBCClobFile

- All Implemented Interfaces:
    `java.sql.Clob`

      public class JDBCClobFile
      extends java.lang.Object
      implements java.sql.Clob

  A client-side file-based implementation of Clob.

  HSQLDB-Specific Information:

  Starting with 2.1, in addition to HSQLDB driver support for both client-side in-memory and remote SQL CLOB data implementations, this class is provided to expose efficient, relatively high-performance CLOB operations over client accessible files.

  Design Notes

  Although it is possible to implement a transactional version of this class, the present implementation directly propagates changes to the underlying file such that changes become visible as soon as they are either implicitly or explicitly flushed to disk.

  Since:
    HSQLDB 2.1
  Author:
    Campbell Burnet (campbell-burnet@users dot sourceforge.net)

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `TEMP_FILE_PREFIX` |
    `static java.lang.String` | `TEMP_FILE_SUFFIX` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JDBCClobFile()` | Convenience constructor for `JDBCClobFile((String)null)`.
    `JDBCClobFile​(java.io.File file)` | Convenience constructor for `JDBCClobFile(file,null)`.
    `JDBCClobFile​(java.io.File file, java.lang.String encoding)` | Constructs a new JDBCClobFile instance backed by the given File object using the given encoding to read and write file content.
    `JDBCClobFile​(java.lang.String encoding)` | Constructs a new JDBCClobFile instance backed by a File object created by File.createTempFile(TEMP_FILE_PREFIX, TEMP_FILE_SUFFIX), using the given encoding to read and write file content.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `free()` | This method frees the `Clob` object and releases the resources that it holds.
    `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.io.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.
    `java.lang.String` | `getEncoding()` |
    `java.io.File` | `getFile()` | Retrieves the canonical `File` object denoting the file that backs this CLOB.
    `java.lang.String` | `getSubString​(long pos, int length)` | Retrieves a copy of the specified substring in the `CLOB` value designated by this `Clob` object.
    `boolean` | `isDeleteOnFree()` | Retrieves whether an attempt to delete the backing file is made in response to invocation of `free()`.
    `long` | `length()` | Retrieves the number of characters in the `CLOB` value designated by this `Clob` object.
    `long` | `position​(char[] pattern, long start)` | Retrieves the character position at which the specified char[] `pattern` appears in the `CLOB` value represented by 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.
    `long` | `position​(java.sql.Clob pattern, long start)` | Retrieves the character position at which the specified `Clob` object `searchstr` appears in 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`.
    `void` | `setDeleteOnFree​(boolean deleteOnFree)` | Assigns whether an attempt to delete the backing file is made in response to invocation of `free()`.
    `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`

- - ### Field Detail

    - #### TEMP_FILE_PREFIX

          public static final java.lang.String TEMP_FILE_PREFIX

      See Also:
        Constant Field Values

    - #### TEMP_FILE_SUFFIX

          public static final java.lang.String TEMP_FILE_SUFFIX

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JDBCClobFile

          public JDBCClobFile()
                       throws java.sql.SQLException

      Convenience constructor for `JDBCClobFile((String)null)`.
      Throws:
        `java.sql.SQLException` - if the platform encoding is unsupported, the temp file cannot be created or some other error occurs that prevents the construction of a valid instance of this class.

    - #### JDBCClobFile

          public JDBCClobFile​(java.lang.String encoding)
                       throws java.sql.SQLException

      Constructs a new JDBCClobFile instance backed by a File object created by File.createTempFile(TEMP_FILE_PREFIX, TEMP_FILE_SUFFIX), using the given encoding to read and write file content.
      Parameters:
        `encoding` - the name of the character encoding used to read and write character data in the underlying file, as well as to determine the character length of and character offsets into the underlying file. Specify null to denote the platform encoding.
      Throws:
        `java.sql.SQLException` - if the given encoding is unsupported, the backing temp file could not be created or if a security manager exists and its `{@link java.lang.SecurityManager#checkWrite(java.lang.String)}` method does not allow a file to be created.

    - #### JDBCClobFile

          public JDBCClobFile​(java.io.File file)
                       throws java.sql.SQLException

      Convenience constructor for `JDBCClobFile(file,null)`.
      Parameters:
        `file` - that is to back the new CLOB instance.
      Throws:
        `java.sql.SQLException` - if an I/O error occurs, which is possible because the construction of the canonical pathname may require file-system queries; a required system property value cannot be accessed; a security manager exists and its `{@link java.lang.SecurityManager#checkRead}` method denies read access to the file

    - #### JDBCClobFile

          public JDBCClobFile​(java.io.File file,
                              java.lang.String encoding)
                       throws java.sql.SQLException

      Constructs a new JDBCClobFile instance backed by the given File object using the given encoding to read and write file content.
      Parameters:
        `file` - that is to back the new CLOB instance.
        `encoding` - the name of the character encoding used to read and write character data in the underlying file, as well as to determine the character length of and character offsets into the underlying file. Specify null to denote the platform encoding.
      Throws:
        `java.sql.SQLException` - if the given encoding is unsupported; an I/O error occurs, which is possible because the construction of the canonical pathname may require file-system queries; a required system property value cannot be accessed; a security manager exists and its `{@link java.lang.SecurityManager#checkRead}` method denies read access to the file

  - ### 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
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.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.
      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; 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:
        `java.sql.SQLException` - if there is an error accessing the `CLOB` value; if pos is less than 1 or length is less than 0
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.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
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.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
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.2
      See Also:
        `setAsciiStream(long)`

    - #### position

          public long position​(char[] pattern,
                               long start)
                        throws java.sql.SQLException

      Retrieves the character position at which the specified char[] `pattern` appears in the `CLOB` value represented by this `Clob` object. The search begins at position `start`.
      Parameters:
        `pattern` - 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 or if pos is less than 1
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method

    - #### 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 or if pos is less than 1
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.2

    - #### position

          public long position​(java.sql.Clob pattern,
                               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:
        `pattern` - 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 or if start is less than 1
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.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`. 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 a `SQLException` while other drivers may support this operation.

      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; 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:
        `java.sql.SQLException` - if there is an error accessing the `CLOB` value or if pos is less than 1
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.4

    - #### 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. 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 a `SQLException` while other drivers may support this operation.

      Specified by:
        `setString` in interface `java.sql.Clob`
      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:
        `java.sql.SQLException` - if there is an error accessing the `CLOB` value or if pos is less than 1
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.4

    - #### 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`. 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 a `SQLException` while other drivers may support this operation.

      Specified by:
        `setAsciiStream` in interface `java.sql.Clob`
      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:
        `java.sql.SQLException` - if there is an error accessing the `CLOB` value or if pos is less than 1
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.4
      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`. 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 a `SQLException` while other drivers may support this operation.

      HSQLDB-Specific Information:

      When the value specified for `pos` is greater then the length+1, an `SQLException` is thrown.
      Specified by:
        `setCharacterStream` in interface `java.sql.Clob`
      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:
        `java.sql.SQLException` - if there is an error accessing the `CLOB` value or if pos is less than 1
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.4
      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.

      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 a `SQLException` while other drivers may support this operation.

      Specified by:
        `truncate` in interface `java.sql.Clob`
      Parameters:
        `len` - the length, in characters, to which the `CLOB` value should be truncated
      Throws:
        `java.sql.SQLException` - if there is an error accessing the `CLOB` value or if len is less than 0
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.4

    - #### free

          public void free()
                    throws java.sql.SQLException

      This method frees the `Clob` object and releases 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.

      Specified by:
        `free` in interface `java.sql.Clob`
      Throws:
        `java.sql.SQLException` - if an error occurs releasing the Clob's resources
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        JDK 1.4

    - #### getCharacterStream

          public java.io.Reader getCharacterStream​(long pos,
                                                   long length)
                                            throws java.sql.SQLException

      Returns a `Reader` object that contains a partial `Clob` value, starting with the character specified by pos, which is length characters in length.
      Specified by:
        `getCharacterStream` in interface `java.sql.Clob`
      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:
        `java.sql.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`
        `java.sql.SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
      Since:
        1.6

    - #### getFile

          public java.io.File getFile()

      Retrieves the canonical `File` object denoting the file that backs this CLOB.
      Returns:
        the file that backs this CLOB.

    - #### getEncoding

          public java.lang.String getEncoding()

      Returns:
        the name of the character encoding used to read and write character data in the underlying files, as well as to determine the character length and character offsets into the underlying file

    - #### isDeleteOnFree

          public boolean isDeleteOnFree()

      Retrieves whether an attempt to delete the backing file is made in response to invocation of `free()`.
      Returns:
        true if backing file deletion is attempted; otherwise false.

    - #### setDeleteOnFree

          public void setDeleteOnFree​(boolean deleteOnFree)

      Assigns whether an attempt to delete the backing file is made in response to invocation of `free()`.
      Parameters:
        `deleteOnFree` - the new value to assign