/* * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.sql; /** * An input stream that contains a stream of values representing an * instance of an SQL structured type or an SQL distinct type. * This interface, used only for custom mapping, is used by the driver * behind the scenes, and a programmer never directly invokes * SQLInput methods. The reader methods * (readLong, readBytes, and so on) * provide a way for an implementation of the SQLData * interface to read the values in an SQLInput object. * And as described in SQLData, calls to reader methods must * be made in the order that their corresponding attributes appear in the * SQL definition of the type. * The method wasNull is used to determine whether * the last value read was SQL NULL. *

When the method getObject is called with an * object of a class implementing the interface SQLData, * the JDBC driver calls the method SQLData.getSQLType * to determine the SQL type of the user-defined type (UDT) * being custom mapped. The driver * creates an instance of SQLInput, populating it with the * attributes of the UDT. The driver then passes the input * stream to the method SQLData.readSQL, which in turn * calls the SQLInput reader methods * in its implementation for reading the * attributes from the input stream. * @since 1.2 */ public interface SQLInput { //================================================================ // Methods for reading attributes from the stream of SQL data. // These methods correspond to the column-accessor methods of // java.sql.ResultSet. //================================================================ /** * Reads the next attribute in the stream and returns it as a String * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ String readString() throws SQLException; /** * Reads the next attribute in the stream and returns it as a boolean * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns false * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ boolean readBoolean() throws SQLException; /** * Reads the next attribute in the stream and returns it as a byte * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns 0 * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ byte readByte() throws SQLException; /** * Reads the next attribute in the stream and returns it as a short * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns 0 * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ short readShort() throws SQLException; /** * Reads the next attribute in the stream and returns it as an int * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns 0 * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ int readInt() throws SQLException; /** * Reads the next attribute in the stream and returns it as a long * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns 0 * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ long readLong() throws SQLException; /** * Reads the next attribute in the stream and returns it as a float * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns 0 * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ float readFloat() throws SQLException; /** * Reads the next attribute in the stream and returns it as a double * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns 0 * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ double readDouble() throws SQLException; /** * Reads the next attribute in the stream and returns it as a java.math.BigDecimal * object in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ java.math.BigDecimal readBigDecimal() throws SQLException; /** * Reads the next attribute in the stream and returns it as an array of bytes * in the Java programming language. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ byte[] readBytes() throws SQLException; /** * Reads the next attribute in the stream and returns it as a java.sql.Date object. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ java.sql.Date readDate() throws SQLException; /** * Reads the next attribute in the stream and returns it as a java.sql.Time object. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ java.sql.Time readTime() throws SQLException; /** * Reads the next attribute in the stream and returns it as a java.sql.Timestamp object. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ java.sql.Timestamp readTimestamp() throws SQLException; /** * Reads the next attribute in the stream and returns it as a stream of Unicode characters. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ java.io.Reader readCharacterStream() throws SQLException; /** * Reads the next attribute in the stream and returns it as a stream of ASCII characters. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ java.io.InputStream readAsciiStream() throws SQLException; /** * Reads the next attribute in the stream and returns it as a stream of uninterpreted * bytes. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ java.io.InputStream readBinaryStream() throws SQLException; //================================================================ // Methods for reading items of SQL user-defined types from the stream. //================================================================ /** * Reads the datum at the head of the stream and returns it as an * Object in the Java programming language. The * actual type of the object returned is determined by the default type * mapping, and any customizations present in this stream's type map. * *

A type map is registered with the stream by the JDBC driver before the * stream is passed to the application. * *

When the datum at the head of the stream is an SQL NULL, * the method returns null. If the datum is an SQL structured or distinct * type, it determines the SQL type of the datum at the head of the stream. * If the stream's type map has an entry for that SQL type, the driver * constructs an object of the appropriate class and calls the method * SQLData.readSQL on that object, which reads additional data from the * stream, using the protocol described for that method. * * @return the datum at the head of the stream as an Object in the * Java programming language;null if the datum is SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ Object readObject() throws SQLException; /** * Reads an SQL REF value from the stream and returns it as a * Ref object in the Java programming language. * * @return a Ref object representing the SQL REF value * at the head of the stream; null if the value read is * SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ Ref readRef() throws SQLException; /** * Reads an SQL BLOB value from the stream and returns it as a * Blob object in the Java programming language. * * @return a Blob object representing data of the SQL BLOB value * at the head of the stream; null if the value read is * SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ Blob readBlob() throws SQLException; /** * Reads an SQL CLOB value from the stream and returns it as a * Clob object in the Java programming language. * * @return a Clob object representing data of the SQL CLOB value * at the head of the stream; null if the value read is * SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ Clob readClob() throws SQLException; /** * Reads an SQL ARRAY value from the stream and returns it as an * Array object in the Java programming language. * * @return an Array object representing data of the SQL * ARRAY value at the head of the stream; null * if the value read is SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ Array readArray() throws SQLException; /** * Retrieves whether the last value read was SQL NULL. * * @return true if the most recently read SQL value was SQL * NULL; false otherwise * @exception SQLException if a database access error occurs * * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ boolean wasNull() throws SQLException; //---------------------------- JDBC 3.0 ------------------------- /** * Reads an SQL DATALINK value from the stream and returns it as a * java.net.URL object in the Java programming language. * * @return a java.net.URL object. * @exception SQLException if a database access error occurs, * or if a URL is malformed * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.4 */ java.net.URL readURL() throws SQLException; //---------------------------- JDBC 4.0 ------------------------- /** * Reads an SQL NCLOB value from the stream and returns it as a * NClob object in the Java programming language. * * @return a NClob object representing data of the SQL NCLOB value * at the head of the stream; null if the value read is * SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.6 */ NClob readNClob() throws SQLException; /** * Reads the next attribute in the stream and returns it as a String * in the Java programming language. It is intended for use when * accessing NCHAR,NVARCHAR * and LONGNVARCHAR columns. * * @return the attribute; if the value is SQL NULL, returns null * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.6 */ String readNString() throws SQLException; /** * Reads an SQL XML value from the stream and returns it as a * SQLXML object in the Java programming language. * * @return a SQLXML object representing data of the SQL XML value * at the head of the stream; null if the value read is * SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.6 */ SQLXML readSQLXML() throws SQLException; /** * Reads an SQL ROWID value from the stream and returns it as a * RowId object in the Java programming language. * * @return a RowId object representing data of the SQL ROWID value * at the head of the stream; null if the value read is * SQL NULL * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.6 */ RowId readRowId() throws SQLException; //--------------------------JDBC 4.2 ----------------------------- /** * Reads the next attribute in the stream and returns it as an * {@code Object} in the Java programming language. The * actual type of the object returned is determined by the specified * Java data type, and any customizations present in this * stream's type map. * *

A type map is registered with the stream by the JDBC driver before the * stream is passed to the application. * *

When the attribute at the head of the stream is an SQL {@code NULL} * the method returns {@code null}. If the attribute is an SQL * structured or distinct * type, it determines the SQL type of the attribute at the head of the stream. * If the stream's type map has an entry for that SQL type, the driver * constructs an object of the appropriate class and calls the method * {@code SQLData.readSQL} on that object, which reads additional data from the * stream, using the protocol described for that method. *

* The default implementation will throw {@code SQLFeatureNotSupportedException} * * @param type Class representing the Java data type to convert the attribute to. * @return the attribute at the head of the stream as an {@code Object} in the * Java programming language;{@code null} if the attribute is SQL {@code NULL} * @exception SQLException if a database access error occurs * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.8 */ default T readObject(Class type) throws SQLException { throw new SQLFeatureNotSupportedException(); } }