package org.okip.service.dbc.api;



/*
   Copyright (c) 2002 Massachusetts Institute of Technology

   This work, including any software, documents, or other related items
   (the "Work"), is being provided by the copyright holder(s) subject to
   the terms of the MIT OKI(TM) API Definition License. By obtaining,
   using and/or copying this Work, you agree that you have read,
   understand, and will comply with the following terms and conditions of
   the MIT OKI(TM) API Definition License:

   You may use, copy, and distribute unmodified versions of this Work for
   any purpose, without fee or royalty, provided that you include the
   following on ALL copies of the Work that you make or distribute:

    *  The full text of the MIT OKI(TM) API Definition License in a
       location viewable to users of the redistributed Work.

    *  Any pre-existing intellectual property disclaimers, notices, or
       terms and conditions. If none exist, a short notice similar to the
       following should be used within the body of any redistributed
       Work: "Copyright (c) 2002 Massachusetts Institute of Technology. All
       Rights Reserved."

   You may modify or create Derivatives of this Work only for your
   internal purposes. You shall not distribute or transfer any such
   Derivative of this Work to any location or any other third party. For
   purposes of this license, "Derivative" shall mean any derivative of
   the Work as defined in the United States Copyright Act of 1976, such
   as a translation or modification.

   THIS WORK PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE WORK
   OR THE USE OR OTHER DEALINGS IN THE WORK.

   The name and trademarks of copyright holder(s) and/or MIT may NOT be
   used in advertising or publicity pertaining to the Work without
   specific, written prior permission. Title to copyright in the Work and
   any associated documentation will at all times remain with the
   copyright holders.

*/

/*
 * $Source: /cvs/oki/tech/src/org/okip/service/dbc/api/Clob.java,v $
 */

/**
 * The mapping in the OKI DBC API programming language for the SQL
 * CLOB type. An SQL CLOB is a built-in type that stores a Character
 * Large Object as a column value in a row of a database table. By
 * default drivers implement a Clob object using an SQL locator(CLOB),
 * which means that a Clob object contains a logical pointer to the
 * SQL CLOB data rather than the data itself. A Clob object is valid
 * for the duration of the transaction in which it was created.
 * <p>
 * The Clob interface 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.  Methods in the interfaces ResultSet,
 * CallableStatement, and PreparedStatement, such as getClob and
 * setClob allow a programmer to access an SQL CLOB value. In
 * addition, this interface has methods for updating a CLOB value.
 *
 * <p>
 * Licensed under the {@link org.okip.service.ApiLicense MIT OKI&#153; API Definition License}.
 *
 * @version $Name:  $ / $Revision: 1.7 $ / $Date: 2002/07/29 18:42:42 $
 */
public interface Clob
extends java.io.Serializable {

  /* methods which are in Clob in 1.4 but not in this interface:
     getAsciiStream
     getCharacterStream
     setAsciiStream
     setCharacterStream
   */

  /**
   * Retrieves a copy of the specified substring
   * in the CLOB value designated by this Clob object.
   *
   * @param pos
   * @param length
   *
   * @return String
   *
   * @throws DbcException
   *
   */
  String getSubString(long pos, int length)
  throws DbcException;

  /**
   * Retrieves the number of characters in the
   * CLOB value designated by this Clob object.
   *
   * @return long
   *
   * @throws DbcException
   *
   */
  long length()
  throws DbcException;

  /**
   * Retrieves the character position at which
   * the specified Clob object searchstr appears
   * in this Clob object.
   *
   * @param searchstr
   * @param start
   *
   * @return long
   *
   * @throws DbcException
   *
   */
  long position(Clob searchstr, long start)
  throws DbcException;

  /**
   * Retrieves the character position at which
   * the specified substring searchstr appears
   * in the SQL CLOB value represented by this
   * Clob object.
   *
   * @param searchstr
   * @param start
   *
   * @return long
   *
   * @throws DbcException
   *
   */
  long position(String searchstr, long start)
  throws DbcException;

  /**
   * Writes the given Java String to the
   * CLOB value that this Clob object designates
   * at the position pos.
   *
   * @param pos
   * @param str
   *
   * @return int
   *
   * @throws DbcException
   *
   */
  int setString(long pos, String str)
  throws DbcException;

  /**
   * Writes len characters of str, starting at
   * character offset, to the CLOB value that
   * this Clob represents.
   *
   * @param pos
   * @param str
   * @param offset
   * @param len
   *
   * @return int
   *
   * @throws DbcException
   *
   */
  int setString(long pos, String str, int offset, int len)
  throws DbcException;

  /**
   * Truncates the CLOB value that this Clob
   * designates to have a length of len characters.
   *
   * @param len
   *
   * @throws DbcException
   *
   */
  void truncate(long len)
  throws DbcException;

}