Back to index...

	/*
	* Copyright (c) 1998, 2020, 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
	* {@code SQLInput} methods. The <i>reader</i> methods
	* ({@code readLong}, {@code readBytes}, and so on)
	* provide a way for an implementation of the {@code SQLData}
	* interface to read the values in an {@code SQLInput} object.
	* And as described in {@code 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 {@code wasNull} is used to determine whether
	* the last value read was SQL {@code NULL}.
	* <P>When the method {@code getObject} is called with an
	* object of a class implementing the interface {@code SQLData},
	* the JDBC driver calls the method {@code SQLData.getSQLType}
	* to determine the SQL type of the user-defined type (UDT)
	* being custom mapped. The driver
	* creates an instance of {@code SQLInput}, populating it with the
	* attributes of the UDT. The driver then passes the input
	* stream to the method {@code SQLData.readSQL}, which in turn
	* calls the {@code 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 {@code String}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code boolean}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code false}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code byte}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code 0}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code short}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code 0}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code int}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code 0}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code long}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code 0}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code float}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code 0}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code double}
	* in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code 0}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code java.math.BigDecimal}
	* object in the Java programming language.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code java.sql.Date} object.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code java.sql.Time} object.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code java.sql.Timestamp} object.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws 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
	* {@code 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.
	*
	* <P>A type map is registered with the stream by the JDBC driver before the
	* stream is passed to the application.
	*
	* <P>When the datum at the head of the stream is an SQL {@code NULL},
	* the method returns {@code 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
	* {@code 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 {@code Object} in the
	* Java programming language;{@code null} if the datum is SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.2
	*/
	Object readObject() throws SQLException;

	/**
	* Reads an SQL {@code REF} value from the stream and returns it as a
	* {@code Ref} object in the Java programming language.
	*
	* @return a {@code Ref} object representing the SQL {@code REF} value
	* at the head of the stream; {@code null} if the value read is
	* SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.2
	*/
	Ref readRef() throws SQLException;

	/**
	* Reads an SQL {@code BLOB} value from the stream and returns it as a
	* {@code Blob} object in the Java programming language.
	*
	* @return a {@code Blob} object representing data of the SQL {@code BLOB} value
	* at the head of the stream; {@code null} if the value read is
	* SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.2
	*/
	Blob readBlob() throws SQLException;

	/**
	* Reads an SQL {@code CLOB} value from the stream and returns it as a
	* {@code Clob} object in the Java programming language.
	*
	* @return a {@code Clob} object representing data of the SQL {@code CLOB} value
	* at the head of the stream; {@code null} if the value read is
	* SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.2
	*/
	Clob readClob() throws SQLException;

	/**
	* Reads an SQL {@code ARRAY} value from the stream and returns it as an
	* {@code Array} object in the Java programming language.
	*
	* @return an {@code Array} object representing data of the SQL
	* {@code ARRAY} value at the head of the stream; {@code null}
	* if the value read is SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code NULL}.
	*
	* @return {@code true} if the most recently read SQL value was SQL
	* {@code NULL}; {@code false} otherwise
	* @throws SQLException if a database access error occurs
	*
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.2
	*/
	boolean wasNull() throws SQLException;

	//---------------------------- JDBC 3.0 -------------------------

	/**
	* Reads an SQL {@code DATALINK} value from the stream and returns it as a
	* {@code java.net.URL} object in the Java programming language.
	*
	* @return a {@code java.net.URL} object.
	* @throws SQLException if a database access error occurs,
	* or if a URL is malformed
	* @throws 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 {@code NCLOB} value from the stream and returns it as a
	* {@code NClob} object in the Java programming language.
	*
	* @return a {@code NClob} object representing data of the SQL {@code NCLOB} value
	* at the head of the stream; {@code null} if the value read is
	* SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws 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 {@code String}
	* in the Java programming language. It is intended for use when
	* accessing {@code NCHAR},{@code NVARCHAR}
	* and {@code LONGNVARCHAR} columns.
	*
	* @return the attribute; if the value is SQL {@code NULL}, returns {@code null}
	* @throws SQLException if a database access error occurs
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.6
	*/
	String readNString() throws SQLException;

	/**
	* Reads an SQL {@code XML} value from the stream and returns it as a
	* {@code SQLXML} object in the Java programming language.
	*
	* @return a {@code SQLXML} object representing data of the SQL {@code XML} value
	* at the head of the stream; {@code null} if the value read is
	* SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.6
	*/
	SQLXML readSQLXML() throws SQLException;

	/**
	* Reads an SQL {@code ROWID} value from the stream and returns it as a
	* {@code RowId} object in the Java programming language.
	*
	* @return a {@code RowId} object representing data of the SQL {@code ROWID} value
	* at the head of the stream; {@code null} if the value read is
	* SQL {@code NULL}
	* @throws SQLException if a database access error occurs
	* @throws 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.
	*
	* <P>A type map is registered with the stream by the JDBC driver before the
	* stream is passed to the application.
	*
	* <P>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.
	*<p>
	* The default implementation will throw {@code SQLFeatureNotSupportedException}
	*
	* @param <T> the type of the class modeled by this Class object
	* @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}
	* @throws SQLException if a database access error occurs
	* @throws SQLFeatureNotSupportedException if the JDBC driver does not support
	* this method
	* @since 1.8
	*/
	default <T> T readObject(Class<T> type) throws SQLException {
	throw new SQLFeatureNotSupportedException();
	}
	}

Back to index...