home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / sql / SQLInput.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  8.3 KB  |  244 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)SQLInput.java    1.11 98/09/29
  3.  * 
  4.  * Copyright 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * JDBC 2.0
  19.  *
  20.  * A input stream that contains a stream of values representing an 
  21.  * instance of an SQL structured or distinct type.
  22.  * This interface, used only for custom mapping, is used by the driver
  23.  * behind the scenes, and a programmer never directly invokes
  24.  * <code>SQLInput</code> methods.
  25.  * <P>When the method <code>getObject</code> is called with an
  26.  * object of a class implementing the interface <code>SQLData</code>,
  27.  * the JDBC driver calls the method <code>SQLData.getSQLType</code>
  28.  * to determine the SQL type of the user-defined type (UDT)
  29.  * being custom mapped. The driver
  30.  * creates an instance of <code>SQLInput</code>, populating it with the
  31.  * attributes of the UDT.  The driver then passes the input
  32.  * stream to the method <code>SQLData.readSQL</code>, which in turn 
  33.  * calls the <code>SQLInput.readXXX</code> methods 
  34.  * in its implementation for reading the
  35.  * attributes from the input stream.
  36.  */
  37.  
  38. public interface SQLInput {
  39.   
  40.  
  41.   //================================================================
  42.   // Methods for reading attributes from the stream of SQL data.
  43.   // These methods correspond to the column-accessor methods of
  44.   // java.sql.ResultSet.
  45.   //================================================================
  46.  
  47.   /**
  48.    * Reads the next attribute in the stream as a Java String.
  49.    *
  50.    * @return the attribute; if the value is SQL NULL, return null.
  51.    * @exception SQLException if a database access error occurs
  52.    */
  53.   String readString() throws SQLException;
  54.  
  55.   /**
  56.    * Reads the next attribute in the stream as a Java boolean.
  57.    *
  58.    * @return the attribute; if the value is SQL NULL, return null.
  59.    * @exception SQLException if a database access error occurs
  60.    */
  61.   boolean readBoolean() throws SQLException;
  62.  
  63.   /**
  64.    * Reads the next attribute in the stream as a Java byte.
  65.    *
  66.    * @return the attribute; if the value is SQL NULL, return null.
  67.    * @exception SQLException if a database access error occurs
  68.    */
  69.   byte readByte() throws SQLException;
  70.  
  71.   /**
  72.    * Reads the next attribute in the stream as a Java short.
  73.    *
  74.    * @return the attribute; if the value is SQL NULL, return null.
  75.    * @exception SQLException if a database access error occurs
  76.    */
  77.   short readShort() throws SQLException;
  78.  
  79.   /**
  80.    * Reads the next attribute in the stream as a Java int.
  81.    *
  82.    * @return the attribute; if the value is SQL NULL, return null.
  83.    * @exception SQLException if a database access error occurs
  84.    */
  85.   int readInt() throws SQLException;
  86.  
  87.   /**
  88.    * Reads the next attribute in the stream as a Java long.
  89.    *
  90.    * @return the attribute; if the value is SQL NULL, return null.
  91.    * @exception SQLException if a database access error occurs
  92.    */
  93.   long readLong() throws SQLException;
  94.  
  95.   /**
  96.    * Reads the next attribute in the stream as a Java float.
  97.    *
  98.    * @return the attribute; if the value is SQL NULL, return null.
  99.    * @exception SQLException if a database access error occurs
  100.    */
  101.   float readFloat() throws SQLException;
  102.  
  103.   /**
  104.    * Reads the next attribute in the stream as a Java double.
  105.    *
  106.    * @return the attribute; if the value is SQL NULL, return null.
  107.    * @exception SQLException if a database access error occurs
  108.    */
  109.   double readDouble() throws SQLException;
  110.  
  111.   /**
  112.    * Reads the next attribute in the stream as a java.math.BigDecimal object.
  113.    *
  114.    * @return the attribute; if the value is SQL NULL, return null.
  115.    * @exception SQLException if a database access error occurs
  116.    */
  117.   java.math.BigDecimal readBigDecimal() throws SQLException;
  118.  
  119.   /**
  120.    * Reads the next attribute in the stream as an array of bytes.
  121.    *
  122.    * @return the attribute; if the value is SQL NULL, return null.
  123.    * @exception SQLException if a database access error occurs
  124.    */
  125.   byte[] readBytes() throws SQLException;
  126.  
  127.   /**
  128.    * Reads the next attribute in the stream as a java.sql.Date object.
  129.    *
  130.    * @return the attribute; if the value is SQL NULL, return null.
  131.    * @exception SQLException if a database access error occurs
  132.    */
  133.   java.sql.Date readDate() throws SQLException;
  134.  
  135.   /**
  136.    * Reads the next attribute in the stream as a java.sql.Time object.
  137.    *
  138.    * @return the attribute; if the value is SQL NULL, return null.
  139.    * @exception SQLException if a database access error occurs
  140.    */
  141.   java.sql.Time readTime() throws SQLException;
  142.  
  143.   /**
  144.    * Reads the next attribute in the stream as a java.sql.Timestamp object.
  145.    *
  146.    * @return the attribute; if the value is SQL NULL, return null.
  147.    * @exception SQLException if a database access error occurs
  148.    */
  149.   java.sql.Timestamp readTimestamp() throws SQLException;
  150.  
  151.   /**
  152.    * Returns the next attribute in the stream as a stream of Unicode characters.
  153.    *
  154.    * @return the attribute; if the value is SQL NULL, return null.
  155.    * @exception SQLException if a database access error occurs
  156.    */
  157.   java.io.Reader readCharacterStream() throws SQLException;
  158.  
  159.   /**
  160.    * Returns the next attribute in the stream as a stream of ASCII characters.
  161.    *
  162.    * @return the attribute; if the value is SQL NULL, return null.
  163.    * @exception SQLException if a database access error occurs
  164.    */
  165.   java.io.InputStream readAsciiStream() throws SQLException;
  166.  
  167.   /**
  168.    * Returns the next attribute in the stream as a stream of uninterpreted
  169.    * bytes.
  170.    *
  171.    * @return the attribute; if the value is SQL NULL, return null.
  172.    * @exception SQLException if a database access error occurs
  173.    */
  174.   java.io.InputStream readBinaryStream() throws SQLException;
  175.   
  176.   //================================================================
  177.   // Methods for reading items of SQL user-defined types from the stream.
  178.   //================================================================
  179.  
  180.   /**
  181.    * Returns the datum at the head of the stream as a Java object.  The 
  182.    * actual type of the object returned is determined by the default type
  183.    * mapping, and any customizations present in this stream's type map.
  184.    *
  185.    * A type map is registered with the stream by the JDBC driver before the
  186.    * stream is passed to the application.
  187.    *
  188.    * When the datum at the head of the stream is an SQL NULL, 
  189.    * the method returns null.  If the datum is an SQL structured or distinct
  190.    * type, it determines the SQL type of the datum at the head of the stream, 
  191.    * constructs an object of the appropriate class, and calls the method 
  192.    * <code>SQLData.readSQL</code> on that object, which reads additional data from the 
  193.    * stream, using the protocol described for that method.
  194.    *
  195.    * @return the datum at the head of the stream as a Java object; null if
  196.    *         the datum is SQL NULL
  197.    * @exception SQLException if a database access error occurs
  198.    */
  199.   Object readObject() throws SQLException;
  200.  
  201.   /**
  202.    * Reads a REF(<structured-type>) from the stream.
  203.    *
  204.    * @return an object representing data of the SQL REF at the head of the stream
  205.    * @exception SQLException if a database access error occurs
  206.    */
  207.   Ref readRef() throws SQLException;
  208.  
  209.   /**
  210.    * Reads a BLOB from the stream.
  211.    *
  212.    * @return an object representing the SQL BLOB at the head of the stream
  213.    * @exception SQLException if a database access error occurs
  214.    */
  215.   Blob readBlob() throws SQLException;
  216.  
  217.   /**
  218.    * Reads a CLOB from the stream.
  219.    *
  220.    * @return an object representing the SQL CLOB at the head of the stream
  221.    * @exception SQLException if a database access error occurs
  222.    */
  223.   Clob readClob() throws SQLException;
  224.  
  225.   /**
  226.    * Reads an array from the stream.
  227.    *
  228.    * @return an object representing the SQL array at the head of the stream
  229.    * @exception SQLException if a database access error occurs
  230.    */
  231.   Array readArray() throws SQLException;
  232.  
  233.   /**
  234.    * Determines whether the last value read was null.
  235.    * 
  236.    * @return true if the most recently gotten SQL value was null;
  237.    *         otherwise,  false 
  238.    * @exception SQLException if a database access error occurs
  239.    * 
  240.    */
  241.   boolean wasNull() throws SQLException;
  242.  
  243. }
  244.