KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > sql > SQLInput


1 /*
2  * @(#)SQLInput.java 1.25 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.sql;
9  
10 /**
11  * An input stream that contains a stream of values representing an
12  * instance of an SQL structured type or an SQL distinct type.
13  * This interface, used only for custom mapping, is used by the driver
14  * behind the scenes, and a programmer never directly invokes
15  * <code>SQLInput</code> methods. The <i>reader</i> methods
16  * (<code>readLong</code>, <code>readBytes</code>, and so on)
17  * provide a way to read the values in an <code>SQLInput</code> object.
18  * The method <code>wasNull</code> is used to determine whether the
19  * the last value read was SQL <code>NULL</code>.
20  * <P>When the method <code>getObject</code> is called with an
21  * object of a class implementing the interface <code>SQLData</code>,
22  * the JDBC driver calls the method <code>SQLData.getSQLType</code>
23  * to determine the SQL type of the user-defined type (UDT)
24  * being custom mapped. The driver
25  * creates an instance of <code>SQLInput</code>, populating it with the
26  * attributes of the UDT. The driver then passes the input
27  * stream to the method <code>SQLData.readSQL</code>, which in turn
28  * calls the <code>SQLInput</code> reader methods
29  * in its implementation for reading the
30  * attributes from the input stream.
31  * @since 1.2
32  */

33
34 public interface SQLInput {
35   
36
37     //================================================================
38
// Methods for reading attributes from the stream of SQL data.
39
// These methods correspond to the column-accessor methods of
40
// java.sql.ResultSet.
41
//================================================================
42

43     /**
44      * Reads the next attribute in the stream and returns it as a <code>String</code>
45      * in the Java programming language.
46      *
47      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
48      * @exception SQLException if a database access error occurs
49      */

50     String JavaDoc readString() throws SQLException JavaDoc;
51
52     /**
53      * Reads the next attribute in the stream and returns it as a <code>boolean</code>
54      * in the Java programming language.
55      *
56      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>false</code>
57      * @exception SQLException if a database access error occurs
58      */

59     boolean readBoolean() throws SQLException JavaDoc;
60
61     /**
62      * Reads the next attribute in the stream and returns it as a <code>byte</code>
63      * in the Java programming language.
64      *
65      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
66      * @exception SQLException if a database access error occurs
67      */

68     byte readByte() throws SQLException JavaDoc;
69
70     /**
71      * Reads the next attribute in the stream and returns it as a <code>short</code>
72      * in the Java programming language.
73      *
74      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
75      * @exception SQLException if a database access error occurs
76      */

77     short readShort() throws SQLException JavaDoc;
78
79     /**
80      * Reads the next attribute in the stream and returns it as an <code>int</code>
81      * in the Java programming language.
82      *
83      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
84      * @exception SQLException if a database access error occurs
85      */

86     int readInt() throws SQLException JavaDoc;
87
88     /**
89      * Reads the next attribute in the stream and returns it as a <code>long</code>
90      * in the Java programming language.
91      *
92      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
93      * @exception SQLException if a database access error occurs
94      */

95     long readLong() throws SQLException JavaDoc;
96
97     /**
98      * Reads the next attribute in the stream and returns it as a <code>float</code>
99      * in the Java programming language.
100      *
101      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
102      * @exception SQLException if a database access error occurs
103      */

104     float readFloat() throws SQLException JavaDoc;
105
106     /**
107      * Reads the next attribute in the stream and returns it as a <code>double</code>
108      * in the Java programming language.
109      *
110      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
111      * @exception SQLException if a database access error occurs
112      */

113     double readDouble() throws SQLException JavaDoc;
114
115     /**
116      * Reads the next attribute in the stream and returns it as a <code>java.math.BigDecimal</code>
117      * object in the Java programming language.
118      *
119      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
120      * @exception SQLException if a database access error occurs
121      */

122     java.math.BigDecimal JavaDoc readBigDecimal() throws SQLException JavaDoc;
123
124     /**
125      * Reads the next attribute in the stream and returns it as an array of bytes
126      * in the Java programming language.
127      *
128      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
129      * @exception SQLException if a database access error occurs
130      */

131     byte[] readBytes() throws SQLException JavaDoc;
132
133     /**
134      * Reads the next attribute in the stream and returns it as a <code>java.sql.Date</code> object.
135      *
136      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
137      * @exception SQLException if a database access error occurs
138      */

139     java.sql.Date JavaDoc readDate() throws SQLException JavaDoc;
140
141     /**
142      * Reads the next attribute in the stream and returns it as a <code>java.sql.Time</code> object.
143      *
144      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
145      * @exception SQLException if a database access error occurs
146      */

147     java.sql.Time JavaDoc readTime() throws SQLException JavaDoc;
148
149     /**
150      * Reads the next attribute in the stream and returns it as a <code>java.sql.Timestamp</code> object.
151      *
152      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
153      * @exception SQLException if a database access error occurs
154      */

155     java.sql.Timestamp JavaDoc readTimestamp() throws SQLException JavaDoc;
156
157     /**
158      * Reads the next attribute in the stream and returns it as a stream of Unicode characters.
159      *
160      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
161      * @exception SQLException if a database access error occurs
162      */

163     java.io.Reader JavaDoc readCharacterStream() throws SQLException JavaDoc;
164
165     /**
166      * Reads the next attribute in the stream and returns it as a stream of ASCII characters.
167      *
168      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
169      * @exception SQLException if a database access error occurs
170      */

171     java.io.InputStream JavaDoc readAsciiStream() throws SQLException JavaDoc;
172
173     /**
174      * Reads the next attribute in the stream and returns it as a stream of uninterpreted
175      * bytes.
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      */

180     java.io.InputStream JavaDoc readBinaryStream() throws SQLException JavaDoc;
181   
182     //================================================================
183
// Methods for reading items of SQL user-defined types from the stream.
184
//================================================================
185

186     /**
187      * Reads the datum at the head of the stream and returns it as an
188      * <code>Object</code> in the Java programming language. The
189      * actual type of the object returned is determined by the default type
190      * mapping, and any customizations present in this stream's type map.
191      *
192      * <P>A type map is registered with the stream by the JDBC driver before the
193      * stream is passed to the application.
194      *
195      * <P>When the datum at the head of the stream is an SQL <code>NULL</code>,
196      * the method returns <code>null</code>. If the datum is an SQL structured or distinct
197      * type, it determines the SQL type of the datum at the head of the stream.
198      * If the stream's type map has an entry for that SQL type, the driver
199      * constructs an object of the appropriate class and calls the method
200      * <code>SQLData.readSQL</code> on that object, which reads additional data from the
201      * stream, using the protocol described for that method.
202      *
203      * @return the datum at the head of the stream as an <code>Object</code> in the
204      * Java programming language;<code>null</code> if the datum is SQL <code>NULL</code>
205      * @exception SQLException if a database access error occurs
206      */

207     Object JavaDoc readObject() throws SQLException JavaDoc;
208
209     /**
210      * Reads an SQL <code>REF</code> value from the stream and returns it as a
211      * <code>Ref</code> object in the Java programming language.
212      *
213      * @return a <code>Ref</code> object representing the SQL <code>REF</code> value
214      * at the head of the stream; <code>null</code> if the value read is
215      * SQL <code>NULL</code>
216      * @exception SQLException if a database access error occurs
217      */

218     Ref JavaDoc readRef() throws SQLException JavaDoc;
219
220     /**
221      * Reads an SQL <code>BLOB</code> value from the stream and returns it as a
222      * <code>Blob</code> object in the Java programming language.
223      *
224      * @return a <code>Blob</code> object representing data of the SQL <code>BLOB</code> value
225      * at the head of the stream; <code>null</code> if the value read is
226      * SQL <code>NULL</code>
227      * @exception SQLException if a database access error occurs
228      */

229     Blob JavaDoc readBlob() throws SQLException JavaDoc;
230
231     /**
232      * Reads an SQL <code>CLOB</code> value from the stream and returns it as a
233      * <code>Clob</code> object in the Java programming language.
234      *
235      * @return a <code>Clob</code> object representing data of the SQL <code>CLOB</code> value
236      * at the head of the stream; <code>null</code> if the value read is
237      * SQL <code>NULL</code>
238      * @exception SQLException if a database access error occurs
239      */

240     Clob JavaDoc readClob() throws SQLException JavaDoc;
241
242     /**
243      * Reads an SQL <code>ARRAY</code> value from the stream and returns it as an
244      * <code>Array</code> object in the Java programming language.
245      *
246      * @return an <code>Array</code> object representing data of the SQL
247      * <code>ARRAY</code> value at the head of the stream; <code>null</code>
248      * if the value read is SQL <code>NULL</code>
249      * @exception SQLException if a database access error occurs
250      */

251     Array JavaDoc readArray() throws SQLException JavaDoc;
252
253     /**
254      * Retrieves whether the last value read was SQL <code>NULL</code>.
255      *
256      * @return <code>true</code> if the most recently read SQL value was SQL
257      * <code>NULL</code>; <code>false</code> otherwise
258      * @exception SQLException if a database access error occurs
259      *
260      */

261     boolean wasNull() throws SQLException JavaDoc;
262
263     //---------------------------- JDBC 3.0 -------------------------
264

265     /**
266      * Reads an SQL <code>DATALINK</code> value from the stream and returns it as a
267      * <code>java.net.URL</code> object in the Java programming language.
268      *
269      * @return a <code>java.net.URL</code> object.
270      * @exception SQLException if a database access error occurs,
271      * or if a URL is malformed
272      * @since 1.4
273      */

274     java.net.URL JavaDoc readURL() throws SQLException JavaDoc;
275
276 }
277
Popular Tags