1 /*
   2  * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.sql;
  27 
  28 import java.io.Reader;
  29 
  30 /**
  31  * The mapping in the Java™ programming language
  32  * for the SQL <code>CLOB</code> type.
  33  * An SQL <code>CLOB</code> is a built-in type
  34  * that stores a Character Large Object as a column value in a row of
  35  * a database table.
  36  * By default drivers implement a <code>Clob</code> object using an SQL
  37  * <code>locator(CLOB)</code>, which means that a <code>Clob</code> object
  38  * contains a logical pointer to the SQL <code>CLOB</code> data rather than
  39  * the data itself. A <code>Clob</code> object is valid for the duration
  40  * of the transaction in which it was created.
  41  * <P>The <code>Clob</code> interface provides methods for getting the
  42  * length of an SQL <code>CLOB</code> (Character Large Object) value,
  43  * for materializing a <code>CLOB</code> value on the client, and for
  44  * searching for a substring or <code>CLOB</code> object within a
  45  * <code>CLOB</code> value.
  46  * Methods in the interfaces {@link ResultSet},
  47  * {@link CallableStatement}, and {@link PreparedStatement}, such as
  48  * <code>getClob</code> and <code>setClob</code> allow a programmer to
  49  * access an SQL <code>CLOB</code> value.  In addition, this interface
  50  * has methods for updating a <code>CLOB</code> value.
  51  * <p>
  52  * All methods on the <code>Clob</code> interface must be fully implemented if the
  53  * JDBC driver supports the data type.
  54  *
  55  * @since 1.2
  56  */
  57 
  58 public interface Clob {
  59 
  60   /**
  61    * Retrieves the number of characters
  62    * in the <code>CLOB</code> value
  63    * designated by this <code>Clob</code> object.
  64    *
  65    * @return length of the <code>CLOB</code> in characters
  66    * @exception SQLException if there is an error accessing the
  67    *            length of the <code>CLOB</code> value
  68    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
  69    * this method
  70    * @since 1.2
  71    */
  72   long length() throws SQLException;
  73 
  74   /**
  75    * Retrieves a copy of the specified substring
  76    * in the <code>CLOB</code> value
  77    * designated by this <code>Clob</code> object.
  78    * The substring begins at position
  79    * <code>pos</code> and has up to <code>length</code> consecutive
  80    * characters.
  81    *
  82    * @param pos the first character of the substring to be extracted.
  83    *            The first character is at position 1.
  84    * @param length the number of consecutive characters to be copied;
  85    * the value for length must be 0 or greater
  86    * @return a <code>String</code> that is the specified substring in
  87    *         the <code>CLOB</code> value designated by this <code>Clob</code> object
  88    * @exception SQLException if there is an error accessing the
  89    *            <code>CLOB</code> value; if pos is less than 1 or length is
  90    * less than 0
  91    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
  92    * this method
  93    * @since 1.2
  94    */
  95   String getSubString(long pos, int length) throws SQLException;
  96 
  97   /**
  98    * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
  99    * object as a <code>java.io.Reader</code> object (or as a stream of
 100    * characters).
 101    *
 102    * @return a <code>java.io.Reader</code> object containing the
 103    *         <code>CLOB</code> data
 104    * @exception SQLException if there is an error accessing the
 105    *            <code>CLOB</code> value
 106    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 107    * this method
 108    * @see #setCharacterStream
 109    * @since 1.2
 110    */
 111   java.io.Reader getCharacterStream() throws SQLException;
 112 
 113   /**
 114    * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
 115    * object as an ascii stream.
 116    *
 117    * @return a <code>java.io.InputStream</code> object containing the
 118    *         <code>CLOB</code> data
 119    * @exception SQLException if there is an error accessing the
 120    *            <code>CLOB</code> value
 121    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 122    * this method
 123    * @see #setAsciiStream
 124    * @since 1.2
 125    */
 126   java.io.InputStream getAsciiStream() throws SQLException;
 127 
 128   /**
 129    * Retrieves the character position at which the specified substring
 130    * <code>searchstr</code> appears in the SQL <code>CLOB</code> value
 131    * represented by this <code>Clob</code> object.  The search
 132    * begins at position <code>start</code>.
 133    *
 134    * @param searchstr the substring for which to search
 135    * @param start the position at which to begin searching; the first position
 136    *              is 1
 137    * @return the position at which the substring appears or -1 if it is not
 138    *         present; the first position is 1
 139    * @exception SQLException if there is an error accessing the
 140    *            <code>CLOB</code> value or if pos is less than 1
 141    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 142    * this method
 143    * @since 1.2
 144    */
 145   long position(String searchstr, long start) throws SQLException;
 146 
 147   /**
 148    * Retrieves the character position at which the specified
 149    * <code>Clob</code> object <code>searchstr</code> appears in this
 150    * <code>Clob</code> object.  The search begins at position
 151    * <code>start</code>.
 152    *
 153    * @param searchstr the <code>Clob</code> object for which to search
 154    * @param start the position at which to begin searching; the first
 155    *              position is 1
 156    * @return the position at which the <code>Clob</code> object appears
 157    *              or -1 if it is not present; the first position is 1
 158    * @exception SQLException if there is an error accessing the
 159    *            <code>CLOB</code> value or if start is less than 1
 160    * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 161    * this method
 162    * @since 1.2
 163    */
 164   long position(Clob searchstr, long start) throws SQLException;
 165 
 166     //---------------------------- jdbc 3.0 -----------------------------------
 167 
 168     /**
 169      * Writes the given Java <code>String</code> to the <code>CLOB</code>
 170      * value that this <code>Clob</code> object designates at the position
 171      * <code>pos</code>. The string will overwrite the existing characters
 172      * in the <code>Clob</code> object starting at the position
 173      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
 174      * while writing the given string, then the length of the <code>Clob</code>
 175      * value will be increased to accommodate the extra characters.
 176      * <p>
 177      * <b>Note:</b> If the value specified for <code>pos</code>
 178      * is greater then the length+1 of the <code>CLOB</code> value then the
 179      * behavior is undefined. Some JDBC drivers may throw a
 180      * <code>SQLException</code> while other drivers may support this
 181      * operation.
 182      *
 183      * @param pos the position at which to start writing to the <code>CLOB</code>
 184      *         value that this <code>Clob</code> object represents;
 185      * The first position is 1
 186      * @param str the string to be written to the <code>CLOB</code>
 187      *        value that this <code>Clob</code> designates
 188      * @return the number of characters written
 189      * @exception SQLException if there is an error accessing the
 190      *            <code>CLOB</code> value or if pos is less than 1
 191      *
 192      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 193      * this method
 194      * @since 1.4
 195      */
 196     int setString(long pos, String str) throws SQLException;
 197 
 198     /**
 199      * Writes <code>len</code> characters of <code>str</code>, starting
 200      * at character <code>offset</code>, to the <code>CLOB</code> value
 201      * that this <code>Clob</code> represents.  The string will overwrite the existing characters
 202      * in the <code>Clob</code> object starting at the position
 203      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
 204      * while writing the given string, then the length of the <code>Clob</code>
 205      * value will be increased to accommodate the extra characters.
 206      * <p>
 207      * <b>Note:</b> If the value specified for <code>pos</code>
 208      * is greater then the length+1 of the <code>CLOB</code> value then the
 209      * behavior is undefined. Some JDBC drivers may throw a
 210      * <code>SQLException</code> while other drivers may support this
 211      * operation.
 212      *
 213      * @param pos the position at which to start writing to this
 214      *        <code>CLOB</code> object; The first position  is 1
 215      * @param str the string to be written to the <code>CLOB</code>
 216      *        value that this <code>Clob</code> object represents
 217      * @param offset the offset into <code>str</code> to start reading
 218      *        the characters to be written
 219      * @param len the number of characters to be written
 220      * @return the number of characters written
 221      * @exception SQLException if there is an error accessing the
 222      *            <code>CLOB</code> value or if pos is less than 1
 223      *
 224      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 225      * this method
 226      * @since 1.4
 227      */
 228     int setString(long pos, String str, int offset, int len) throws SQLException;
 229 
 230     /**
 231      * Retrieves a stream to be used to write Ascii characters to the
 232      * <code>CLOB</code> value that this <code>Clob</code> object represents,
 233      * starting at position <code>pos</code>.  Characters written to the stream
 234      * will overwrite the existing characters
 235      * in the <code>Clob</code> object starting at the position
 236      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
 237      * while writing characters to the stream, then the length of the <code>Clob</code>
 238      * value will be increased to accommodate the extra characters.
 239      * <p>
 240      * <b>Note:</b> If the value specified for <code>pos</code>
 241      * is greater then the length+1 of the <code>CLOB</code> value then the
 242      * behavior is undefined. Some JDBC drivers may throw a
 243      * <code>SQLException</code> while other drivers may support this
 244      * operation.
 245      *
 246      * @param pos the position at which to start writing to this
 247      *        <code>CLOB</code> object; The first position is 1
 248      * @return the stream to which ASCII encoded characters can be written
 249      * @exception SQLException if there is an error accessing the
 250      *            <code>CLOB</code> value or if pos is less than 1
 251      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 252      * this method
 253      * @see #getAsciiStream
 254      *
 255      * @since 1.4
 256      */
 257     java.io.OutputStream setAsciiStream(long pos) throws SQLException;
 258 
 259     /**
 260      * Retrieves a stream to be used to write a stream of Unicode characters
 261      * to the <code>CLOB</code> value that this <code>Clob</code> object
 262      * represents, at position <code>pos</code>. Characters written to the stream
 263      * will overwrite the existing characters
 264      * in the <code>Clob</code> object starting at the position
 265      * <code>pos</code>.  If the end of the <code>Clob</code> value is reached
 266      * while writing characters to the stream, then the length of the <code>Clob</code>
 267      * value will be increased to accommodate the extra characters.
 268      * <p>
 269      * <b>Note:</b> If the value specified for <code>pos</code>
 270      * is greater then the length+1 of the <code>CLOB</code> value then the
 271      * behavior is undefined. Some JDBC drivers may throw a
 272      * <code>SQLException</code> while other drivers may support this
 273      * operation.
 274      *
 275      * @param  pos the position at which to start writing to the
 276      *        <code>CLOB</code> value; The first position is 1
 277      *
 278      * @return a stream to which Unicode encoded characters can be written
 279      * @exception SQLException if there is an error accessing the
 280      *            <code>CLOB</code> value or if pos is less than 1
 281      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 282      * this method
 283      * @see #getCharacterStream
 284      *
 285      * @since 1.4
 286      */
 287     java.io.Writer setCharacterStream(long pos) throws SQLException;
 288 
 289     /**
 290      * Truncates the <code>CLOB</code> value that this <code>Clob</code>
 291      * designates to have a length of <code>len</code>
 292      * characters.
 293      * <p>
 294      * <b>Note:</b> If the value specified for <code>pos</code>
 295      * is greater then the length+1 of the <code>CLOB</code> value then the
 296      * behavior is undefined. Some JDBC drivers may throw a
 297      * <code>SQLException</code> while other drivers may support this
 298      * operation.
 299      *
 300      * @param len the length, in characters, to which the <code>CLOB</code> value
 301      *        should be truncated
 302      * @exception SQLException if there is an error accessing the
 303      *            <code>CLOB</code> value or if len is less than 0
 304      *
 305      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 306      * this method
 307      * @since 1.4
 308      */
 309     void truncate(long len) throws SQLException;
 310 
 311     /**
 312      * This method releases the resources that the <code>Clob</code> object
 313      * holds.  The object is invalid once the <code>free</code> method
 314      * is called.
 315      * <p>
 316      * After <code>free</code> has been called, any attempt to invoke a
 317      * method other than <code>free</code> will result in a <code>SQLException</code>
 318      * being thrown.  If <code>free</code> is called multiple times, the subsequent
 319      * calls to <code>free</code> are treated as a no-op.
 320      *
 321      * @throws SQLException if an error occurs releasing
 322      * the Clob's resources
 323      *
 324      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 325      * this method
 326      * @since 1.6
 327      */
 328     void free() throws SQLException;
 329 
 330     /**
 331      * Returns a <code>Reader</code> object that contains a partial <code>Clob</code> value, starting
 332      * with the character specified by pos, which is length characters in length.
 333      *
 334      * @param pos the offset to the first character of the partial value to
 335      * be retrieved.  The first character in the Clob is at position 1.
 336      * @param length the length in characters of the partial value to be retrieved.
 337      * @return <code>Reader</code> through which the partial <code>Clob</code> value can be read.
 338      * @throws SQLException if pos is less than 1 or if pos is greater than the number of
 339      * characters in the <code>Clob</code> or if pos + length is greater than the number of
 340      * characters in the <code>Clob</code>
 341      *
 342      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 343      * this method
 344      * @since 1.6
 345      */
 346     Reader getCharacterStream(long pos, long length) throws SQLException;
 347 
 348 }