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   readString() throws SQLException  ;
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  ;
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  ;
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  ;
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  ;
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  ;
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  ;
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  ;
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   readBigDecimal() throws SQLException  ;
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  ;
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   readDate() throws SQLException  ;
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   readTime() throws SQLException  ;
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   readTimestamp() throws SQLException  ;
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   readCharacterStream() throws SQLException  ;
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   readAsciiStream() throws SQLException  ;
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   readBinaryStream() throws SQLException  ;
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   readObject() throws SQLException  ;
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   readRef() throws SQLException  ;
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   readBlob() throws SQLException  ;
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   readClob() throws SQLException  ;
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   readArray() throws SQLException  ;
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  ;
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   readURL() throws SQLException  ;
275 
276 }
277
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags