History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/sql/SQLInput.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/sql/SQLInput.java+424−0
@@ -0,0 +1,424 @@
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+
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+}