1 /* 2 * Copyright (c) 1998, 2006, 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<sup><font size=-2>TM</font></sup> 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 */ length()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 */ getSubString(long pos, int length)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 */ getCharacterStream()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 */ getAsciiStream()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 */ position(String searchstr, long start)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 */ position(Clob searchstr, long start)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 accomodate 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 */ setString(long pos, String str)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 accomodate 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 */ setString(long pos, String str, int offset, int len)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 accomodate 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 */ setAsciiStream(long pos)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 accomodate 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 */ setCharacterStream(long pos)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 */ truncate(long len)309 void truncate(long len) throws SQLException; 310 311 /** 312 * This method frees the <code>Clob</code> object and releases the resources the resources 313 * that it 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 * <p> 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 */ free()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 */ getCharacterStream(long pos, long length)346 Reader getCharacterStream(long pos, long length) throws SQLException; 347 348 } 349