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