View Javadoc
1   /*
2    * Copyright (c) 1998, 2013, 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     //--------------------------JDBC 4.2 -----------------------------
425 
426     /**
427      * Reads the next attribute in the stream and returns it as an
428      * {@code Object} in the Java programming language. The
429      * actual type of the object returned is determined by the specified
430      * Java data type, and any customizations present in this
431      * stream's type map.
432      *
433      * <P>A type map is registered with the stream by the JDBC driver before the
434      * stream is passed to the application.
435      *
436      * <P>When the attribute at the head of the stream is an SQL {@code NULL}
437      * the method returns {@code null}. If the attribute is an SQL
438      * structured or distinct
439      * type, it determines the SQL type of the attribute at the head of the stream.
440      * If the stream's type map has an entry for that SQL type, the driver
441      * constructs an object of the appropriate class and calls the method
442      * {@code SQLData.readSQL} on that object, which reads additional data from the
443      * stream, using the protocol described for that method.
444      *<p>
445      * The default implementation will throw {@code SQLFeatureNotSupportedException}
446      *
447      * @param <T> the type of the class modeled by this Class object
448      * @param type Class representing the Java data type to convert the attribute to.
449      * @return the attribute at the head of the stream as an {@code Object} in the
450      * Java programming language;{@code null} if the attribute is SQL {@code NULL}
451      * @exception SQLException if a database access error occurs
452      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
453      * this method
454      * @since 1.8
455      */
456     default <T> T readObject(Class<T> type) throws SQLException {
457        throw new SQLFeatureNotSupportedException();
458     }
459 }