1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.sql;
19
20import java.io.InputStream;
21import java.io.Reader;
22import java.math.BigDecimal;
23import java.net.URL;
24
25/**
26 * The {@code SQLInput} interface defines operations which apply to a type of
27 * input stream which carries a series of values representing an instance of
28 * an SQL structured type or SQL distinct type.
29 * <p>
30 * This interface is used to define custom mappings of SQL <i>User Defined
31 * Types</i> (UDTs) to Java classes. It is used by JDBC drivers, therefore
32 * application programmers do not normally use the {@code SQLInput} methods
33 * directly. Reader methods such as {@code readLong} and {@code readBytes}
34 * provide means to read values from an {@code SQLInput} stream.
35 * <p>
36 * When the {@code getObject} method is called with an object which implements
37 * the {@code SQLData} interface, the JDBC driver determines the SQL type of the
38 * UDT being mapped by calling the {@code SQLData.getSQLType} method. The driver
39 * creates an instance of an {@code SQLInput} stream, filling the stream with
40 * the attributes of the UDT. The {@code SQLInput} stream is passed to the
41 * {@code SQLData.readSQL} method which then calls the {@code SQLInput} reader
42 * methods to read the attributes.
43 *
44 * @see SQLData
45 */
46public interface SQLInput {
47
48    /**
49     * Returns the next attribute in the stream in the form of a {@code String}.
50     *
51     * @return the next attribute. {@code null} if the value is SQL {@code NULL}.
52     *
53     * @throws SQLException
54     *             if there is a database error.
55     */
56    public String readString() throws SQLException;
57
58    /**
59     * Returns the next attribute in the stream in the form of a {@code boolean}
60     * .
61     *
62     * @return the next attribute as a {@code boolean}. {@code false} if the
63     *         value is SQL {@code NULL}.
64     * @throws SQLException
65     *             if there is a database error.
66     */
67    public boolean readBoolean() throws SQLException;
68
69    /**
70     * Returns the next attribute in the stream in the form of a {@code byte}.
71     *
72     * @return the next attribute as a {@code byte}. 0 if the value is SQL
73     *         {@code NULL}.
74     * @throws SQLException
75     *             if there is a database error.
76     */
77    public byte readByte() throws SQLException;
78
79    /**
80     * Returns the next attribute in the stream in the form of a {@code short}.
81     *
82     * @return the next attribute as a {@code short}. 0 if the value is SQL
83     *         {@code NULL}.
84     * @throws SQLException
85     *             if there is a database error.
86     */
87    public short readShort() throws SQLException;
88
89    /**
90     * Returns the next attribute in the stream in the form of an {@code int}.
91     *
92     * @return the next attribute as an {@code int}. 0 if the value is SQL
93     *         {@code NULL}.
94     * @throws SQLException
95     *             if there is a database error.
96     */
97    public int readInt() throws SQLException;
98
99    /**
100     * Returns the next attribute in the stream in the form of a {@code long}.
101     *
102     * @return the next attribute as a {@code long}. 0 if the value is SQL
103     *         {@code NULL}.
104     * @throws SQLException
105     *             if there is a database error.
106     */
107    public long readLong() throws SQLException;
108
109    /**
110     * Returns the next attribute in the stream in the form of a {@code float}.
111     *
112     * @return the next attribute as a {@code float}. 0 if the value is SQL
113     *         {@code NULL}.
114     * @throws SQLException
115     *             if there is a database error.
116     */
117    public float readFloat() throws SQLException;
118
119    /**
120     * Returns the next attribute in the stream in the form of a {@code double}.
121     *
122     * @return the next attribute as a {@code double}. 0 if the value is SQL
123     *         {@code NULL}.
124     * @throws SQLException
125     *             if there is a database error.
126     */
127    public double readDouble() throws SQLException;
128
129    /**
130     * Returns the next attribute in the stream in the form of a {@code
131     * java.math.BigDecimal}.
132     *
133     * @return the attribute as a {@code java.math.BigDecimal}. {@code null} if
134     *         the read returns SQL {@code NULL}.
135     * @throws SQLException
136     *             if there is a database error.
137     * @see java.math.BigDecimal
138     */
139    public BigDecimal readBigDecimal() throws SQLException;
140
141    /**
142     * Returns the next attribute in the stream in the form of a byte array.
143     *
144     * @return the attribute as a byte array. {@code null} if the read returns
145     *         SQL {@code NULL}.
146     * @throws SQLException
147     *             if there is a database error.
148     */
149    public byte[] readBytes() throws SQLException;
150
151    /**
152     * Returns the next attribute in the stream in the form of a {@code
153     * java.sql.Date}.
154     *
155     * @return the next attribute as a {@code java.sql.Date}. {@code null} if
156     *         the value is SQL {@code NULL}.
157     * @throws SQLException
158     *             if there is a database error.
159     * @see Date
160     */
161    public Date readDate() throws SQLException;
162
163    /**
164     * Returns the next attribute in the stream in the form of a {@code
165     * java.sql.Time}.
166     *
167     * @return the attribute as a {@code java.sql.Time}. {@code null} if the
168     *         read returns SQL {@code NULL}.
169     * @throws SQLException
170     *             if there is a database error.
171     * @see Time
172     */
173    public Time readTime() throws SQLException;
174
175    /**
176     * Returns the next attribute in the stream in the form of a {@code
177     * java.sql.Timestamp}.
178     *
179     * @return the attribute as a {@code java.sql.Timestamp}. {@code null} if
180     *         the read returns SQL {@code NULL}.
181     * @throws SQLException
182     *             if there is a database error.
183     * @see Timestamp
184     */
185    public Timestamp readTimestamp() throws SQLException;
186
187    /**
188     * Returns the next attribute in the stream in the form of a Unicode
189     * character stream embodied as a {@code java.io.Reader}.
190     *
191     * @return the next attribute as a {@code java.io.Reader}. {@code null} if
192     *         the value is SQL {@code NULL}.
193     * @throws SQLException
194     *             if there is a database error.
195     * @see java.io.Reader
196     */
197    public Reader readCharacterStream() throws SQLException;
198
199    /**
200     * Returns the next attribute in the stream in the form of an ASCII
201     * character stream embodied as a {@code java.io.InputStream}.
202     *
203     * @return the next attribute as a {@code java.io.InputStream}. {@code null}
204     *         if the value is SQL {@code NULL}.
205     * @throws SQLException
206     *             if there is a database error.
207     * @see java.io.InputStream
208     */
209    public InputStream readAsciiStream() throws SQLException;
210
211    /**
212     * Returns the next attribute in the stream in the form of a stream of bytes
213     * embodied as a {@code java.io.InputStream}.
214     *
215     * @return the next attribute as a {@code java.io.InputStream}. {@code null}
216     *         if the value is SQL {@code NULL}.
217     * @throws SQLException
218     *             if there is a database error.
219     * @see java.io.InputStream
220     */
221    public InputStream readBinaryStream() throws SQLException;
222
223    /**
224     * Returns the next attribute in the stream in the form of a {@code
225     * java.lang.Object}.
226     * <p>
227     * The type of the {@code Object} returned is determined by the type mapping
228     * for this JDBC driver, including any customized mappings, if present. A
229     * type map is given to the {@code SQLInput} by the JDBC driver before the
230     * {@code SQLInput} is given to the application.
231     * <p>
232     * If the attribute is an SQL structured or distinct type, its SQL type is
233     * determined. If the stream's type map contains an element for that SQL
234     * type, the driver creates an object for the relevant type and invokes the
235     * method {@code SQLData.readSQL} on it, which reads supplementary data from
236     * the stream using whichever protocol is defined for that method.
237     *
238     * @return the next attribute as an Object. {@code null} if the value is SQL
239     *         {@code NULL}.
240     * @throws SQLException
241     *             if there is a database error.
242     */
243    public Object readObject() throws SQLException;
244
245    /**
246     * Returns the next attribute in the stream in the form of a {@code
247     * java.sql.Ref}.
248     *
249     * @return the next attribute as a {@code java.sql.Ref}. {@code null} if the
250     *         value is SQL {@code NULL}.
251     * @throws SQLException
252     *             if there is a database error.
253     * @see Ref
254     */
255    public Ref readRef() throws SQLException;
256
257    /**
258     * Returns the next attribute in the stream in the form of a {@code
259     * java.sql.Blob}.
260     *
261     * @return the next attribute as a {@code java.sql.Blob}. {@code null} if
262     *         the value is SQL {@code NULL}.
263     * @throws SQLException
264     *             if there is a database error.
265     */
266    public Blob readBlob() throws SQLException;
267
268    /**
269     * Returns the next attribute in the stream in the form of a {@code
270     * java.sql.Clob}.
271     *
272     * @return the next attribute as a {@code java.sql.Clob}. {@code null} if
273     *         the value is SQL {@code NULL}.
274     * @throws SQLException
275     *             if there is a database error.
276     * @see Clob
277     */
278    public Clob readClob() throws SQLException;
279
280    /**
281     * Returns the next attribute in the stream in the form of a {@code
282     * java.sql.Array}.
283     *
284     * @return the next attribute as an {@code Array}. {@code null} if the value
285     *         is SQL {@code NULL}.
286     * @throws SQLException
287     *             if there is a database error.
288     * @see Array
289     */
290    public Array readArray() throws SQLException;
291
292    /**
293     * Reports whether the last value read was SQL {@code NULL}.
294     *
295     * @return {@code true} if the last value read was SQL {@code NULL}, {@code
296     *         false} otherwise.
297     * @throws SQLException
298     *             if there is a database error.
299     */
300    public boolean wasNull() throws SQLException;
301
302    /**
303     * Reads the next attribute in the stream (SQL DATALINK value) and returns
304     * it as a {@code java.net.URL} object.
305     *
306     * @return the next attribute as a {@code java.net.URL}. {@code null} if the
307     *         value is SQL {@code NULL}.
308     * @throws SQLException
309     *             if there is a database error.
310     * @see java.net.URL
311     */
312    public URL readURL() throws SQLException;
313
314    /**
315     * Returns the next attribute in the stream in the form of a {@code
316     * java.sql.NClob}.
317     *
318     * @return the next attribute as a {@code java.sql.NClob}. {@code null} if
319     *         the value is SQL {@code NULL}.
320     * @throws SQLException
321     *             if there is a database error.
322     */
323    public NClob readNClob() throws SQLException;
324
325    /**
326     * Returns the next attribute in the stream in the form of a {@code
327     * java.lang.String}. Used for the NCHAR, NVARCHAR and LONGNVARCHAR types.
328     * See {@link #readString} otherwise.
329     *
330     * @return the next attribute as a {@code java.lang.String}. {@code null} if
331     *         the value is SQL {@code NULL}.
332     * @throws SQLException
333     *             if there is a database error.
334     */
335    public String readNString() throws SQLException;
336
337    /**
338     * Returns the next attribute in the stream in the form of a {@code
339     * java.sql.SQLXML}.
340     *
341     * @return the next attribute as a {@code java.sql.SQLXML}. {@code null} if
342     *         the value is SQL {@code NULL}.
343     * @throws SQLException
344     *             if there is a database error.
345     */
346    public SQLXML readSQLXML() throws SQLException;
347
348    /**
349     * Returns the next attribute in the stream in the form of a {@code
350     * java.sql.RowId}. Used for the ROWID type.
351     *
352     * @return the next attribute as a {@code java.sql.RowId}. {@code null} if
353     *         the value is SQL {@code NULL}.
354     * @throws SQLException
355     *             if there is a database error.
356     */
357    public RowId readRowId() throws SQLException;
358}
359