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} type. 33 * An SQL {@code CLOB} 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} object using an SQL 37 * {@code locator(CLOB)}, which means that a {@code Clob} object 38 * contains a logical pointer to the SQL {@code CLOB} data rather than 39 * the data itself. A {@code Clob} object is valid for the duration 40 * of the transaction in which it was created. 41 * <P>The {@code Clob} interface provides methods for getting the 42 * length of an SQL {@code CLOB} (Character Large Object) value, 43 * for materializing a {@code CLOB} value on the client, and for 44 * searching for a substring or {@code CLOB} object within a 45 * {@code CLOB} value. 46 * Methods in the interfaces {@link ResultSet}, 47 * {@link CallableStatement}, and {@link PreparedStatement}, such as 48 * {@code getClob} and {@code setClob} allow a programmer to 49 * access an SQL {@code CLOB} value. In addition, this interface 50 * has methods for updating a {@code CLOB} value. 51 * <p> 52 * All methods on the {@code Clob} interface must be 53 * fully implemented if the 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} value 63 * designated by this {@code Clob} object. 64 * 65 * @return length of the {@code CLOB} in characters 66 * @exception SQLException if there is an error accessing the 67 * length of the {@code CLOB} value 68 * @exception SQLFeatureNotSupportedException if the JDBC driver 69 * does not support 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} value 77 * designated by this {@code Clob} object. 78 * The substring begins at position 79 * {@code pos} and has up to {@code length} 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} that is the specified substring in 87 * the {@code CLOB} value designated by this {@code Clob} object 88 * @exception SQLException if there is an error accessing the 89 * {@code CLOB} value; if pos is less than 1 or length is 90 * less than 0 91 * @exception SQLFeatureNotSupportedException if the JDBC driver 92 * does not support this method 93 * @since 1.2 94 */ 95 String getSubString(long pos, int length) throws SQLException; 96 97 /** 98 * Retrieves the {@code CLOB} value designated by this {@code Clob} 99 * object as a {@code java.io.Reader} object (or as a stream of 100 * characters). 101 * 102 * @return a {@code java.io.Reader} object containing the 103 * {@code CLOB} data 104 * @exception SQLException if there is an error accessing the 105 * {@code CLOB} value 106 * @exception SQLFeatureNotSupportedException if the JDBC driver 107 * does not support this method 108 * @see #setCharacterStream 109 * @since 1.2 110 */ 111 java.io.Reader getCharacterStream() throws SQLException; 112 113 /** 114 * Retrieves the {@code CLOB} value designated by this {@code Clob} 115 * object as an ascii stream. 116 * 117 * @return a {@code java.io.InputStream} object containing the 118 * {@code CLOB} data 119 * @exception SQLException if there is an error accessing the 120 * {@code CLOB} value 121 * @exception SQLFeatureNotSupportedException if the JDBC driver 122 * does not support 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} appears in the SQL {@code CLOB} value 131 * represented by this {@code Clob} object. The search 132 * begins at position {@code start}. 133 * 134 * @param searchstr the substring for which to search 135 * @param start the position at which to begin searching; 136 * the first position 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} value or if pos is less than 1 141 * @exception SQLFeatureNotSupportedException if the JDBC driver 142 * does not support 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} object {@code searchstr} appears in this 150 * {@code Clob} object. The search begins at position 151 * {@code start}. 152 * 153 * @param searchstr the {@code Clob} 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} 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} value or if start is less than 1 160 * @exception SQLFeatureNotSupportedException if the JDBC driver 161 * does not support 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} to the {@code CLOB} 170 * value that this {@code Clob} object designates at the position 171 * {@code pos}. The string will overwrite the existing characters 172 * in the {@code Clob} object starting at the position 173 * {@code pos}. If the end of the {@code Clob} value is reached 174 * while writing the given string, then the length of the {@code Clob} 175 * value will be increased to accommodate the extra characters. 176 * <p> 177 * <b>Note:</b> If the value specified for {@code pos} 178 * is greater than the length+1 of the {@code CLOB} value then the 179 * behavior is undefined. Some JDBC drivers may throw an 180 * {@code SQLException} while other drivers may support this 181 * operation. 182 * 183 * @param pos the position at which to start writing to the {@code CLOB} 184 * value that this {@code Clob} object represents; 185 * the first position is 1. 186 * @param str the string to be written to the {@code CLOB} 187 * value that this {@code Clob} designates 188 * @return the number of characters written 189 * @exception SQLException if there is an error accessing the 190 * {@code CLOB} value or if pos is less than 1 191 * 192 * @exception SQLFeatureNotSupportedException if the JDBC driver 193 * does not support this method 194 * @since 1.4 195 */ 196 int setString(long pos, String str) throws SQLException; 197 198 /** 199 * Writes {@code len} characters of {@code str}, starting 200 * at character {@code offset}, to the {@code CLOB} value 201 * that this {@code Clob} represents. 202 * The string will overwrite the existing characters 203 * in the {@code Clob} object starting at the position 204 * {@code pos}. If the end of the {@code Clob} value is reached 205 * while writing the given string, then the length of the {@code Clob} 206 * value will be increased to accommodate the extra characters. 207 * <p> 208 * <b>Note:</b> If the value specified for {@code pos} 209 * is greater than the length+1 of the {@code CLOB} value then the 210 * behavior is undefined. Some JDBC drivers may throw an 211 * {@code SQLException} while other drivers may support this 212 * operation. 213 * 214 * @param pos the position at which to start writing to this 215 * {@code CLOB} object; The first position is 1 216 * @param str the string to be written to the {@code CLOB} 217 * value that this {@code Clob} object represents 218 * @param offset the offset into {@code str} to start reading 219 * the characters to be written 220 * @param len the number of characters to be written 221 * @return the number of characters written 222 * @exception SQLException if there is an error accessing the 223 * {@code CLOB} value or if pos is less than 1 224 * 225 * @exception SQLFeatureNotSupportedException if the JDBC driver 226 * does not support this method 227 * @since 1.4 228 */ 229 int setString(long pos, String str, int offset, int len) throws SQLException; 230 231 /** 232 * Retrieves a stream to be used to write Ascii characters to the 233 * {@code CLOB} value that this {@code Clob} object represents, 234 * starting at position {@code pos}. Characters written to the stream 235 * will overwrite the existing characters 236 * in the {@code Clob} object starting at the position 237 * {@code pos}. If the end of the {@code Clob} value is reached 238 * while writing characters to the stream, then the length of the {@code Clob} 239 * value will be increased to accommodate the extra characters. 240 * <p> 241 * <b>Note:</b> If the value specified for {@code pos} 242 * is greater than the length+1 of the {@code CLOB} value then the 243 * behavior is undefined. Some JDBC drivers may throw an 244 * {@code SQLException} while other drivers may support this 245 * operation. 246 * 247 * @param pos the position at which to start writing to this 248 * {@code CLOB} object; The first position is 1 249 * @return the stream to which ASCII encoded characters can be written 250 * @exception SQLException if there is an error accessing the 251 * {@code CLOB} value or if pos is less than 1 252 * @exception SQLFeatureNotSupportedException if the JDBC driver 253 * does not support this method 254 * @see #getAsciiStream 255 * 256 * @since 1.4 257 */ 258 java.io.OutputStream setAsciiStream(long pos) throws SQLException; 259 260 /** 261 * Retrieves a stream to be used to write a stream of Unicode characters 262 * to the {@code CLOB} value that this {@code Clob} object 263 * represents, at position {@code pos}. Characters written to the stream 264 * will overwrite the existing characters 265 * in the {@code Clob} object starting at the position 266 * {@code pos}. If the end of the {@code Clob} value is reached 267 * while writing characters to the stream, then the length of the {@code Clob} 268 * value will be increased to accommodate the extra characters. 269 * <p> 270 * <b>Note:</b> If the value specified for {@code pos} 271 * is greater than the length+1 of the {@code CLOB} value then the 272 * behavior is undefined. Some JDBC drivers may throw an 273 * {@code SQLException} while other drivers may support this 274 * operation. 275 * 276 * @param pos the position at which to start writing to the 277 * {@code CLOB} value; The first position is 1 278 * 279 * @return a stream to which Unicode encoded characters can be written 280 * @exception SQLException if there is an error accessing the 281 * {@code CLOB} value or if pos is less than 1 282 * @exception SQLFeatureNotSupportedException if the JDBC driver 283 * does not support this method 284 * @see #getCharacterStream 285 * 286 * @since 1.4 287 */ 288 java.io.Writer setCharacterStream(long pos) throws SQLException; 289 290 /** 291 * Truncates the {@code CLOB} value that this {@code Clob} 292 * designates to have a length of {@code len} 293 * characters. 294 * <p> 295 * <b>Note:</b> If the value specified for {@code pos} 296 * is greater than the length+1 of the {@code CLOB} value then the 297 * behavior is undefined. Some JDBC drivers may throw an 298 * {@code SQLException} while other drivers may support this 299 * operation. 300 * 301 * @param len the length, in characters, to which the {@code CLOB} value 302 * should be truncated 303 * @exception SQLException if there is an error accessing the 304 * {@code CLOB} value or if len is less than 0 305 * 306 * @exception SQLFeatureNotSupportedException if the JDBC driver 307 * does not support this method 308 * @since 1.4 309 */ 310 void truncate(long len) throws SQLException; 311 312 /** 313 * This method releases the resources that the {@code Clob} object 314 * holds. The object is invalid once the {@code free} method 315 * is called. 316 * <p> 317 * After {@code free} has been called, any attempt to invoke a 318 * method other than {@code free} will result in a {@code SQLException} 319 * being thrown. If {@code free} is called multiple times, the subsequent 320 * calls to {@code free} are treated as a no-op. 321 * 322 * @throws SQLException if an error occurs releasing 323 * the Clob's resources 324 * 325 * @exception SQLFeatureNotSupportedException if the JDBC driver 326 * does not support this method 327 * @since 1.6 328 */ 329 void free() throws SQLException; 330 331 /** 332 * Returns a {@code Reader} object that contains 333 * a partial {@code Clob} value, starting with the character 334 * specified by pos, which is length characters in length. 335 * 336 * @param pos the offset to the first character of the partial value to 337 * be retrieved. The first character in the Clob is at position 1. 338 * @param length the length in characters of the partial value to be retrieved. 339 * @return {@code Reader} through which 340 * the partial {@code Clob} value can be read. 341 * @throws SQLException if pos is less than 1; 342 * or if pos is greater than the number of characters 343 * in the {@code Clob}; 344 * or if pos + length is greater than the number of 345 * characters in the {@code Clob} 346 * 347 * @exception SQLFeatureNotSupportedException if the JDBC driver 348 * does not support this method 349 * @since 1.6 350 */ 351 Reader getCharacterStream(long pos, long length) throws SQLException; 352 353 }