Module java.sql.rowset
Package javax.sql.rowset.serial

# Class SQLInputImpl

java.lang.Object
javax.sql.rowset.serial.SQLInputImpl

All Implemented Interfaces:
  `SQLInput`

public class SQLInputImpl extends Object implements SQLInput
An input stream used for custom mapping user-defined types (UDTs). An `SQLInputImpl` object is an input stream that contains a stream of values that are the attributes of a UDT.

This class is used by the driver behind the scenes when the method `getObject` is called on an SQL structured or distinct type that has a custom mapping; a programmer never invokes `SQLInputImpl` methods directly. They are provided here as a convenience for those who write `RowSet` implementations.

The `SQLInputImpl` class provides a set of reader methods analogous to the `ResultSet` getter methods. These methods make it possible to read the values in an `SQLInputImpl` object.

The method `wasNull` is used to determine whether the 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 UDT being custom mapped. The driver creates an instance of `SQLInputImpl`, 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 `SQLInputImpl` reader methods to read the attributes from the input stream.

Since:
  1.5
See Also:
  - `SQLData`

## Constructor Summary

Constructors
Constructor
Description
`SQLInputImpl(Object[] attributes, Map<String,Class<?>> map)`
Creates an `SQLInputImpl` object initialized with the given array of attributes and the given type map.

## Method Summary

Modifier and Type
Method
Description
`Array`
`readArray()`
Reads an SQL `ARRAY` value from the stream and returns it as an `Array` object in the Java programming language.
`InputStream`
`readAsciiStream()`
Returns the next attribute in this `SQLInputImpl` object as a stream of ASCII characters.
`BigDecimal`
`readBigDecimal()`
Retrieves the next attribute in this `SQLInputImpl` object as a `java.math.BigDecimal`.
`InputStream`
`readBinaryStream()`
Returns the next attribute in this `SQLInputImpl` object as a stream of uninterpreted bytes.
`Blob`
`readBlob()`
Retrieves the `BLOB` value at the head of this `SQLInputImpl` object as a `Blob` object in the Java programming language.
`boolean`
`readBoolean()`
Retrieves the next attribute in this `SQLInputImpl` object as a `boolean` in the Java programming language.
`byte`
`readByte()`
Retrieves the next attribute in this `SQLInputImpl` object as a `byte` in the Java programming language.
`byte[]`
`readBytes()`
Retrieves the next attribute in this `SQLInputImpl` object as an array of bytes.
`Reader`
`readCharacterStream()`
Retrieves the next attribute in this `SQLInputImpl` object as a stream of Unicode characters.
`Clob`
`readClob()`
Retrieves the `CLOB` value at the head of this `SQLInputImpl` object as a `Clob` object in the Java programming language.
`Date`
`readDate()`
Retrieves the next attribute in this `SQLInputImpl` as a `java.sql.Date` object.
`double`
`readDouble()`
Retrieves the next attribute in this `SQLInputImpl` object as a `double` in the Java programming language.
`float`
`readFloat()`
Retrieves the next attribute in this `SQLInputImpl` object as a `float` in the Java programming language.
`int`
`readInt()`
Retrieves the next attribute in this `SQLInputImpl` object as an `int` in the Java programming language.
`long`
`readLong()`
Retrieves the next attribute in this `SQLInputImpl` object as a `long` in the Java programming language.
`NClob`
`readNClob()`
Reads an SQL `NCLOB` value from the stream and returns it as a `Clob` object in the Java programming language.
`String`
`readNString()`
Reads the next attribute in the stream and returns it as a `String` in the Java programming language.
`Object`
`readObject()`
Retrieves the value at the head of this `SQLInputImpl` object as an `Object` in the Java programming language.
`Ref`
`readRef()`
Retrieves the value at the head of this `SQLInputImpl` object as a `Ref` object in the Java programming language.
`RowId`
`readRowId()`
Reads an SQL `ROWID` value from the stream and returns it as a `RowId` object in the Java programming language.
`short`
`readShort()`
Retrieves the next attribute in this `SQLInputImpl` object as a `short` in the Java programming language.
`SQLXML`
`readSQLXML()`
Reads an SQL `XML` value from the stream and returns it as a `SQLXML` object in the Java programming language.
`String`
`readString()`
Retrieves the next attribute in this `SQLInputImpl` object as a `String` in the Java programming language.
`Time`
`readTime()`
Retrieves the next attribute in this `SQLInputImpl` object as a `java.sql.Time` object.
`Timestamp`
`readTimestamp()`
Retrieves the next attribute in this `SQLInputImpl` object as a `java.sql.Timestamp` object.
`URL`
`readURL()`
Reads an SQL `DATALINK` value from the stream and returns it as an `URL` object in the Java programming language.
`boolean`
`wasNull()`
Ascertains whether the last value read from this `SQLInputImpl` object was `null`.

