1 /*

     2  * Copyright 1998-2006 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.sql;

    27 

    28 /**

    29  * An input stream that contains a stream of values representing an

    30  * instance of an SQL structured type or an SQL distinct type.

    31  * This interface, used only for custom mapping, is used by the driver

    32  * behind the scenes, and a programmer never directly invokes

    33  * <code>SQLInput</code> methods. The <i>reader</i> methods

    34  * (<code>readLong</code>, <code>readBytes</code>, and so on)

    35  * provide a way  for an implementation of the <code>SQLData</code>

    36  *  interface to read the values in an <code>SQLInput</code> object.

    37  *  And as described in <code>SQLData</code>, calls to reader methods must

    38  * be made in the order that their corresponding attributes appear in the

    39  * SQL definition of the type.

    40  * The method <code>wasNull</code> is used to determine whether

    41  * the last value read was SQL <code>NULL</code>.

    42  * <P>When the method <code>getObject</code> is called with an

    43  * object of a class implementing the interface <code>SQLData</code>,

    44  * the JDBC driver calls the method <code>SQLData.getSQLType</code>

    45  * to determine the SQL type of the user-defined type (UDT)

    46  * being custom mapped. The driver

    47  * creates an instance of <code>SQLInput</code>, populating it with the

    48  * attributes of the UDT.  The driver then passes the input

    49  * stream to the method <code>SQLData.readSQL</code>, which in turn

    50  * calls the <code>SQLInput</code> reader methods

    51  * in its implementation for reading the

    52  * attributes from the input stream.

    53  * @since 1.2

    54  */

    55 

    56 public interface SQLInput {

    57 

    58 

    59     //================================================================

    60     // Methods for reading attributes from the stream of SQL data.

    61     // These methods correspond to the column-accessor methods of

    62     // java.sql.ResultSet.

    63     //================================================================

    64 

    65     /**

    66      * Reads the next attribute in the stream and returns it as a <code>String</code>

    67      * in the Java programming language.

    68      *

    69      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

    70      * @exception SQLException if a database access error occurs

    71      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

    72      * this method

    73      * @since 1.2

    74      */

    75     String readString() throws SQLException;

    76 

    77     /**

    78      * Reads the next attribute in the stream and returns it as a <code>boolean</code>

    79      * in the Java programming language.

    80      *

    81      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>false</code>

    82      * @exception SQLException if a database access error occurs

    83      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

    84      * this method

    85      * @since 1.2

    86      */

    87     boolean readBoolean() throws SQLException;

    88 

    89     /**

    90      * Reads the next attribute in the stream and returns it as a <code>byte</code>

    91      * in the Java programming language.

    92      *

    93      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>

    94      * @exception SQLException if a database access error occurs

    95      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

    96      * this method

    97      * @since 1.2

    98      */

    99     byte readByte() throws SQLException;

   100 

   101     /**

   102      * Reads the next attribute in the stream and returns it as a <code>short</code>

   103      * in the Java programming language.

   104      *

   105      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>

   106      * @exception SQLException if a database access error occurs

   107      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   108      * this method

   109      * @since 1.2

   110      */

   111     short readShort() throws SQLException;

   112 

   113     /**

   114      * Reads the next attribute in the stream and returns it as an <code>int</code>

   115      * in the Java programming language.

   116      *

   117      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>

   118      * @exception SQLException if a database access error occurs

   119      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   120      * this method

   121      * @since 1.2

   122      */

   123     int readInt() throws SQLException;

   124 

   125     /**

   126      * Reads the next attribute in the stream and returns it as a <code>long</code>

   127      * in the Java programming language.

   128      *

   129      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>

   130      * @exception SQLException if a database access error occurs

   131      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   132      * this method

   133      * @since 1.2

   134      */

   135     long readLong() throws SQLException;

   136 

   137     /**

   138      * Reads the next attribute in the stream and returns it as a <code>float</code>

   139      * in the Java programming language.

   140      *

   141      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>

   142      * @exception SQLException if a database access error occurs

   143      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   144      * this method

   145      * @since 1.2

   146      */

   147     float readFloat() throws SQLException;

   148 

   149     /**

   150      * Reads the next attribute in the stream and returns it as a <code>double</code>

   151      * in the Java programming language.

   152      *

   153      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>

   154      * @exception SQLException if a database access error occurs

   155      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   156      * this method

   157      * @since 1.2

   158      */

   159     double readDouble() throws SQLException;

   160 

   161     /**

   162      * Reads the next attribute in the stream and returns it as a <code>java.math.BigDecimal</code>

   163      * object in the Java programming language.

   164      *

   165      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   166      * @exception SQLException if a database access error occurs

   167      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   168      * this method

   169      * @since 1.2

   170      */

   171     java.math.BigDecimal readBigDecimal() throws SQLException;

   172 

   173     /**

   174      * Reads the next attribute in the stream and returns it as an array of bytes

   175      * in the Java programming language.

   176      *

   177      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   178      * @exception SQLException if a database access error occurs

   179      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   180      * this method

   181      * @since 1.2

   182      */

   183     byte[] readBytes() throws SQLException;

   184 

   185     /**

   186      * Reads the next attribute in the stream and returns it as a <code>java.sql.Date</code> object.

   187      *

   188      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   189      * @exception SQLException if a database access error occurs

   190      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   191      * this method

   192      * @since 1.2

   193      */

   194     java.sql.Date readDate() throws SQLException;

   195 

   196     /**

   197      * Reads the next attribute in the stream and returns it as a <code>java.sql.Time</code> object.

   198      *

   199      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   200      * @exception SQLException if a database access error occurs

   201      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   202      * this method

   203      * @since 1.2

   204      */

   205     java.sql.Time readTime() throws SQLException;

   206 

   207     /**

   208      * Reads the next attribute in the stream and returns it as a <code>java.sql.Timestamp</code> object.

   209      *

   210      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   211      * @exception SQLException if a database access error occurs

   212      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   213      * this method

   214      * @since 1.2

   215      */

   216     java.sql.Timestamp readTimestamp() throws SQLException;

   217 

   218     /**

   219      * Reads the next attribute in the stream and returns it as a stream of Unicode characters.

   220      *

   221      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   222      * @exception SQLException if a database access error occurs

   223      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   224      * this method

   225      * @since 1.2

   226      */

   227     java.io.Reader readCharacterStream() throws SQLException;

   228 

   229     /**

   230      * Reads the next attribute in the stream and returns it as a stream of ASCII characters.

   231      *

   232      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   233      * @exception SQLException if a database access error occurs

   234      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   235      * this method

   236      * @since 1.2

   237      */

   238     java.io.InputStream readAsciiStream() throws SQLException;

   239 

   240     /**

   241      * Reads the next attribute in the stream and returns it as a stream of uninterpreted

   242      * bytes.

   243      *

   244      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   245      * @exception SQLException if a database access error occurs

   246      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   247      * this method

   248      * @since 1.2

   249      */

   250     java.io.InputStream readBinaryStream() throws SQLException;

   251 

   252     //================================================================

   253     // Methods for reading items of SQL user-defined types from the stream.

   254     //================================================================

   255 

   256     /**

   257      * Reads the datum at the head of the stream and returns it as an

   258      * <code>Object</code> in the Java programming language.  The

   259      * actual type of the object returned is determined by the default type

   260      * mapping, and any customizations present in this stream's type map.

   261      *

   262      * <P>A type map is registered with the stream by the JDBC driver before the

   263      * stream is passed to the application.

   264      *

   265      * <P>When the datum at the head of the stream is an SQL <code>NULL</code>,

   266      * the method returns <code>null</code>.  If the datum is an SQL structured or distinct

   267      * type, it determines the SQL type of the datum at the head of the stream.

   268      * If the stream's type map has an entry for that SQL type, the driver

   269      * constructs an object of the appropriate class and calls the method

   270      * <code>SQLData.readSQL</code> on that object, which reads additional data from the

   271      * stream, using the protocol described for that method.

   272      *

   273      * @return the datum at the head of the stream as an <code>Object</code> in the

   274      * Java programming language;<code>null</code> if the datum is SQL <code>NULL</code>

   275      * @exception SQLException if a database access error occurs

   276      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   277      * this method

   278      * @since 1.2

   279      */

   280     Object readObject() throws SQLException;

   281 

   282     /**

   283      * Reads an SQL <code>REF</code> value from the stream and returns it as a

   284      * <code>Ref</code> object in the Java programming language.

   285      *

   286      * @return a <code>Ref</code> object representing the SQL <code>REF</code> value

   287      * at the head of the stream; <code>null</code> if the value read is

   288      * SQL <code>NULL</code>

   289      * @exception SQLException if a database access error occurs

   290      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   291      * this method

   292      * @since 1.2

   293      */

   294     Ref readRef() throws SQLException;

   295 

   296     /**

   297      * Reads an SQL <code>BLOB</code> value from the stream and returns it as a

   298      * <code>Blob</code> object in the Java programming language.

   299      *

   300      * @return a <code>Blob</code> object representing data of the SQL <code>BLOB</code> value

   301      * at the head of the stream; <code>null</code> if the value read is

   302      * SQL <code>NULL</code>

   303      * @exception SQLException if a database access error occurs

   304      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   305      * this method

   306      * @since 1.2

   307      */

   308     Blob readBlob() throws SQLException;

   309 

   310     /**

   311      * Reads an SQL <code>CLOB</code> value from the stream and returns it as a

   312      * <code>Clob</code> object in the Java programming language.

   313      *

   314      * @return a <code>Clob</code> object representing data of the SQL <code>CLOB</code> value

   315      * at the head of the stream; <code>null</code> if the value read is

   316      * SQL <code>NULL</code>

   317      * @exception SQLException if a database access error occurs

   318      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   319      * this method

   320      * @since 1.2

   321      */

   322     Clob readClob() throws SQLException;

   323 

   324     /**

   325      * Reads an SQL <code>ARRAY</code> value from the stream and returns it as an

   326      * <code>Array</code> object in the Java programming language.

   327      *

   328      * @return an <code>Array</code> object representing data of the SQL

   329      * <code>ARRAY</code> value at the head of the stream; <code>null</code>

   330      * if the value read is SQL <code>NULL</code>

   331      * @exception SQLException if a database access error occurs

   332      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   333      * this method

   334      * @since 1.2

   335      */

   336     Array readArray() throws SQLException;

   337 

   338     /**

   339      * Retrieves whether the last value read was SQL <code>NULL</code>.

   340      *

   341      * @return <code>true</code> if the most recently read SQL value was SQL

   342      * <code>NULL</code>; <code>false</code> otherwise

   343      * @exception SQLException if a database access error occurs

   344      *

   345      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   346      * this method

   347      * @since 1.2

   348      */

   349     boolean wasNull() throws SQLException;

   350 

   351     //---------------------------- JDBC 3.0 -------------------------

   352 

   353     /**

   354      * Reads an SQL <code>DATALINK</code> value from the stream and returns it as a

   355      * <code>java.net.URL</code> object in the Java programming language.

   356      *

   357      * @return a <code>java.net.URL</code> object.

   358      * @exception SQLException if a database access error occurs,

   359      *            or if a URL is malformed

   360      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   361      * this method

   362      * @since 1.4

   363      */

   364     java.net.URL readURL() throws SQLException;

   365 

   366      //---------------------------- JDBC 4.0 -------------------------

   367 

   368     /**

   369      * Reads an SQL <code>NCLOB</code> value from the stream and returns it as a

   370      * <code>NClob</code> object in the Java programming language.

   371      *

   372      * @return a <code>NClob</code> object representing data of the SQL <code>NCLOB</code> value

   373      * at the head of the stream; <code>null</code> if the value read is

   374      * SQL <code>NULL</code>

   375      * @exception SQLException if a database access error occurs

   376      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   377      * this method

   378      * @since 1.6

   379      */

   380     NClob readNClob() throws SQLException;

   381 

   382     /**

   383      * Reads the next attribute in the stream and returns it as a <code>String</code>

   384      * in the Java programming language. It is intended for use when

   385      * accessing  <code>NCHAR</code>,<code>NVARCHAR</code>

   386      * and <code>LONGNVARCHAR</code> columns.

   387      *

   388      * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>

   389      * @exception SQLException if a database access error occurs

   390      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   391      * this method

   392      * @since 1.6

   393      */

   394     String readNString() throws SQLException;

   395 

   396     /**

   397      * Reads an SQL <code>XML</code> value from the stream and returns it as a

   398      * <code>SQLXML</code> object in the Java programming language.

   399      *

   400      * @return a <code>SQLXML</code> object representing data of the SQL <code>XML</code> value

   401      * at the head of the stream; <code>null</code> if the value read is

   402      * SQL <code>NULL</code>

   403      * @exception SQLException if a database access error occurs

   404      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   405      * this method

   406      * @since 1.6

   407      */

   408     SQLXML readSQLXML() throws SQLException;

   409 

   410     /**

   411      * Reads an SQL <code>ROWID</code> value from the stream and returns it as a

   412      * <code>RowId</code> object in the Java programming language.

   413      *

   414      * @return a <code>RowId</code> object representing data of the SQL <code>ROWID</code> value

   415      * at the head of the stream; <code>null</code> if the value read is

   416      * SQL <code>NULL</code>

   417      * @exception SQLException if a database access error occurs

   418      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   419      * this method

   420      * @since 1.6

   421      */

   422     RowId readRowId() throws SQLException;

   423 

   424 }