1 /*
2 * Copyright (c) 1998, 2006, 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 /**
29 * An input stream that contains a stream of values representing an
30 * instance of an SQL structured type or an SQL distinct type.
31 * This interface, used only for custom mapping, is used by the driver
32 * behind the scenes, and a programmer never directly invokes
33 * <code>SQLInput</code> methods. The <i>reader</i> methods
34 * (<code>readLong</code>, <code>readBytes</code>, and so on)
35 * provide a way for an implementation of the <code>SQLData</code>
36 * interface to read the values in an <code>SQLInput</code> object.
37 * And as described in <code>SQLData</code>, calls to reader methods must
38 * be made in the order that their corresponding attributes appear in the
39 * SQL definition of the type.
40 * The method <code>wasNull</code> is used to determine whether
41 * the last value read was SQL <code>NULL</code>.
42 * <P>When the method <code>getObject</code> is called with an
43 * object of a class implementing the interface <code>SQLData</code>,
44 * the JDBC driver calls the method <code>SQLData.getSQLType</code>
45 * to determine the SQL type of the user-defined type (UDT)
46 * being custom mapped. The driver
47 * creates an instance of <code>SQLInput</code>, populating it with the
48 * attributes of the UDT. The driver then passes the input
49 * stream to the method <code>SQLData.readSQL</code>, which in turn
50 * calls the <code>SQLInput</code> reader methods
51 * in its implementation for reading the
52 * attributes from the input stream.
53 * @since 1.2
54 */
55
56 public interface SQLInput {
57
58
59 //================================================================
60 // Methods for reading attributes from the stream of SQL data.
61 // These methods correspond to the column-accessor methods of
62 // java.sql.ResultSet.
63 //================================================================
64
65 /**
66 * Reads the next attribute in the stream and returns it as a <code>String</code>
67 * in the Java programming language.
68 *
69 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
70 * @exception SQLException if a database access error occurs
71 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
72 * this method
73 * @since 1.2
74 */
75 String readString() throws SQLException;
76
77 /**
78 * Reads the next attribute in the stream and returns it as a <code>boolean</code>
79 * in the Java programming language.
80 *
81 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>false</code>
82 * @exception SQLException if a database access error occurs
83 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
84 * this method
85 * @since 1.2
86 */
87 boolean readBoolean() throws SQLException;
88
89 /**
90 * Reads the next attribute in the stream and returns it as a <code>byte</code>
91 * in the Java programming language.
92 *
93 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
94 * @exception SQLException if a database access error occurs
95 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
96 * this method
97 * @since 1.2
98 */
99 byte readByte() throws SQLException;
100
101 /**
102 * Reads the next attribute in the stream and returns it as a <code>short</code>
103 * in the Java programming language.
104 *
105 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
106 * @exception SQLException if a database access error occurs
107 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
108 * this method
109 * @since 1.2
110 */
111 short readShort() throws SQLException;
112
113 /**
114 * Reads the next attribute in the stream and returns it as an <code>int</code>
115 * in the Java programming language.
116 *
117 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
118 * @exception SQLException if a database access error occurs
119 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
120 * this method
121 * @since 1.2
122 */
123 int readInt() throws SQLException;
124
125 /**
126 * Reads the next attribute in the stream and returns it as a <code>long</code>
127 * in the Java programming language.
128 *
129 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
130 * @exception SQLException if a database access error occurs
131 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
132 * this method
133 * @since 1.2
134 */
135 long readLong() throws SQLException;
136
137 /**
138 * Reads the next attribute in the stream and returns it as a <code>float</code>
139 * in the Java programming language.
140 *
141 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
142 * @exception SQLException if a database access error occurs
143 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
144 * this method
145 * @since 1.2
146 */
147 float readFloat() throws SQLException;
148
149 /**
150 * Reads the next attribute in the stream and returns it as a <code>double</code>
151 * in the Java programming language.
152 *
153 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
154 * @exception SQLException if a database access error occurs
155 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
156 * this method
157 * @since 1.2
158 */
159 double readDouble() throws SQLException;
160
161 /**
162 * Reads the next attribute in the stream and returns it as a <code>java.math.BigDecimal</code>
163 * object in the Java programming language.
164 *
165 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
166 * @exception SQLException if a database access error occurs
167 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
168 * this method
169 * @since 1.2
170 */
171 java.math.BigDecimal readBigDecimal() throws SQLException;
172
173 /**
174 * Reads the next attribute in the stream and returns it as an array of bytes
175 * in the Java programming language.
176 *
177 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
178 * @exception SQLException if a database access error occurs
179 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
180 * this method
181 * @since 1.2
182 */
183 byte[] readBytes() throws SQLException;
184
185 /**
186 * Reads the next attribute in the stream and returns it as a <code>java.sql.Date</code> object.
187 *
188 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
189 * @exception SQLException if a database access error occurs
190 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
191 * this method
192 * @since 1.2
193 */
194 java.sql.Date readDate() throws SQLException;
195
196 /**
197 * Reads the next attribute in the stream and returns it as a <code>java.sql.Time</code> object.
198 *
199 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
200 * @exception SQLException if a database access error occurs
201 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
202 * this method
203 * @since 1.2
204 */
205 java.sql.Time readTime() throws SQLException;
206
207 /**
208 * Reads the next attribute in the stream and returns it as a <code>java.sql.Timestamp</code> object.
209 *
210 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
211 * @exception SQLException if a database access error occurs
212 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
213 * this method
214 * @since 1.2
215 */
216 java.sql.Timestamp readTimestamp() throws SQLException;
217
218 /**
219 * Reads the next attribute in the stream and returns it as a stream of Unicode characters.
220 *
221 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
222 * @exception SQLException if a database access error occurs
223 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
224 * this method
225 * @since 1.2
226 */
227 java.io.Reader readCharacterStream() throws SQLException;
228
229 /**
230 * Reads the next attribute in the stream and returns it as a stream of ASCII characters.
231 *
232 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
233 * @exception SQLException if a database access error occurs
234 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
235 * this method
236 * @since 1.2
237 */
238 java.io.InputStream readAsciiStream() throws SQLException;
239
240 /**
241 * Reads the next attribute in the stream and returns it as a stream of uninterpreted
242 * bytes.
243 *
244 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
245 * @exception SQLException if a database access error occurs
246 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
247 * this method
248 * @since 1.2
249 */
250 java.io.InputStream readBinaryStream() throws SQLException;
251
252 //================================================================
253 // Methods for reading items of SQL user-defined types from the stream.
254 //================================================================
255
256 /**
257 * Reads the datum at the head of the stream and returns it as an
258 * <code>Object</code> in the Java programming language. The
259 * actual type of the object returned is determined by the default type
260 * mapping, and any customizations present in this stream's type map.
261 *
262 * <P>A type map is registered with the stream by the JDBC driver before the
263 * stream is passed to the application.
264 *
265 * <P>When the datum at the head of the stream is an SQL <code>NULL</code>,
266 * the method returns <code>null</code>. If the datum is an SQL structured or distinct
267 * type, it determines the SQL type of the datum at the head of the stream.
268 * If the stream's type map has an entry for that SQL type, the driver
269 * constructs an object of the appropriate class and calls the method
270 * <code>SQLData.readSQL</code> on that object, which reads additional data from the
271 * stream, using the protocol described for that method.
272 *
273 * @return the datum at the head of the stream as an <code>Object</code> in the
274 * Java programming language;<code>null</code> if the datum is SQL <code>NULL</code>
275 * @exception SQLException if a database access error occurs
276 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
277 * this method
278 * @since 1.2
279 */
280 Object readObject() throws SQLException;
281
282 /**
283 * Reads an SQL <code>REF</code> value from the stream and returns it as a
284 * <code>Ref</code> object in the Java programming language.
285 *
286 * @return a <code>Ref</code> object representing the SQL <code>REF</code> value
287 * at the head of the stream; <code>null</code> if the value read is
288 * SQL <code>NULL</code>
289 * @exception SQLException if a database access error occurs
290 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
291 * this method
292 * @since 1.2
293 */
294 Ref readRef() throws SQLException;
295
296 /**
297 * Reads an SQL <code>BLOB</code> value from the stream and returns it as a
298 * <code>Blob</code> object in the Java programming language.
299 *
300 * @return a <code>Blob</code> object representing data of the SQL <code>BLOB</code> value
301 * at the head of the stream; <code>null</code> if the value read is
302 * SQL <code>NULL</code>
303 * @exception SQLException if a database access error occurs
304 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
305 * this method
306 * @since 1.2
307 */
308 Blob readBlob() throws SQLException;
309
310 /**
311 * Reads an SQL <code>CLOB</code> value from the stream and returns it as a
312 * <code>Clob</code> object in the Java programming language.
313 *
314 * @return a <code>Clob</code> object representing data of the SQL <code>CLOB</code> value
315 * at the head of the stream; <code>null</code> if the value read is
316 * SQL <code>NULL</code>
317 * @exception SQLException if a database access error occurs
318 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
319 * this method
320 * @since 1.2
321 */
322 Clob readClob() throws SQLException;
323
324 /**
325 * Reads an SQL <code>ARRAY</code> value from the stream and returns it as an
326 * <code>Array</code> object in the Java programming language.
327 *
328 * @return an <code>Array</code> object representing data of the SQL
329 * <code>ARRAY</code> value at the head of the stream; <code>null</code>
330 * if the value read is SQL <code>NULL</code>
331 * @exception SQLException if a database access error occurs
332 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
333 * this method
334 * @since 1.2
335 */
336 Array readArray() throws SQLException;
337
338 /**
339 * Retrieves whether the last value read was SQL <code>NULL</code>.
340 *
341 * @return <code>true</code> if the most recently read SQL value was SQL
342 * <code>NULL</code>; <code>false</code> otherwise
343 * @exception SQLException if a database access error occurs
344 *
345 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
346 * this method
347 * @since 1.2
348 */
349 boolean wasNull() throws SQLException;
350
351 //---------------------------- JDBC 3.0 -------------------------
352
353 /**
354 * Reads an SQL <code>DATALINK</code> value from the stream and returns it as a
355 * <code>java.net.URL</code> object in the Java programming language.
356 *
357 * @return a <code>java.net.URL</code> object.
358 * @exception SQLException if a database access error occurs,
359 * or if a URL is malformed
360 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
361 * this method
362 * @since 1.4
363 */
364 java.net.URL readURL() throws SQLException;
365
366 //---------------------------- JDBC 4.0 -------------------------
367
368 /**
369 * Reads an SQL <code>NCLOB</code> value from the stream and returns it as a
370 * <code>NClob</code> object in the Java programming language.
371 *
372 * @return a <code>NClob</code> object representing data of the SQL <code>NCLOB</code> value
373 * at the head of the stream; <code>null</code> if the value read is
374 * SQL <code>NULL</code>
375 * @exception SQLException if a database access error occurs
376 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
377 * this method
378 * @since 1.6
379 */
380 NClob readNClob() throws SQLException;
381
382 /**
383 * Reads the next attribute in the stream and returns it as a <code>String</code>
384 * in the Java programming language. It is intended for use when
385 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
386 * and <code>LONGNVARCHAR</code> columns.
387 *
388 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
389 * @exception SQLException if a database access error occurs
390 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
391 * this method
392 * @since 1.6
393 */
394 String readNString() throws SQLException;
395
396 /**
397 * Reads an SQL <code>XML</code> value from the stream and returns it as a
398 * <code>SQLXML</code> object in the Java programming language.
399 *
400 * @return a <code>SQLXML</code> object representing data of the SQL <code>XML</code> value
401 * at the head of the stream; <code>null</code> if the value read is
402 * SQL <code>NULL</code>
403 * @exception SQLException if a database access error occurs
404 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
405 * this method
406 * @since 1.6
407 */
408 SQLXML readSQLXML() throws SQLException;
409
410 /**
411 * Reads an SQL <code>ROWID</code> value from the stream and returns it as a
412 * <code>RowId</code> object in the Java programming language.
413 *
414 * @return a <code>RowId</code> object representing data of the SQL <code>ROWID</code> value
415 * at the head of the stream; <code>null</code> if the value read is
416 * SQL <code>NULL</code>
417 * @exception SQLException if a database access error occurs
418 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
419 * this method
420 * @since 1.6
421 */
422 RowId readRowId() throws SQLException;
423
424 }