### Methods declared in class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods declared in interface java.sql.SQLInput

`readObject`

## Constructor Details

### SQLInputImpl

public SQLInputImpl(Object[] attributes, Map<String,Class<?>> map) throws SQLException
Creates an `SQLInputImpl` object initialized with the given array of attributes and the given type map. If any of the attributes is a UDT whose name is in an entry in the type map, the attribute will be mapped according to the corresponding `SQLData` implementation.

Parameters:
  `attributes` - an array of `Object` instances in which each element is an attribute of a UDT. The order of the attributes in the array is the same order in which the attributes were defined in the UDT definition.
  `map` - a `java.util.Map` object containing zero or more entries, with each entry consisting of 1) a `String` giving the fully qualified name of the UDT and 2) the `Class` object for the `SQLData` implementation that defines how the UDT is to be mapped
Throws:
  `SQLException` - if the `attributes` or the `map` is a `null` value

## Method Details

### readString

public String readString() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `String` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readString` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no further values in the stream.

### readBoolean

public boolean readBoolean() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `boolean` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readBoolean` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no further values in the stream.

### readByte

public byte readByte() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `byte` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readByte` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no further values in the stream

### readShort

public short readShort() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `short` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readShort` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readInt

public int readInt() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as an `int` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readInt` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readLong

public long readLong() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `long` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readLong` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readFloat

public float readFloat() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `float` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readFloat` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readDouble

public double readDouble() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `double` in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readDouble` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readBigDecimal

public BigDecimal readBigDecimal() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `java.math.BigDecimal`.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readBigDecimal` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readBytes

public byte[] readBytes() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as an array of bytes.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readBytes` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readDate

public Date readDate() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` as a `java.sql.Date` object.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a `SQLData` implementation.

Specified by:
  `readDate` in interface `SQLInput`
Returns:
  the next attribute in this `SQLInputImpl` object; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position or if there are no more values in the stream

### readTime

public Time readTime() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `java.sql.Time` object.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readTime` in interface `SQLInput`
Returns:
  the attribute; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readTimestamp

public Timestamp readTimestamp() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a `java.sql.Timestamp` object.

Specified by:
  `readTimestamp` in interface `SQLInput`
Returns:
  the attribute; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readCharacterStream

public Reader readCharacterStream() throws SQLException
Retrieves the next attribute in this `SQLInputImpl` object as a stream of Unicode characters.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readCharacterStream` in interface `SQLInput`
Returns:
  the attribute; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readAsciiStream

public InputStream readAsciiStream() throws SQLException
Returns the next attribute in this `SQLInputImpl` object as a stream of ASCII characters.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readAsciiStream` in interface `SQLInput`
Returns:
  the attribute; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readBinaryStream

