home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / sql / Clob.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  4.6 KB  |  115 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Clob.java    1.8 98/05/19
  3.  * 
  4.  * Copyright 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * JDBC 2.0
  19.  * The mapping in the Java<sup><font size=-2>TM</font></sup> programming language 
  20.  * for the SQL <code>CLOB</code> type.
  21.  * An SQL <code>CLOB</code> is a built-in type
  22.  * that stores a Character Large Object as a column value in a row of
  23.  * a database table.
  24.  * The driver implements a <code>Clob</code> object using an SQL
  25.  * <code>locator(CLOB)</code>, which means that a <code>Clob</code> object 
  26.  * contains a logical pointer to the SQL <code>CLOB</code> data rather than
  27.  * the data itself. A <code>Clob</code> object is valid for the duration
  28.  * of the transaction in which it was created.
  29.  * <P>The <code>Clob</code> interface provides methods for getting the
  30.  * length of an SQL <code>CLOB</code> (Character Large Object) value,
  31.  * for materializing a <code>CLOB</code> value on the client, and for
  32.  * searching for a substring or <code>CLOB</code> object within a
  33.  * <code>CLOB</code> value.
  34.  * Methods in the interfaces {@link ResultSet},
  35.  * {@link CallableStatement}, and {@link PreparedStatement}, such as
  36.  * <code>getClob</code> and <code>setClob</code> allow a programmer to
  37.  * access the SQL <code>CLOB</code>.
  38.  */
  39.  
  40. public interface Clob {
  41.  
  42.   /**
  43.    * Returns the number of characters 
  44.    * in the <code>CLOB</code> value
  45.    * designated by this <code>Clob</code> object.
  46.    * @return length of the <code>CLOB</code> in characters
  47.    * @exception SQLException if there is an error accessing the
  48.    * length of the <code>CLOB</code>
  49.    */
  50.   long length() throws SQLException;
  51.  
  52.   /**
  53.    * Returns a copy of the specified substring 
  54.    * in the <code>CLOB</code> value
  55.    * designated by this <code>Clob</code> object.
  56.    * The substring begins at position
  57.    * <code>pos</code> and has up to <code>length</code> consecutive
  58.    * characters.
  59.    * @param pos the first character of the substring to be extracted.
  60.    *            The first character is at position 1.
  61.    * @param length the number of consecutive characters to be copied
  62.    * @return a <code>String</code> that is the specified substring in
  63.    *         the <code>CLOB</code> value designated by this <code>Clob</code> object
  64.    * @exception SQLException if there is an error accessing the
  65.    * <code>CLOB</code> 
  66.    */
  67.   String getSubString(long pos, int length) throws SQLException;
  68.  
  69.   /**
  70.    * Gets the <code>Clob</code> contents as a Unicode stream.
  71.    * @return a Unicode stream containing the <code>CLOB</code> data
  72.    * @exception SQLException if there is an error accessing the 
  73.    * <code>CLOB</code>
  74.    */
  75.   java.io.Reader getCharacterStream() throws SQLException;
  76.  
  77.   /**
  78.    * Gets the <code>CLOB</code> value designated by this <code>Clob</code>
  79.    * object as a stream of Ascii bytes.
  80.    * @return an ascii stream containing the <code>CLOB</code> data
  81.    * @exception SQLException if there is an error accessing the 
  82.    * <code>CLOB</code> value
  83.    */
  84.   java.io.InputStream getAsciiStream() throws SQLException;
  85.  
  86.   /** 
  87.    * Determines the character position at which the specified substring 
  88.    * <code>searchstr</code> appears in the <code>CLOB</code>.  The search 
  89.    * begins at position <code>start</code>.
  90.    * @param searchstr the substring for which to search 
  91.    * @param start the position at which to begin searching; the first position
  92.    *              is 1
  93.    * @return the position at which the substring appears, else -1; the first
  94.    *         position is 1
  95.    * @exception SQLException if there is an error accessing the       
  96.    * <code>CLOB</code> value
  97.    */
  98.   long position(String searchstr, long start) throws SQLException;
  99.  
  100.   /** 
  101.    * Determines the character position at which the specified  
  102.    * <code>Clob</code> object <code>searchstr</code> appears in this 
  103.    * <code>Clob</code> object.  The search begins at position 
  104.    * <code>start</code>.
  105.    * @param searchstr the <code>Clob</code> object for which to search
  106.    * @param start the position at which to begin searching; the first
  107.    *              position is 1
  108.    * @return the position at which the <code>Clob</code> object appears, 
  109.    * else -1; the first position is 1
  110.    * @exception SQLException if there is an error accessing the 
  111.    * <code>CLOB</code> value
  112.    */
  113.   long position(Clob searchstr, long start) throws SQLException;
  114. }
  115.