Module java.sql
Package java.sql

Interface SQLInput

All Known Implementing Classes:
SQLInputImpl
public interfaceSQLInput
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 invokesSQLInput methods. Thereader methods (readLong,readBytes, and so on) provide a way for an implementation of theSQLData interface to read the values in anSQLInput object. And as described inSQLData, calls to reader methods must be made in the order that their corresponding attributes appear in the SQL definition of the type. The methodwasNull is used to determine whether the last value read was SQLNULL.

When the methodgetObject is called with an object of a class implementing the interfaceSQLData, the JDBC driver calls the methodSQLData.getSQLType to determine the SQL type of the user-defined type (UDT) being custom mapped. The driver creates an instance ofSQLInput, populating it with the attributes of the UDT. The driver then passes the input stream to the methodSQLData.readSQL, which in turn calls theSQLInput reader methods in its implementation for reading the attributes from the input stream.

Since:
1.2

  • Method Summary

    Modifier and Type
    Method
    Description
    Reads an SQLARRAY value from the stream and returns it as anArray object in the Java programming language.
    Reads the next attribute in the stream and returns it as a stream of ASCII characters.
    Reads the next attribute in the stream and returns it as ajava.math.BigDecimal object in the Java programming language.
    Reads the next attribute in the stream and returns it as a stream of uninterpreted bytes.
    Reads an SQLBLOB value from the stream and returns it as aBlob object in the Java programming language.
    boolean
    Reads the next attribute in the stream and returns it as aboolean in the Java programming language.
    byte
    Reads the next attribute in the stream and returns it as abyte in the Java programming language.
    byte[]
    Reads the next attribute in the stream and returns it as an array of bytes in the Java programming language.
    Reads the next attribute in the stream and returns it as a stream of Unicode characters.
    Reads an SQLCLOB value from the stream and returns it as aClob object in the Java programming language.
    Reads the next attribute in the stream and returns it as ajava.sql.Date object.
    double
    Reads the next attribute in the stream and returns it as adouble in the Java programming language.
    float
    Reads the next attribute in the stream and returns it as afloat in the Java programming language.
    int
    Reads the next attribute in the stream and returns it as anint in the Java programming language.
    long
    Reads the next attribute in the stream and returns it as along in the Java programming language.
    Reads an SQLNCLOB value from the stream and returns it as aNClob object in the Java programming language.
    Reads the next attribute in the stream and returns it as aString in the Java programming language.
    Reads the datum at the head of the stream and returns it as anObject in the Java programming language.
    default <T> T
    readObject(Class<T> type)
    Reads the next attribute in the stream and returns it as anObject in the Java programming language.
    Reads an SQLREF value from the stream and returns it as aRef object in the Java programming language.
    Reads an SQLROWID value from the stream and returns it as aRowId object in the Java programming language.
    short
    Reads the next attribute in the stream and returns it as ashort in the Java programming language.
    Reads an SQLXML value from the stream and returns it as aSQLXML object in the Java programming language.
    Reads the next attribute in the stream and returns it as aString in the Java programming language.
    Reads the next attribute in the stream and returns it as ajava.sql.Time object.
    Reads the next attribute in the stream and returns it as ajava.sql.Timestamp object.
    Reads an SQLDATALINK value from the stream and returns it as ajava.net.URL object in the Java programming language.
    boolean
    Retrieves whether the last value read was SQLNULL.

  • Method Details

    • readString

      String readString() throwsSQLException
      Reads the next attribute in the stream and returns it as aString in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readBoolean

      boolean readBoolean() throwsSQLException
      Reads the next attribute in the stream and returns it as aboolean in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returnsfalse
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readByte

      byte readByte() throwsSQLException
      Reads the next attribute in the stream and returns it as abyte in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returns0
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readShort

      short readShort() throwsSQLException
      Reads the next attribute in the stream and returns it as ashort in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returns0
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readInt

      int readInt() throwsSQLException
      Reads the next attribute in the stream and returns it as anint in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returns0
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readLong

      long readLong() throwsSQLException
      Reads the next attribute in the stream and returns it as along in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returns0
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readFloat

      float readFloat() throwsSQLException
      Reads the next attribute in the stream and returns it as afloat in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returns0
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readDouble

      double readDouble() throwsSQLException
      Reads the next attribute in the stream and returns it as adouble in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returns0
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readBigDecimal

      BigDecimal readBigDecimal() throwsSQLException
      Reads the next attribute in the stream and returns it as ajava.math.BigDecimal object in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readBytes

      byte[] readBytes() throwsSQLException
      Reads the next attribute in the stream and returns it as an array of bytes in the Java programming language.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readDate

      Date readDate() throwsSQLException
      Reads the next attribute in the stream and returns it as ajava.sql.Date object.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readTime

      Time readTime() throwsSQLException
      Reads the next attribute in the stream and returns it as ajava.sql.Time object.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readTimestamp

      Timestamp readTimestamp() throwsSQLException
      Reads the next attribute in the stream and returns it as ajava.sql.Timestamp object.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readCharacterStream

      Reader readCharacterStream() throwsSQLException
      Reads the next attribute in the stream and returns it as a stream of Unicode characters.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readAsciiStream

      InputStream readAsciiStream() throwsSQLException
      Reads the next attribute in the stream and returns it as a stream of ASCII characters.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readBinaryStream

      InputStream readBinaryStream() throwsSQLException
      Reads the next attribute in the stream and returns it as a stream of uninterpreted bytes.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readObject

      Object readObject() throwsSQLException
      Reads the datum at the head of the stream and returns it as anObject 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 SQLNULL, the method returnsnull. 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 methodSQLData.readSQL on that object, which reads additional data from the stream, using the protocol described for that method.

      Returns:
      the datum at the head of the stream as anObject in the Java programming language;null if the datum is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readRef

      Ref readRef() throwsSQLException
      Reads an SQLREF value from the stream and returns it as aRef object in the Java programming language.
      Returns:
      aRef object representing the SQLREF value at the head of the stream;null if the value read is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readBlob

      Blob readBlob() throwsSQLException
      Reads an SQLBLOB value from the stream and returns it as aBlob object in the Java programming language.
      Returns:
      aBlob object representing data of the SQLBLOB value at the head of the stream;null if the value read is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readClob

      Clob readClob() throwsSQLException
      Reads an SQLCLOB value from the stream and returns it as aClob object in the Java programming language.
      Returns:
      aClob object representing data of the SQLCLOB value at the head of the stream;null if the value read is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readArray

      Array readArray() throwsSQLException
      Reads an SQLARRAY value from the stream and returns it as anArray object in the Java programming language.
      Returns:
      anArray object representing data of the SQLARRAY value at the head of the stream;null if the value read is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • wasNull

      boolean wasNull() throwsSQLException
      Retrieves whether the last value read was SQLNULL.
      Returns:
      true if the most recently read SQL value was SQLNULL;false otherwise
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.2

    • readURL

      URL readURL() throwsSQLException
      Reads an SQLDATALINK value from the stream and returns it as ajava.net.URL object in the Java programming language.
      Returns:
      ajava.net.URL object.
      Throws:
      SQLException - if a database access error occurs, or if a URL is malformed
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.4

    • readNClob

      NClob readNClob() throwsSQLException
      Reads an SQLNCLOB value from the stream and returns it as aNClob object in the Java programming language.
      Returns:
      aNClob object representing data of the SQLNCLOB value at the head of the stream;null if the value read is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.6

    • readNString

      String readNString() throwsSQLException
      Reads the next attribute in the stream and returns it as aString in the Java programming language. It is intended for use when accessingNCHAR,NVARCHAR andLONGNVARCHAR columns.
      Returns:
      the attribute; if the value is SQLNULL, returnsnull
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.6

    • readSQLXML

      SQLXML readSQLXML() throwsSQLException
      Reads an SQLXML value from the stream and returns it as aSQLXML object in the Java programming language.
      Returns:
      aSQLXML object representing data of the SQLXML value at the head of the stream;null if the value read is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.6

    • readRowId

      RowId readRowId() throwsSQLException
      Reads an SQLROWID value from the stream and returns it as aRowId object in the Java programming language.
      Returns:
      aRowId object representing data of the SQLROWID value at the head of the stream;null if the value read is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.6

    • readObject

      default <T> T readObject(Class<T> type) throwsSQLException
      Reads the next attribute in the stream and returns it as anObject 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 SQLNULL the method returnsnull. 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 methodSQLData.readSQL on that object, which reads additional data from the stream, using the protocol described for that method.

      The default implementation will throwSQLFeatureNotSupportedException

      Type Parameters:
      T - the type of the class modeled by this Class object
      Parameters:
      type - Class representing the Java data type to convert the attribute to.
      Returns:
      the attribute at the head of the stream as anObject in the Java programming language;null if the attribute is SQLNULL
      Throws:
      SQLException - if a database access error occurs
      SQLFeatureNotSupportedException - if the JDBC driver does not support this method
      Since:
      1.8