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 Detail

    - #### 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 Detail

    - #### 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