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 / SQLOutput.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  8.2 KB  |  246 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)SQLOutput.java    1.10 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.  * The output stream for writing the attributes of a user-defined
  20.  * type back to the database.  This interface, used 
  21.  * only for custom mapping, is used by the driver, and its
  22.  * methods are never directly invoked by a programmer.
  23.  * <p>When an object of a class implementing interface
  24.  * <code>SQLData</code> is passed as an argument to an SQL statement, the
  25.  * JDBC driver calls <code>SQLData.getSQLType</code> to
  26.  * determine the  kind of SQL
  27.  * datum being passed to the database.
  28.  * The driver then creates an instance of <code>SQLOutput</code> and
  29.  * passes it to the method <code>SQLData.writeSQL</code>.
  30.  * The method <code>writeSQL</code> in turn calls the
  31.  * appropriate <code>SQLOutput.writeXXX</code> methods 
  32.  * to write data from the <code>SQLData</code> object to
  33.  * the <code>SQLOutput</code> output stream as the 
  34.  * representation of an SQL user-defined type.
  35.  */
  36.  
  37.  public interface SQLOutput {
  38.  
  39.   //================================================================
  40.   // Methods for writing attributes to the stream of SQL data.
  41.   // These methods correspond to the column-accessor methods of
  42.   // java.sql.ResultSet.
  43.   //================================================================
  44.  
  45.   /**
  46.    * Writes the next attribute to the stream as a Java String.
  47.    *
  48.    * @param x the value to pass to the database.
  49.    * @exception SQLException if a database access error occurs
  50.    */
  51.   void writeString(String x) throws SQLException;
  52.  
  53.   /**
  54.    * Writes the next attribute to the stream as a Java boolean.
  55.    *
  56.    * @param x the value to pass to the database.
  57.    * @exception SQLException if a database access error occurs
  58.    */
  59.   void writeBoolean(boolean x) throws SQLException;
  60.  
  61.   /**
  62.    * Writes the next attribute to the stream as a Java byte.
  63.    *
  64.    * @param x the value to pass to the database.
  65.    * @exception SQLException if a database access error occurs
  66.    */
  67.   void writeByte(byte x) throws SQLException;
  68.  
  69.   /**
  70.    * Writes the next attribute to the stream as a Java short.
  71.    *
  72.    * @param x the value to pass to the database.
  73.    * @exception SQLException if a database access error occurs
  74.    */
  75.   void writeShort(short x) throws SQLException;
  76.  
  77.   /**
  78.    * Writes the next attribute to the stream as a Java int.
  79.    *
  80.    * @param x the value to pass to the database.
  81.    * @exception SQLException if a database access error occurs
  82.    */
  83.   void writeInt(int x) throws SQLException;
  84.  
  85.   /**
  86.    * Writes the next attribute to the stream as a Java long.
  87.    *
  88.    * @param x the value to pass to the database.
  89.    * @exception SQLException if a database access error occurs
  90.    */
  91.   void writeLong(long x) throws SQLException;
  92.  
  93.   /**
  94.    * Writes the next attribute to the stream as a Java float.
  95.    *
  96.    * @param x the value to pass to the database.
  97.    * @exception SQLException if a database access error occurs
  98.    */
  99.   void writeFloat(float x) throws SQLException;
  100.  
  101.   /**
  102.    * Writes the next attribute to the stream as a Java double.
  103.    *
  104.    * @param x the value to pass to the database.
  105.    * @exception SQLException if a database access error occurs
  106.    */
  107.   void writeDouble(double x) throws SQLException;
  108.  
  109.   /**
  110.    * Writes the next attribute to the stream as a java.math.BigDecimal object.
  111.    *
  112.    * @param x the value to pass to the database.
  113.    * @exception SQLException if a database access error occurs
  114.    */
  115.   void writeBigDecimal(java.math.BigDecimal x) throws SQLException;
  116.  
  117.   /**
  118.    * Writes the next attribute to the stream as an array of bytes.
  119.    *
  120.    * @param x the value to pass to the database.
  121.    * @exception SQLException if a database access error occurs
  122.    */
  123.   void writeBytes(byte[] x) throws SQLException;
  124.  
  125.   /**
  126.    * Writes the next attribute to the stream as a java.sql.Date object.
  127.    *
  128.    * @param x the value to pass to the database.
  129.    * @exception SQLException if a database access error occurs
  130.    */
  131.   void writeDate(java.sql.Date x) throws SQLException;
  132.  
  133.   /**
  134.    * Writes the next attribute to the stream as a java.sql.Time object.
  135.    *
  136.    * @param x the value to pass to the database.
  137.    * @exception SQLException if a database access error occurs
  138.    */
  139.   void writeTime(java.sql.Time x) throws SQLException;
  140.  
  141.   /**
  142.    * Writes the next attribute to the stream as a java.sql.Timestamp object.
  143.    *
  144.    * @param x the value to pass to the database.
  145.    * @exception SQLException if a database access error occurs
  146.    */
  147.   void writeTimestamp(java.sql.Timestamp x) throws SQLException;
  148.  
  149.   /**
  150.    * Returns the next attribute to the stream as a stream of Unicode characters.
  151.    *
  152.    * @param x the value to pass to the database.
  153.    * @exception SQLException if a database access error occurs
  154.    */
  155.   void writeCharacterStream(java.io.Reader x) throws SQLException;
  156.  
  157.   /**
  158.    * Returns the next attribute to the stream as a stream of ASCII characters.
  159.    *
  160.    * @param x the value to pass to the database.
  161.    * @exception SQLException if a database access error occurs
  162.    */
  163.   void writeAsciiStream(java.io.InputStream x) throws SQLException;
  164.  
  165.   /**
  166.    * Returns the next attribute to the stream as a stream of uninterpreted
  167.    * bytes.
  168.    *
  169.    * @param x the value to pass to the database.
  170.    * @exception SQLException if a database access error occurs
  171.    */
  172.   void writeBinaryStream(java.io.InputStream x) throws SQLException;
  173.   
  174.   //================================================================
  175.   // Methods for writing items of SQL user-defined types to the stream.
  176.   // These methods pass objects to the database as values of SQL
  177.   // Structured Types, Distinct Types, Constructed Types, and Locator
  178.   // Types.  They decompose the Java object(s) and write leaf data
  179.   // items using the methods above.
  180.   //================================================================
  181.  
  182.   /**
  183.    * Writes to the stream the data contained in the given 
  184.    * <code>SQLData</code> object.
  185.    * When the <code>SQLData</code> object is null, this
  186.    * method writes an SQL NULL to the stream.  
  187.    * Otherwise, it calls the <code>SQLData.writeSQL</code>
  188.    * method of the given object, which 
  189.    * writes the object's attributes to the stream.
  190.    * The implementation of the method <code>SQLData.writeSQ</code>
  191.    * calls the appropriate <code>SQLOutput.writeXXX</code> method(s)
  192.    * for writing each of the object's attributes in order.
  193.    * The attributes must be read from an <code>SQLInput</code>
  194.    * input stream and written to an <code>SQLOutput</code>
  195.    * output stream in the same order in which they were
  196.    * listed in the SQL definition of the user-defined type.
  197.    * 
  198.    * @param x the object representing data of an SQL structured or
  199.    * distinct type
  200.    * @exception SQLException if a database access error occurs
  201.    */
  202.   void writeObject(SQLData x) throws SQLException;
  203.  
  204.   /**
  205.    * Writes a REF(<structured-type>) to the stream.
  206.    *
  207.    * @param x an object representing data of an SQL REF Type
  208.    * @exception SQLException if a database access error occurs
  209.    */
  210.   void writeRef(Ref x) throws SQLException;
  211.  
  212.   /**
  213.    * Writes a BLOB to the stream.
  214.    *
  215.    * @param x an object representing a BLOB
  216.    * @exception SQLException if a database access error occurs
  217.    */
  218.   void writeBlob(Blob x) throws SQLException;
  219.  
  220.   /**
  221.    * Writes a CLOB to the stream.
  222.    *
  223.    * @param x an object representing a CLOB
  224.    * @exception SQLException if a database access error occurs
  225.    */
  226.   void writeClob(Clob x) throws SQLException;
  227.  
  228.   /**
  229.    * Writes a structured-type to the stream.
  230.    *
  231.    * @param x an object representing data of a Structured Type
  232.    * @exception SQLException if a database access error occurs
  233.    */
  234.   void writeStruct(Struct x) throws SQLException;
  235.  
  236.   /**
  237.    * Writes an array to the stream.
  238.    *
  239.    * @param x an object representing an SQL array
  240.    * @exception SQLException if a database access error occurs
  241.    */
  242.   void writeArray(Array x) throws SQLException;
  243.  
  244. }
  245.  
  246.