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