/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.sql;
import java.io.InputStream;
import java.io.Reader;
import java.math.BigDecimal;
import java.net.URL;
/**
* The {@code SQLInput} interface defines operations which apply to a type of
* input stream which carries a series of values representing an instance of
* an SQL structured type or SQL distinct type.
* <p>
* This interface is used to define custom mappings of SQL <i>User Defined
* Types</i> (UDTs) to Java classes. It is used by JDBC drivers, therefore
* application programmers do not normally use the {@code SQLInput} methods
* directly. Reader methods such as {@code readLong} and {@code readBytes}
* provide means to read values from an {@code SQLInput} stream.
* <p>
* When the {@code getObject} method is called with an object which implements
* the {@code SQLData} interface, the JDBC driver determines the SQL type of the
* UDT being mapped by calling the {@code SQLData.getSQLType} method. The driver
* creates an instance of an {@code SQLInput} stream, filling the stream with
* the attributes of the UDT. The {@code SQLInput} stream is passed to the
* {@code SQLData.readSQL} method which then calls the {@code SQLInput} reader
* methods to read the attributes.
*
* @see SQLData
*/
public interface SQLInput {
/**
* Returns the next attribute in the stream in the form of a {@code String}.
*
* @return the next attribute. {@code null} if the value is SQL {@code NULL}.
*
* @throws SQLException
* if there is a database error.
*/
public String readString() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code boolean}
* .
*
* @return the next attribute as a {@code boolean}. {@code false} if the
* value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public boolean readBoolean() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code byte}.
*
* @return the next attribute as a {@code byte}. 0 if the value is SQL
* {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public byte readByte() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code short}.
*
* @return the next attribute as a {@code short}. 0 if the value is SQL
* {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public short readShort() throws SQLException;
/**
* Returns the next attribute in the stream in the form of an {@code int}.
*
* @return the next attribute as an {@code int}. 0 if the value is SQL
* {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public int readInt() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code long}.
*
* @return the next attribute as a {@code long}. 0 if the value is SQL
* {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public long readLong() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code float}.
*
* @return the next attribute as a {@code float}. 0 if the value is SQL
* {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public float readFloat() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code double}.
*
* @return the next attribute as a {@code double}. 0 if the value is SQL
* {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public double readDouble() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.math.BigDecimal}.
*
* @return the attribute as a {@code java.math.BigDecimal}. {@code null} if
* the read returns SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see java.math.BigDecimal
*/
public BigDecimal readBigDecimal() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a byte array.
*
* @return the attribute as a byte array. {@code null} if the read returns
* SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public byte[] readBytes() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.Date}.
*
* @return the next attribute as a {@code java.sql.Date}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see Date
*/
public Date readDate() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.Time}.
*
* @return the attribute as a {@code java.sql.Time}. {@code null} if the
* read returns SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see Time
*/
public Time readTime() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.Timestamp}.
*
* @return the attribute as a {@code java.sql.Timestamp}. {@code null} if
* the read returns SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see Timestamp
*/
public Timestamp readTimestamp() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a Unicode
* character stream embodied as a {@code java.io.Reader}.
*
* @return the next attribute as a {@code java.io.Reader}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see java.io.Reader
*/
public Reader readCharacterStream() throws SQLException;
/**
* Returns the next attribute in the stream in the form of an ASCII
* character stream embodied as a {@code java.io.InputStream}.
*
* @return the next attribute as a {@code java.io.InputStream}. {@code null}
* if the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see java.io.InputStream
*/
public InputStream readAsciiStream() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a stream of bytes
* embodied as a {@code java.io.InputStream}.
*
* @return the next attribute as a {@code java.io.InputStream}. {@code null}
* if the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see java.io.InputStream
*/
public InputStream readBinaryStream() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.lang.Object}.
* <p>
* The type of the {@code Object} returned is determined by the type mapping
* for this JDBC driver, including any customized mappings, if present. A
* type map is given to the {@code SQLInput} by the JDBC driver before the
* {@code SQLInput} is given to the application.
* <p>
* If the attribute is an SQL structured or distinct type, its SQL type is
* determined. If the stream's type map contains an element for that SQL
* type, the driver creates an object for the relevant type and invokes the
* method {@code SQLData.readSQL} on it, which reads supplementary data from
* the stream using whichever protocol is defined for that method.
*
* @return the next attribute as an Object. {@code null} if the value is SQL
* {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public Object readObject() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.Ref}.
*
* @return the next attribute as a {@code java.sql.Ref}. {@code null} if the
* value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see Ref
*/
public Ref readRef() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.Blob}.
*
* @return the next attribute as a {@code java.sql.Blob}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public Blob readBlob() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.Clob}.
*
* @return the next attribute as a {@code java.sql.Clob}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see Clob
*/
public Clob readClob() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.Array}.
*
* @return the next attribute as an {@code Array}. {@code null} if the value
* is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see Array
*/
public Array readArray() throws SQLException;
/**
* Reports whether the last value read was SQL {@code NULL}.
*
* @return {@code true} if the last value read was SQL {@code NULL}, {@code
* false} otherwise.
* @throws SQLException
* if there is a database error.
*/
public boolean wasNull() throws SQLException;
/**
* Reads the next attribute in the stream (SQL DATALINK value) and returns
* it as a {@code java.net.URL} object.
*
* @return the next attribute as a {@code java.net.URL}. {@code null} if the
* value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
* @see java.net.URL
*/
public URL readURL() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.NClob}.
*
* @return the next attribute as a {@code java.sql.NClob}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public NClob readNClob() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.lang.String}. Used for the NCHAR, NVARCHAR and LONGNVARCHAR types.
* See {@link #readString} otherwise.
*
* @return the next attribute as a {@code java.lang.String}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public String readNString() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.SQLXML}.
*
* @return the next attribute as a {@code java.sql.SQLXML}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public SQLXML readSQLXML() throws SQLException;
/**
* Returns the next attribute in the stream in the form of a {@code
* java.sql.RowId}. Used for the ROWID type.
*
* @return the next attribute as a {@code java.sql.RowId}. {@code null} if
* the value is SQL {@code NULL}.
* @throws SQLException
* if there is a database error.
*/
public RowId readRowId() throws SQLException;
}