public InputStream readBinaryStream() throws SQLException
Returns the next attribute in this `SQLInputImpl` object as a stream of uninterpreted bytes.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readBinaryStream` in interface `SQLInput`
Returns:
  the attribute; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readObject

public Object readObject() throws SQLException
Retrieves the value at the head of this `SQLInputImpl` object as an `Object` in the Java programming language. The actual type of the object returned is determined by the default mapping of SQL types to types in the Java programming language unless there is a custom mapping, in which case the type of the object returned is determined by this stream's type map.

The JDBC technology-enabled driver registers a type map with the stream before passing the stream to the application.

When the datum at the head of the stream is an SQL `NULL`, this method returns `null`. If the datum is an SQL structured or distinct type with a custom mapping, this method determines the SQL type of the datum at the head of the stream, constructs an object of the appropriate class, and calls the method `SQLData.readSQL` on that object. The `readSQL` method then calls the appropriate `SQLInputImpl.readXXX` methods to retrieve the attribute values from the stream.

Specified by:
  `readObject` in interface `SQLInput`
Returns:
  the value at the head of the stream as an `Object` in the Java programming language; `null` if the value is SQL `NULL`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readRef

public Ref readRef() throws SQLException
Retrieves the value at the head of this `SQLInputImpl` object as a `Ref` object in the Java programming language.

Specified by:
  `readRef` in interface `SQLInput`
Returns:
  a `Ref` object representing the SQL `REF` value at the head of the stream; if the value is `SQL NULL` return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readBlob

public Blob readBlob() throws SQLException
Retrieves the `BLOB` value at the head of this `SQLInputImpl` object as a `Blob` object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readBlob` in interface `SQLInput`
Returns:
  a `Blob` object representing the SQL `BLOB` value at the head of this stream; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readClob

public Clob readClob() throws SQLException
Retrieves the `CLOB` value at the head of this `SQLInputImpl` object as a `Clob` object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readClob` in interface `SQLInput`
Returns:
  a `Clob` object representing the SQL `CLOB` value at the head of the stream; if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readArray

public Array readArray() throws SQLException
Reads an SQL `ARRAY` value from the stream and returns it as an `Array` object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readArray` in interface `SQLInput`
Returns:
  an `Array` object representing the SQL `ARRAY` value at the head of the stream; * if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### wasNull

public boolean wasNull() throws SQLException
Ascertains whether the last value read from this `SQLInputImpl` object was `null`.

Specified by:
  `wasNull` in interface `SQLInput`
Returns:
  `true` if the SQL value read most recently was `null`; otherwise, `false`; by default it will return false
Throws:
  `SQLException` - if an error occurs determining the last value read was a `null` value or not;

### readURL

public URL readURL() throws SQLException
Reads an SQL `DATALINK` value from the stream and returns it as an `URL` object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a `SQLData` implementation.

Specified by:
  `readURL` in interface `SQLInput`
Returns:
  an `URL` object representing the SQL `DATALINK` value at the head of the stream; * if the value is `SQL NULL`, return `null`
Throws:
  `SQLException` - if the read position is located at an invalid position; or if there are no further values in the stream.

### readNClob

public NClob readNClob() throws SQLException
Reads an SQL `NCLOB` value from the stream and returns it as a `Clob` object in the Java programming language.

Specified by:
  `readNClob` in interface `SQLInput`
Returns:
  a `NClob` object representing data of the SQL `NCLOB` value at the head of the stream; `null` if the value read is SQL `NULL`
Throws:
  `SQLException` - if a database access error occurs
Since:
  1.6

### readNString

public String readNString() 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.

Specified by:
  `readNString` in interface `SQLInput`
Returns:
  the attribute; if the value is SQL `NULL`, returns `null`
Throws:
  `SQLException` - if a database access error occurs
Since:
  1.6

### readSQLXML

public SQLXML readSQLXML() throws SQLException
Reads an SQL `XML` value from the stream and returns it as a `SQLXML` object in the Java programming language.

Specified by:
  `readSQLXML` in interface `SQLInput`
Returns:
  a `SQLXML` object representing data of the SQL `XML` value at the head of the stream; `null` if the value read is SQL `NULL`
Throws:
  `SQLException` - if a database access error occurs
Since:
  1.6

### readRowId

public RowId readRowId() throws SQLException
Reads an SQL `ROWID` value from the stream and returns it as a `RowId` object in the Java programming language.

Specified by:
  `readRowId` in interface `SQLInput`
Returns:
  a `RowId` object representing data of the SQL `ROWID` value at the head of the stream; `null` if the value read is SQL `NULL`
Throws:
  `SQLException` - if a database access error occurs
Since:
  1.6