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
26package 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
56public 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}
425