Source for java.sql.SQLOutput

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