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

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and TypeMethodDescription
      ArrayreadArray()
      Reads an SQLARRAY value from the stream and returns it as anArray object in the Java programming language.
      InputStreamreadAsciiStream()
      Reads the next attribute in the stream and returns it as a stream of ASCII characters.
      BigDecimalreadBigDecimal()
      Reads the next attribute in the stream and returns it as ajava.math.BigDecimal object in the Java programming language.
      InputStreamreadBinaryStream()
      Reads the next attribute in the stream and returns it as a stream of uninterpreted bytes.
      BlobreadBlob()
      Reads an SQLBLOB value from the stream and returns it as aBlob object in the Java programming language.
      booleanreadBoolean()
      Reads the next attribute in the stream and returns it as aboolean in the Java programming language.
      bytereadByte()
      Reads the next attribute in the stream and returns it as abyte in the Java programming language.
      byte[]readBytes()
      Reads the next attribute in the stream and returns it as an array of bytes in the Java programming language.
      ReaderreadCharacterStream()
      Reads the next attribute in the stream and returns it as a stream of Unicode characters.
      ClobreadClob()
      Reads an SQLCLOB value from the stream and returns it as aClob object in the Java programming language.
      DatereadDate()
      Reads the next attribute in the stream and returns it as ajava.sql.Date object.
      doublereadDouble()
      Reads the next attribute in the stream and returns it as adouble in the Java programming language.
      floatreadFloat()
      Reads the next attribute in the stream and returns it as afloat in the Java programming language.
      intreadInt()
      Reads the next attribute in the stream and returns it as anint in the Java programming language.
      longreadLong()
      Reads the next attribute in the stream and returns it as along in the Java programming language.
      NClobreadNClob()
      Reads an SQLNCLOB value from the stream and returns it as aNClob object in the Java programming language.
      StringreadNString()
      Reads the next attribute in the stream and returns it as aString in the Java programming language.
      ObjectreadObject()
      Reads the datum at the head of the stream and returns it as anObject in the Java programming language.
      default <T> TreadObject(Class<T> type)
      Reads the next attribute in the stream and returns it as anObject in the Java programming language.
      RefreadRef()
      Reads an SQLREF value from the stream and returns it as aRef object in the Java programming language.
      RowIdreadRowId()
      Reads an SQLROWID value from the stream and returns it as aRowId object in the Java programming language.
      shortreadShort()
      Reads the next attribute in the stream and returns it as ashort in the Java programming language.
      SQLXMLreadSQLXML()
      Reads an SQLXML value from the stream and returns it as aSQLXML object in the Java programming language.
      StringreadString()
      Reads the next attribute in the stream and returns it as aString in the Java programming language.
      TimereadTime()
      Reads the next attribute in the stream and returns it as ajava.sql.Time object.
      TimestampreadTimestamp()
      Reads the next attribute in the stream and returns it as ajava.sql.Timestamp object.
      URLreadURL()
      Reads an SQLDATALINK value from the stream and returns it as ajava.net.URL object in the Java programming language.
      booleanwasNull()
      Retrieves whether the last value read was SQLNULL.

    • Method Detail

      • 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