001 /*
002 * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.sql;
027
028 import java.io.Reader;
029
030 /**
031 * The mapping in the Java<sup><font size=-2>TM</font></sup> programming language
032 * for the SQL <code>CLOB</code> type.
033 * An SQL <code>CLOB</code> is a built-in type
034 * that stores a Character Large Object as a column value in a row of
035 * a database table.
036 * By default drivers implement a <code>Clob</code> object using an SQL
037 * <code>locator(CLOB)</code>, which means that a <code>Clob</code> object
038 * contains a logical pointer to the SQL <code>CLOB</code> data rather than
039 * the data itself. A <code>Clob</code> object is valid for the duration
040 * of the transaction in which it was created.
041 * <P>The <code>Clob</code> interface provides methods for getting the
042 * length of an SQL <code>CLOB</code> (Character Large Object) value,
043 * for materializing a <code>CLOB</code> value on the client, and for
044 * searching for a substring or <code>CLOB</code> object within a
045 * <code>CLOB</code> value.
046 * Methods in the interfaces {@link ResultSet},
047 * {@link CallableStatement}, and {@link PreparedStatement}, such as
048 * <code>getClob</code> and <code>setClob</code> allow a programmer to
049 * access an SQL <code>CLOB</code> value. In addition, this interface
050 * has methods for updating a <code>CLOB</code> value.
051 * <p>
052 * All methods on the <code>Clob</code> interface must be fully implemented if the
053 * JDBC driver supports the data type.
054 *
055 * @since 1.2
056 */
057
058 public interface Clob {
059
060 /**
061 * Retrieves the number of characters
062 * in the <code>CLOB</code> value
063 * designated by this <code>Clob</code> object.
064 *
065 * @return length of the <code>CLOB</code> in characters
066 * @exception SQLException if there is an error accessing the
067 * length of the <code>CLOB</code> value
068 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
069 * this method
070 * @since 1.2
071 */
072 long length() throws SQLException;
073
074 /**
075 * Retrieves a copy of the specified substring
076 * in the <code>CLOB</code> value
077 * designated by this <code>Clob</code> object.
078 * The substring begins at position
079 * <code>pos</code> and has up to <code>length</code> consecutive
080 * characters.
081 *
082 * @param pos the first character of the substring to be extracted.
083 * The first character is at position 1.
084 * @param length the number of consecutive characters to be copied;
085 * the value for length must be 0 or greater
086 * @return a <code>String</code> that is the specified substring in
087 * the <code>CLOB</code> value designated by this <code>Clob</code> object
088 * @exception SQLException if there is an error accessing the
089 * <code>CLOB</code> value; if pos is less than 1 or length is
090 * less than 0
091 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
092 * this method
093 * @since 1.2
094 */
095 String getSubString(long pos, int length) throws SQLException;
096
097 /**
098 * Retrieves the <code>CLOB</code> value designated by this <code>Clob</code>
099 * 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 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 */
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 */
228 int setString(long pos, String str, int offset, int len)
229 throws SQLException;
230
231 /**
232 * Retrieves a stream to be used to write Ascii characters to the
233 * <code>CLOB</code> value that this <code>Clob</code> object represents,
234 * starting at position <code>pos</code>. Characters written to the stream
235 * will overwrite the existing characters
236 * in the <code>Clob</code> object starting at the position
237 * <code>pos</code>. If the end of the <code>Clob</code> value is reached
238 * while writing characters to the stream, then the length of the <code>Clob</code>
239 * value will be increased to accomodate the extra characters.
240 * <p>
241 * <b>Note:</b> If the value specified for <code>pos</code>
242 * is greater then the length+1 of the <code>CLOB</code> value then the
243 * behavior is undefined. Some JDBC drivers may throw a
244 * <code>SQLException</code> while other drivers may support this
245 * operation.
246 *
247 * @param pos the position at which to start writing to this
248 * <code>CLOB</code> 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</code> value or if pos is less than 1
252 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
253 * 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</code> value that this <code>Clob</code> object
263 * represents, at position <code>pos</code>. Characters written to the stream
264 * will overwrite the existing characters
265 * in the <code>Clob</code> object starting at the position
266 * <code>pos</code>. If the end of the <code>Clob</code> value is reached
267 * while writing characters to the stream, then the length of the <code>Clob</code>
268 * value will be increased to accomodate the extra characters.
269 * <p>
270 * <b>Note:</b> If the value specified for <code>pos</code>
271 * is greater then the length+1 of the <code>CLOB</code> value then the
272 * behavior is undefined. Some JDBC drivers may throw a
273 * <code>SQLException</code> while other drivers may support this
274 * operation.
275 *
276 * @param pos the position at which to start writing to the
277 * <code>CLOB</code> 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</code> value or if pos is less than 1
282 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
283 * 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</code> value that this <code>Clob</code>
292 * designates to have a length of <code>len</code>
293 * characters.
294 * <p>
295 * <b>Note:</b> If the value specified for <code>pos</code>
296 * is greater then the length+1 of the <code>CLOB</code> value then the
297 * behavior is undefined. Some JDBC drivers may throw a
298 * <code>SQLException</code> while other drivers may support this
299 * operation.
300 *
301 * @param len the length, in characters, to which the <code>CLOB</code> value
302 * should be truncated
303 * @exception SQLException if there is an error accessing the
304 * <code>CLOB</code> value or if len is less than 0
305 *
306 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
307 * this method
308 * @since 1.4
309 */
310 void truncate(long len) throws SQLException;
311
312 /**
313 * This method frees the <code>Clob</code> object and releases the resources the resources
314 * that it holds. The object is invalid once the <code>free</code> method
315 * is called.
316 * <p>
317 * After <code>free</code> has been called, any attempt to invoke a
318 * method other than <code>free</code> will result in a <code>SQLException</code>
319 * being thrown. If <code>free</code> is called multiple times, the subsequent
320 * calls to <code>free</code> are treated as a no-op.
321 * <p>
322 * @throws SQLException if an error occurs releasing
323 * the Clob's resources
324 *
325 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
326 * this method
327 * @since 1.6
328 */
329 void free() throws SQLException;
330
331 /**
332 * Returns a <code>Reader</code> object that contains a partial <code>Clob</code> value, starting
333 * with the character specified by pos, which is length characters in length.
334 *
335 * @param pos the offset to the first character of the partial value to
336 * be retrieved. The first character in the Clob is at position 1.
337 * @param length the length in characters of the partial value to be retrieved.
338 * @return <code>Reader</code> through which the partial <code>Clob</code> value can be read.
339 * @throws SQLException if pos is less than 1 or if pos is greater than the number of
340 * characters in the <code>Clob</code> or if pos + length is greater than the number of
341 * characters in the <code>Clob</code>
342 *
343 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
344 * this method
345 * @since 1.6
346 */
347 Reader getCharacterStream(long pos, long length)
348 throws SQLException;
349
350 }
|