1. /*
  2. * @(#)SQLInput.java 1.16 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. * An input stream that contains a stream of values representing an
  13. * instance of an SQL structured or distinct type.
  14. * This interface, used only for custom mapping, is used by the driver
  15. * behind the scenes, and a programmer never directly invokes
  16. * <code>SQLInput</code> methods. The <code>readXXX</code> methods
  17. * provide a way to read the values in an <code>SQLInput</code> object.
  18. * The method <code>wasNull</code> is used to determine whether the
  19. * the last value read was SQL <code>NULL</code>.
  20. * <P>When the method <code>getObject</code> is called with an
  21. * object of a class implementing the interface <code>SQLData</code>,
  22. * the JDBC driver calls the method <code>SQLData.getSQLType</code>
  23. * to determine the SQL type of the user-defined type (UDT)
  24. * being custom mapped. The driver
  25. * creates an instance of <code>SQLInput</code>, populating it with the
  26. * attributes of the UDT. The driver then passes the input
  27. * stream to the method <code>SQLData.readSQL</code>, which in turn
  28. * calls the <code>SQLInput.readXXX</code> methods
  29. * in its implementation for reading the
  30. * attributes from the input stream.
  31. * @since 1.2
  32. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  33. * 2.0 API</a>
  34. */
  35. public interface SQLInput {
  36. //================================================================
  37. // Methods for reading attributes from the stream of SQL data.
  38. // These methods correspond to the column-accessor methods of
  39. // java.sql.ResultSet.
  40. //================================================================
  41. /**
  42. * Reads the next attribute in the stream as a <code>String</code>
  43. * in the Java programming language.
  44. *
  45. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  46. * @exception SQLException if a database access error occurs
  47. */
  48. String readString() throws SQLException;
  49. /**
  50. * Reads the next attribute in the stream as a <code>boolean</code>
  51. * in the Java programming language.
  52. *
  53. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>false</code>
  54. * @exception SQLException if a database access error occurs
  55. */
  56. boolean readBoolean() throws SQLException;
  57. /**
  58. * Reads the next attribute in the stream as a <code>byte</code>
  59. * in the Java programming language.
  60. *
  61. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
  62. * @exception SQLException if a database access error occurs
  63. */
  64. byte readByte() throws SQLException;
  65. /**
  66. * Reads the next attribute in the stream as a <code>short</code>
  67. * in the Java programming language.
  68. *
  69. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
  70. * @exception SQLException if a database access error occurs
  71. */
  72. short readShort() throws SQLException;
  73. /**
  74. * Reads the next attribute in the stream as an <code>int</code>
  75. * in the Java programming language.
  76. *
  77. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
  78. * @exception SQLException if a database access error occurs
  79. */
  80. int readInt() throws SQLException;
  81. /**
  82. * Reads the next attribute in the stream as a <code>long</code>
  83. * in the Java programming language.
  84. *
  85. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
  86. * @exception SQLException if a database access error occurs
  87. */
  88. long readLong() throws SQLException;
  89. /**
  90. * Reads the next attribute in the stream as a <code>float</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. */
  96. float readFloat() throws SQLException;
  97. /**
  98. * Reads the next attribute in the stream as a <code>double</code>
  99. * in the Java programming language.
  100. *
  101. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>0</code>
  102. * @exception SQLException if a database access error occurs
  103. */
  104. double readDouble() throws SQLException;
  105. /**
  106. * Reads the next attribute in the stream as a <code>java.math.BigDecimal</code>
  107. * object in the Java programming language.
  108. *
  109. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  110. * @exception SQLException if a database access error occurs
  111. */
  112. java.math.BigDecimal readBigDecimal() throws SQLException;
  113. /**
  114. * Reads the next attribute in the stream as an array of bytes
  115. * in the Java programming language.
  116. *
  117. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  118. * @exception SQLException if a database access error occurs
  119. */
  120. byte[] readBytes() throws SQLException;
  121. /**
  122. * Reads the next attribute in the stream as a <code>java.sql.Date</code> object.
  123. *
  124. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  125. * @exception SQLException if a database access error occurs
  126. */
  127. java.sql.Date readDate() throws SQLException;
  128. /**
  129. * Reads the next attribute in the stream as a <code>java.sql.Time</code> object.
  130. *
  131. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  132. * @exception SQLException if a database access error occurs
  133. */
  134. java.sql.Time readTime() throws SQLException;
  135. /**
  136. * Reads the next attribute in the stream as a <code>java.sql.Timestamp</code> object.
  137. *
  138. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  139. * @exception SQLException if a database access error occurs
  140. */
  141. java.sql.Timestamp readTimestamp() throws SQLException;
  142. /**
  143. * Returns the next attribute in the stream as a stream of Unicode characters.
  144. *
  145. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  146. * @exception SQLException if a database access error occurs
  147. */
  148. java.io.Reader readCharacterStream() throws SQLException;
  149. /**
  150. * Returns the next attribute in the stream as a stream of ASCII characters.
  151. *
  152. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  153. * @exception SQLException if a database access error occurs
  154. */
  155. java.io.InputStream readAsciiStream() throws SQLException;
  156. /**
  157. * Returns the next attribute in the stream as a stream of uninterpreted
  158. * bytes.
  159. *
  160. * @return the attribute; if the value is SQL <code>NULL</code>, returns <code>null</code>
  161. * @exception SQLException if a database access error occurs
  162. */
  163. java.io.InputStream readBinaryStream() throws SQLException;
  164. //================================================================
  165. // Methods for reading items of SQL user-defined types from the stream.
  166. //================================================================
  167. /**
  168. * Returns the datum at the head of the stream as an
  169. * <code>Object</code> in the Java programming language. The
  170. * actual type of the object returned is determined by the default type
  171. * mapping, and any customizations present in this stream's type map.
  172. *
  173. * <P>A type map is registered with the stream by the JDBC driver before the
  174. * stream is passed to the application.
  175. *
  176. * <P>When the datum at the head of the stream is an SQL <code>NULL</code>,
  177. * the method returns <code>null</code>. If the datum is an SQL structured or distinct
  178. * type, it determines the SQL type of the datum at the head of the stream.
  179. * If the stream's type map has an entry for that SQL type, the driver
  180. * constructs an object of the appropriate class and calls the method
  181. * <code>SQLData.readSQL</code> on that object, which reads additional data from the
  182. * stream, using the protocol described for that method.
  183. *
  184. * @return the datum at the head of the stream as an <code>Object</code> in the
  185. * Java programming language;<code>null</code> if the datum is SQL <code>NULL</code>
  186. * @exception SQLException if a database access error occurs
  187. */
  188. Object readObject() throws SQLException;
  189. /**
  190. * Reads an SQL <code>REF</code> value from the stream and returns it as a
  191. * <code>Ref</code> object in the Java programming language.
  192. *
  193. * @return a <code>Ref</code> object representing the SQL <code>REF</code> value
  194. * at the head of the stream; <code>null</code> if the value read is
  195. * SQL <code>NULL</code>
  196. * @exception SQLException if a database access error occurs
  197. */
  198. Ref readRef() throws SQLException;
  199. /**
  200. * Reads an SQL <code>BLOB</code> value from the stream and returns it as a
  201. * <code>Blob</code> object in the Java programming language.
  202. *
  203. * @return a <code>Blob</code> object representing data of the SQL <code>BLOB</code> value
  204. * at the head of the stream; <code>null</code> if the value read is
  205. * SQL <code>NULL</code>
  206. * @exception SQLException if a database access error occurs
  207. */
  208. Blob readBlob() throws SQLException;
  209. /**
  210. * Reads an SQL <code>CLOB</code> value from the stream and returns it as a
  211. * <code>Clob</code> object in the Java programming language.
  212. *
  213. * @return a <code>Clob</code> object representing data of the SQL <code>CLOB</code> value
  214. * at the head of the stream; <code>null</code> if the value read is
  215. * SQL <code>NULL</code>
  216. * @exception SQLException if a database access error occurs
  217. */
  218. Clob readClob() throws SQLException;
  219. /**
  220. * Reads an SQL <code>ARRAY</code> value from the stream and returns it as an
  221. * <code>Array</code> object in the Java programming language.
  222. *
  223. * @return an <code>Array</code> object representing data of the SQL
  224. * <code>ARRAY</code> value at the head of the stream; <code>null</code>
  225. * if the value read is SQL <code>NULL</code>
  226. * @exception SQLException if a database access error occurs
  227. */
  228. Array readArray() throws SQLException;
  229. /**
  230. * Determines whether the last value read was SQL <code>NULL</code>.
  231. *
  232. * @return <code>true</code> if the most recently read SQL value was SQL
  233. * <code>NULL</code> otherwise, <code>false</code>
  234. * @exception SQLException if a database access error occurs
  235. *
  236. */
  237. boolean wasNull() throws SQLException;
  238. }