1 /*
2 * Copyright 1998-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 */
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 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) 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 */
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 */
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 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 */
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 }
Save This Page