## org.hsqldb.jdbc
Class JDBCClobFile

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

All Implemented Interfaces:
  Clob

    public class JDBCClobFile

extends Object
implements 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:
  boucherb@users

Field Summary
`static String` `TEMP_FILE_PREFIX`
`static String` `TEMP_FILE_SUFFIX`

Constructor Summary
`JDBCClobFile()` Convenience constructor for `JDBCClobFile((String)null)`.
`JDBCClobFile(File file)` Convenience constructor for `JDBCClobFile(file,null)`.
`JDBCClobFile(File file, String encoding)` Constructs a new JDBCClobFile instance backed by the given File object using the given encoding to read and write file content.
`JDBCClobFile(String encoding)` Constructs a new JDBCClobFile instance backed by an File object created by File.createTempFile(TEMP_FILE_PREFIX, TEMP_FILE_SUFFIX), using the given encoding to read and write file content.

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` `getEncoding()`
`File` `getFile()` Retrieves the canonical `File` object denoting the file that backs this CLOB.
`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(Clob pattern, 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 `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`.
`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, 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 java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### TEMP_FILE_PREFIX

    public static final String TEMP_FILE_PREFIX

See Also:
  Constant Field Values

### TEMP_FILE_SUFFIX

    public static final String TEMP_FILE_SUFFIX

See Also:
  Constant Field Values

Constructor Detail

### JDBCClobFile

    public JDBCClobFile()
                 throws SQLException

  Convenience constructor for `JDBCClobFile((String)null)`.

  Throws:
    `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(String encoding)
                 throws SQLException

  Constructs a new JDBCClobFile instance backed by an 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:
    `SQLException` - if the given encoding is unsupported, the backing temp file could not be created or if a security manager exists and its ``SecurityManager.checkWrite(java.lang.String)`` method does not allow a file to be created.

### JDBCClobFile

    public JDBCClobFile(File file)
                 throws SQLException

  Convenience constructor for `JDBCClobFile(file,null)`.

  Parameters:
    `file` - that is to back the new CLOB instance.
  Throws:
    `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 ``SecurityManager.checkRead(java.io.FileDescriptor)`` method denies read access to the file

### JDBCClobFile

    public JDBCClobFile(File file,
                        String encoding)
                 throws 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:
    `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 ``SecurityManager.checkRead(java.io.FileDescriptor)`` method denies read access to the file

Method Detail

### 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
    `SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
  Since:
    JDK 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.

  Specified by:
    `getSubString` in interface `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:
    `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:
    JDK 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).

  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
    `SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
  Since:
    JDK 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.

  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
    `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 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:
    `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

### position

    public long position(String 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 or if start is less than 1
    `SQLFeatureNotSupportedException` - if the JDBC driver does not support this method
  Since:
    JDK 1.2

### position

    public long position(Clob pattern,
                         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:
    `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:
    `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:
    JDK 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`. 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 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.

  Specified by:
    `setString` in interface `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:
    `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:
    JDK 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. 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 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.

  Specified by:
    `setString` in interface `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:
    `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:
    JDK 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`. 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 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.

  Specified by:
    `setAsciiStream` in interface `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:
    `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:
    JDK 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`. 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 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.

  Specified by:
    `setCharacterStream` in interface `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:
    `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:
    JDK 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.

  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.

  Specified by:
    `truncate` in interface `Clob`
  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:
    JDK 1.4

### free

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

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

### getCharacterStream

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

  Specified by:
    `getCharacterStream` in interface `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:
    `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

### getFile

    public File getFile()

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

  Returns:
    the file that backs this CLOB.

### getEncoding

    public 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

Copyright © 2001 - 2010 HSQL Development Group.