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