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 /**
029 * An input stream that contains a stream of values representing an
030 * instance of an SQL structured type or an SQL distinct type.
031 * This interface, used only for custom mapping, is used by the driver
032 * behind the scenes, and a programmer never directly invokes
033 * <code>SQLInput</code> methods. The <i>reader</i> methods
034 * (<code>readLong</code>, <code>readBytes</code>, and so on)
035 * provide a way for an implementation of the <code>SQLData</code>
036 * interface to read the values in an <code>SQLInput</code> object.
037 * And as described in <code>SQLData</code>, calls to reader methods must
038 * be made in the order that their corresponding attributes appear in the
039 * SQL definition of the type.
040 * The method <code>wasNull</code> is used to determine whether
041 * the last value read was SQL <code>NULL</code>.
042 * <P>When the method <code>getObject</code> is called with an
043 * object of a class implementing the interface <code>SQLData</code>,
044 * the JDBC driver calls the method <code>SQLData.getSQLType</code>
045 * to determine the SQL type of the user-defined type (UDT)
046 * being custom mapped. The driver
047 * creates an instance of <code>SQLInput</code>, populating it with the
048 * attributes of the UDT. The driver then passes the input
049 * stream to the method <code>SQLData.readSQL</code>, which in turn
050 * calls the <code>SQLInput</code> reader methods
051 * in its implementation for reading the
052 * attributes from the input stream.
053 * @since 1.2
054 */
055
056 public interface SQLInput {
057
058 //================================================================
059 // Methods for reading attributes from the stream of SQL data.
060 // These methods correspond to the column-accessor methods of
061 // java.sql.ResultSet.
062 //================================================================
063
064 /**
065 * Reads the next attribute in the stream and returns it as a <code>String</code>
066 * in the Java programming language.
067 *
068 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
069 * @exception SQLException if a database access error occurs
070 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
071 * this method
072 * @since 1.2
073 */
074 String readString() throws SQLException;
075
076 /**
077 * Reads the next attribute in the stream and returns it as a <code>boolean</code>
078 * in the Java programming language.
079 *
080 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>false</code>
081 * @exception SQLException if a database access error occurs
082 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
083 * this method
084 * @since 1.2
085 */
086 boolean readBoolean() throws SQLException;
087
088 /**
089 * Reads the next attribute in the stream and returns it as a <code>byte</code>
090 * in the Java programming language.
091 *
092 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
093 * @exception SQLException if a database access error occurs
094 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
095 * this method
096 * @since 1.2
097 */
098 byte readByte() throws SQLException;
099
100 /**
101 * Reads the next attribute in the stream and returns it as a <code>short</code>
102 * in the Java programming language.
103 *
104 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
105 * @exception SQLException if a database access error occurs
106 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
107 * this method
108 * @since 1.2
109 */
110 short readShort() throws SQLException;
111
112 /**
113 * Reads the next attribute in the stream and returns it as an <code>int</code>
114 * in the Java programming language.
115 *
116 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
117 * @exception SQLException if a database access error occurs
118 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
119 * this method
120 * @since 1.2
121 */
122 int readInt() throws SQLException;
123
124 /**
125 * Reads the next attribute in the stream and returns it as a <code>long</code>
126 * in the Java programming language.
127 *
128 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
129 * @exception SQLException if a database access error occurs
130 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
131 * this method
132 * @since 1.2
133 */
134 long readLong() throws SQLException;
135
136 /**
137 * Reads the next attribute in the stream and returns it as a <code>float</code>
138 * in the Java programming language.
139 *
140 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
141 * @exception SQLException if a database access error occurs
142 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
143 * this method
144 * @since 1.2
145 */
146 float readFloat() throws SQLException;
147
148 /**
149 * Reads the next attribute in the stream and returns it as a <code>double</code>
150 * in the Java programming language.
151 *
152 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
153 * @exception SQLException if a database access error occurs
154 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
155 * this method
156 * @since 1.2
157 */
158 double readDouble() throws SQLException;
159
160 /**
161 * Reads the next attribute in the stream and returns it as a <code>java.math.BigDecimal</code>
162 * object in the Java programming language.
163 *
164 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
165 * @exception SQLException if a database access error occurs
166 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
167 * this method
168 * @since 1.2
169 */
170 java.math.BigDecimal readBigDecimal() throws SQLException;
171
172 /**
173 * Reads the next attribute in the stream and returns it as an array of bytes
174 * in the Java programming language.
175 *
176 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
177 * @exception SQLException if a database access error occurs
178 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
179 * this method
180 * @since 1.2
181 */
182 byte[] readBytes() throws SQLException;
183
184 /**
185 * Reads the next attribute in the stream and returns it as a <code>java.sql.Date</code> object.
186 *
187 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
188 * @exception SQLException if a database access error occurs
189 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
190 * this method
191 * @since 1.2
192 */
193 java.sql.Date readDate() throws SQLException;
194
195 /**
196 * Reads the next attribute in the stream and returns it as a <code>java.sql.Time</code> object.
197 *
198 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
199 * @exception SQLException if a database access error occurs
200 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
201 * this method
202 * @since 1.2
203 */
204 java.sql.Time readTime() throws SQLException;
205
206 /**
207 * Reads the next attribute in the stream and returns it as a <code>java.sql.Timestamp</code> object.
208 *
209 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
210 * @exception SQLException if a database access error occurs
211 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
212 * this method
213 * @since 1.2
214 */
215 java.sql.Timestamp readTimestamp() throws SQLException;
216
217 /**
218 * Reads the next attribute in the stream and returns it as a stream of Unicode characters.
219 *
220 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
221 * @exception SQLException if a database access error occurs
222 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
223 * this method
224 * @since 1.2
225 */
226 java.io.Reader readCharacterStream() throws SQLException;
227
228 /**
229 * Reads the next attribute in the stream and returns it as a stream of ASCII characters.
230 *
231 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
232 * @exception SQLException if a database access error occurs
233 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
234 * this method
235 * @since 1.2
236 */
237 java.io.InputStream readAsciiStream() throws SQLException;
238
239 /**
240 * Reads the next attribute in the stream and returns it as a stream of uninterpreted
241 * bytes.
242 *
243 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
244 * @exception SQLException if a database access error occurs
245 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
246 * this method
247 * @since 1.2
248 */
249 java.io.InputStream readBinaryStream() throws SQLException;
250
251 //================================================================
252 // Methods for reading items of SQL user-defined types from the stream.
253 //================================================================
254
255 /**
256 * Reads the datum at the head of the stream and returns it as an
257 * <code>Object</code> in the Java programming language. The
258 * actual type of the object returned is determined by the default type
259 * mapping, and any customizations present in this stream's type map.
260 *
261 * <P>A type map is registered with the stream by the JDBC driver before the
262 * stream is passed to the application.
263 *
264 * <P>When the datum at the head of the stream is an SQL <code>NULL</code>,
265 * the method returns <code>null</code>. If the datum is an SQL structured or distinct
266 * type, it determines the SQL type of the datum at the head of the stream.
267 * If the stream's type map has an entry for that SQL type, the driver
268 * constructs an object of the appropriate class and calls the method
269 * <code>SQLData.readSQL</code> on that object, which reads additional data from the
270 * stream, using the protocol described for that method.
271 *
272 * @return the datum at the head of the stream as an <code>Object</code> in the
273 * Java programming language;<code>null</code> if the datum is SQL <code>NULL</code>
274 * @exception SQLException if a database access error occurs
275 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
276 * this method
277 * @since 1.2
278 */
279 Object readObject() throws SQLException;
280
281 /**
282 * Reads an SQL <code>REF</code> value from the stream and returns it as a
283 * <code>Ref</code> object in the Java programming language.
284 *
285 * @return a <code>Ref</code> object representing the SQL <code>REF</code> value
286 * at the head of the stream; <code>null</code> if the value read is
287 * SQL <code>NULL</code>
288 * @exception SQLException if a database access error occurs
289 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
290 * this method
291 * @since 1.2
292 */
293 Ref readRef() throws SQLException;
294
295 /**
296 * Reads an SQL <code>BLOB</code> value from the stream and returns it as a
297 * <code>Blob</code> object in the Java programming language.
298 *
299 * @return a <code>Blob</code> object representing data of the SQL <code>BLOB</code> value
300 * at the head of the stream; <code>null</code> if the value read is
301 * SQL <code>NULL</code>
302 * @exception SQLException if a database access error occurs
303 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
304 * this method
305 * @since 1.2
306 */
307 Blob readBlob() throws SQLException;
308
309 /**
310 * Reads an SQL <code>CLOB</code> value from the stream and returns it as a
311 * <code>Clob</code> object in the Java programming language.
312 *
313 * @return a <code>Clob</code> object representing data of the SQL <code>CLOB</code> value
314 * at the head of the stream; <code>null</code> if the value read is
315 * SQL <code>NULL</code>
316 * @exception SQLException if a database access error occurs
317 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
318 * this method
319 * @since 1.2
320 */
321 Clob readClob() throws SQLException;
322
323 /**
324 * Reads an SQL <code>ARRAY</code> value from the stream and returns it as an
325 * <code>Array</code> object in the Java programming language.
326 *
327 * @return an <code>Array</code> object representing data of the SQL
328 * <code>ARRAY</code> value at the head of the stream; <code>null</code>
329 * if the value read is SQL <code>NULL</code>
330 * @exception SQLException if a database access error occurs
331 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
332 * this method
333 * @since 1.2
334 */
335 Array readArray() throws SQLException;
336
337 /**
338 * Retrieves whether the last value read was SQL <code>NULL</code>.
339 *
340 * @return <code>true</code> if the most recently read SQL value was SQL
341 * <code>NULL</code>; <code>false</code> otherwise
342 * @exception SQLException if a database access error occurs
343 *
344 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
345 * this method
346 * @since 1.2
347 */
348 boolean wasNull() throws SQLException;
349
350 //---------------------------- JDBC 3.0 -------------------------
351
352 /**
353 * Reads an SQL <code>DATALINK</code> value from the stream and returns it as a
354 * <code>java.net.URL</code> object in the Java programming language.
355 *
356 * @return a <code>java.net.URL</code> object.
357 * @exception SQLException if a database access error occurs,
358 * or if a URL is malformed
359 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
360 * this method
361 * @since 1.4
362 */
363 java.net.URL readURL() throws SQLException;
364
365 //---------------------------- JDBC 4.0 -------------------------
366
367 /**
368 * Reads an SQL <code>NCLOB</code> value from the stream and returns it as a
369 * <code>NClob</code> object in the Java programming language.
370 *
371 * @return a <code>NClob</code> object representing data of the SQL <code>NCLOB</code> value
372 * at the head of the stream; <code>null</code> if the value read is
373 * SQL <code>NULL</code>
374 * @exception SQLException if a database access error occurs
375 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
376 * this method
377 * @since 1.6
378 */
379 NClob readNClob() throws SQLException;
380
381 /**
382 * Reads the next attribute in the stream and returns it as a <code>String</code>
383 * in the Java programming language. It is intended for use when
384 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
385 * and <code>LONGNVARCHAR</code> columns.
386 *
387 * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
388 * @exception SQLException if a database access error occurs
389 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
390 * this method
391 * @since 1.6
392 */
393 String readNString() throws SQLException;
394
395 /**
396 * Reads an SQL <code>XML</code> value from the stream and returns it as a
397 * <code>SQLXML</code> object in the Java programming language.
398 *
399 * @return a <code>SQLXML</code> object representing data of the SQL <code>XML</code> value
400 * at the head of the stream; <code>null</code> if the value read is
401 * SQL <code>NULL</code>
402 * @exception SQLException if a database access error occurs
403 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
404 * this method
405 * @since 1.6
406 */
407 SQLXML readSQLXML() throws SQLException;
408
409 /**
410 * Reads an SQL <code>ROWID</code> value from the stream and returns it as a
411 * <code>RowId</code> object in the Java programming language.
412 *
413 * @return a <code>RowId</code> object representing data of the SQL <code>ROWID</code> value
414 * at the head of the stream; <code>null</code> if the value read is
415 * SQL <code>NULL</code>
416 * @exception SQLException if a database access error occurs
417 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
418 * this method
419 * @since 1.6
420 */
421 RowId readRowId() throws SQLException;
422
423 }
|