/*
 * @(#)Clob.java	1.8 98/05/19
 * 
 * Copyright 1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package java.sql;
 
/**
 * JDBC 2.0
 *
 * <p>By default, a Clob is a transaction duration reference to a 
 * character large object.
 */

public interface Clob {

  /**
   * The length of the Character Large Object in characters.
   *
   * @return length of the CLOB in characters
   */
  long length() throws SQLException;

  /**
   * Return copy of the substring of the CLOB at the requested position.
   *
   * @param pos is the first character of the substring to be extracted.
   * @param length is the number of consecutive character to be copied.
   *
   * @return a byte array containing a substring of the CLOB
   */
  String getSubString(long pos, int length) throws SQLException;

  /**
   * Get the Clob contents as a Unicode stream.
   *
   * @return a Unicode stream containing the CLOB data
   */
  java.io.Reader getCharacterStream() throws SQLException;

  /**
   * Get the Clob contents as an ascii stream.
   *
   * @return an ascii stream containing the CLOB data
   */
  java.io.InputStream getAsciiStream() throws SQLException;

  /** 
   * Determine the character position at which the given substring 
   * @searchstr appears in the CLOB.  Begin search at position @start.
   * Return -1 if the substring does not appear in the CLOB.
   *
   * @param searchstr is the substring to search for.
   * @param start is the position at which to begin searching.
   * @return the position at which the substring appears, else -1.
   */
  long position(String searchstr, long start) throws SQLException;

  /** 
   * Determine the character position at which the given substring 
   * @searchstr appears in the CLOB.  Begin search at position @start.
   * Return -1 if the substring does not appear in the CLOB.
   *
   * @param searchstr is the substring to search for.
   * @param start is the position at which to begin searching.
   * @return the position at which the substring appears, else -1.
   */
  long position(Clob searchstr, long start) throws SQLException;
}
