|
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 } |