1. /*
  2. * @(#)Array.java 1.17 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. *
  13. * <p>
  14. * The mapping in the Java programming language for the SQL type
  15. * <code>ARRAY</code>.
  16. * By default, an <code>Array</code> object is a transaction-duration
  17. * reference to an SQL <code>ARRAY</code> value. By default, an <code>Array</code>
  18. * object is implemented using an SQL LOCATOR(array) internally, which
  19. * means that an <code>Array</code> object contains a logical pointer
  20. * to the data in the SQL <code>ARRAY</code> value on the server rather
  21. * than containing the <code>ARRAY</code> value's data.
  22. * <p>
  23. * The <code>Array</code> interface provides methods for bringing an SQL
  24. * <code>ARRAY</code> value's data to the client as either an array or a
  25. * <code>ResultSet</code> object.
  26. * <p>
  27. * If the elements of the SQL <code>ARRAY</code>
  28. * are a UDT, they may be custom mapped. To create a custom mapping,
  29. * a programmer must do two things:
  30. * <ul>
  31. * <li>create a class that implements the {@link SQLData}
  32. * interface for the UDT to be custom mapped. This will typically be
  33. * done using a tool.
  34. * <li>make an entry in a type map that contains
  35. * <ul>
  36. * <li>the fully-qualified SQL type name of the UDT
  37. * <li>the <code>Class</code> object for the class implementing
  38. * <code>SQLData</code>
  39. * </ul>
  40. * </ul>
  41. * <p>
  42. * When a type map with an entry for
  43. * the base type is supplied to the methods <code>getArray</code>
  44. * and <code>getResultSet</code>, the mapping
  45. * it contains will be used to map the elements of the <code>ARRAY</code> value.
  46. * If no type map is supplied, which would typically be the case,
  47. * the connection's type map is used by default.
  48. * If the connection's type map or a type map supplied to a method has no entry
  49. * for the base type, the elements are mapped according to the standard mapping.
  50. * <p>
  51. * <b>NOTE:</b> This interface is new in the JDBC 2.0 API.
  52. *
  53. */
  54. public interface Array {
  55. /**
  56. * Returns the SQL type name of the elements in
  57. * the array designated by this <code>Array</code> object.
  58. * If the elements are a built-in type, it returns
  59. * the database-specific type name of the elements.
  60. * If the elements are a user-defined type (UDT),
  61. * this method returns the fully-qualified SQL type name.
  62. * @return a <code>String</code> that is the database-specific
  63. * name for a built-in base type or the fully-qualified SQL type
  64. * name for a base type that is a UDT
  65. * @exception SQLException if an error occurs while attempting
  66. * to access the type name
  67. * @since 1.2
  68. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  69. * 2.0 API</a>
  70. */
  71. String getBaseTypeName() throws SQLException;
  72. /**
  73. * Returns the JDBC type of the elements in the array designated
  74. * by this <code>Array</code> object.
  75. * @return a constant from the class {@link java.sql.Types} that is
  76. * the type code for the elements in the array designated by this
  77. * <code>Array</code> object.
  78. * @exception SQLException if an error occurs while attempting
  79. * to access the base type
  80. * @since 1.2
  81. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  82. * 2.0 API</a>
  83. */
  84. int getBaseType() throws SQLException;
  85. /**
  86. * Retrieves the contents of the SQL <code>ARRAY</code> value designated
  87. * by this
  88. * <code>Array</code> object in the form of an array in the Java
  89. * programming language. This version of the method <code>getArray</code>
  90. * uses the type map associated with the connection for customizations of
  91. * the type mappings.
  92. * @return an array in the Java programming language that contains
  93. * the ordered elements of the SQL <code>ARRAY</code> value
  94. * designated by this object
  95. * @exception SQLException if an error occurs while attempting to
  96. * access the array
  97. * @since 1.2
  98. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  99. * 2.0 API</a>
  100. */
  101. Object getArray() throws SQLException;
  102. /**
  103. * Retrieves the contents of the SQL array designated by this
  104. * <code>Array</code> object.
  105. * This method uses
  106. * the specified <code>map</code> for type map customizations
  107. * unless the base type of the array does not match a user-defined
  108. * type in <code>map</code>, in which case it
  109. * uses the standard mapping. This version of the method
  110. * <code>getArray</code> uses either the given type map or the standard mapping;
  111. * it never uses the type map associated with the connection.
  112. *
  113. * @param map a <code>java.util.Map</code> object that contains mappings
  114. * of SQL type names to classes in the Java programming language
  115. * @return an array in the Java programming language that contains the ordered
  116. * elements of the SQL array designated by this object
  117. * @exception SQLException if an error occurs while attempting to
  118. * access the array
  119. * @since 1.2
  120. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  121. * 2.0 API</a>
  122. */
  123. Object getArray(java.util.Map map) throws SQLException;
  124. /**
  125. * Returns an array containing a slice of the SQL <code>ARRAY</code>
  126. * value designated by this <code>Array</code> object, beginning with the
  127. * specified <code>index</code> and containing up to <code>count</code>
  128. * successive elements of the SQL array. This method uses the type map
  129. * associated with the connection for customizations of the type mappings.
  130. * @param index the array index of the first element to retrieve;
  131. * the first element is at index 1
  132. * @param count the number of successive SQL array elements to retrieve
  133. * @return an array containing up to <code>count</code> consecutive elements
  134. * of the SQL array, beginning with element <code>index</code>
  135. * @exception SQLException if an error occurs while attempting to
  136. * access the array
  137. * @since 1.2
  138. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  139. * 2.0 API</a>
  140. */
  141. Object getArray(long index, int count) throws SQLException;
  142. /**
  143. * Returns an array containing a slice of the SQL array object
  144. * designated by this <code>Array</code> object, beginning with the specified
  145. * <code>index</code> and containing up to <code>count</code>
  146. * successive elements of the SQL array.
  147. * <P>
  148. * This method uses
  149. * the specified <code>map</code> for type map customizations
  150. * unless the base type of the array does not match a user-defined
  151. * type in <code>map</code>, in which case it
  152. * uses the standard mapping. This version of the method
  153. * <code>getArray</code> uses either the given type map or the standard mapping;
  154. * it never uses the type map associated with the connection.
  155. *
  156. * @param index the array index of the first element to retrieve;
  157. * the first element is at index 1
  158. * @param count the number of successive SQL array elements to
  159. * retrieve
  160. * @param map a <code>java.util.Map</code> object
  161. * that contains SQL type names and the classes in
  162. * the Java programming language to which they are mapped
  163. * @return an array containing up to <code>count</code>
  164. * consecutive elements of the SQL array designated by this
  165. * <code>Array</code> object, beginning with element
  166. * <code>index</code>.
  167. * @exception SQLException if an error occurs while attempting to
  168. * access the array
  169. * @since 1.2
  170. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  171. * 2.0 API</a>
  172. */
  173. Object getArray(long index, int count, java.util.Map map)
  174. throws SQLException;
  175. /**
  176. * Returns a result set that contains the elements of the SQL
  177. * <code>ARRAY</code> value
  178. * designated by this <code>Array</code> object. If appropriate,
  179. * the elements of the array are mapped using the connection's type
  180. * map; otherwise, the standard mapping is used.
  181. * <p>
  182. * The result set contains one row for each array element, with
  183. * two columns in each row. The second column stores the element
  184. * value; the first column stores the index into the array for
  185. * that element (with the first array element being at index 1).
  186. * The rows are in ascending order corresponding to
  187. * the order of the indices.
  188. * @return a {@link ResultSet} object containing one row for each
  189. * of the elements in the array designated by this <code>Array</code>
  190. * object, with the rows in ascending order based on the indices.
  191. * @exception SQLException if an error occurs while attempting to
  192. * access the array
  193. * @since 1.2
  194. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  195. * 2.0 API</a>
  196. */
  197. ResultSet getResultSet () throws SQLException;
  198. /**
  199. * Returns a result set that contains the elements of the SQL
  200. * <code>ARRAY</code> value
  201. * designated by this <code>Array</code> object.
  202. * This method uses
  203. * the specified <code>map</code> for type map customizations
  204. * unless the base type of the array does not match a user-defined
  205. * type in <code>map</code>, in which case it
  206. * uses the standard mapping. This version of the method
  207. * <code>getResultSet</code> uses either the given type map or the standard mapping;
  208. * it never uses the type map associated with the connection.
  209. * <p>
  210. * The result set contains one row for each array element, with
  211. * two columns in each row. The second column stores the element
  212. * value; the first column stores the index into the array for
  213. * that element (with the first array element being at index 1).
  214. * The rows are in ascending order corresponding to
  215. * the order of the indices.
  216. * @param map contains the mapping of SQL user-defined types to
  217. * classes in the Java programming language
  218. * @return a <code>ResultSet</code> object containing one row for each
  219. * of the elements in the array designated by this <code>Array</code>
  220. * object, with the rows in ascending order based on the indices.
  221. * @exception SQLException if an error occurs while attempting to
  222. * access the array
  223. * @since 1.2
  224. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  225. * 2.0 API</a>
  226. */
  227. ResultSet getResultSet (java.util.Map map) throws SQLException;
  228. /**
  229. * Returns a result set holding the elements of the subarray that
  230. * starts at index <code>index</code> and contains up to
  231. * <code>count</code> successive elements. This method uses
  232. * the connection's type map to map the elements of the array if
  233. * the map contains an entry for the base type. Otherwise, the
  234. * standard mapping is used.
  235. * <P>
  236. * The result set has one row for each element of the SQL array
  237. * designated by this object, with the first row containing the
  238. * element at index <code>index</code>. The result set has
  239. * up to <code>count</code> rows in ascending order based on the
  240. * indices. Each row has two columns: The second column stores
  241. * the element value; the first column stores the index into the
  242. * array for that element.
  243. * @param index the array index of the first element to retrieve;
  244. * the first element is at index 1
  245. * @param count the number of successive SQL array elements to retrieve
  246. * @return a <code>ResultSet</code> object containing up to
  247. * <code>count</code> consecutive elements of the SQL array
  248. * designated by this <code>Array</code> object, starting at
  249. * index <code>index</code>.
  250. * @exception SQLException if an error occurs while attempting to
  251. * access the array
  252. * @since 1.2
  253. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  254. * 2.0 API</a>
  255. */
  256. ResultSet getResultSet(long index, int count) throws SQLException;
  257. /**
  258. * Returns a result set holding the elements of the subarray that
  259. * starts at index <code>index</code> and contains up to
  260. * <code>count</code> successive elements.
  261. * This method uses
  262. * the specified <code>map</code> for type map customizations
  263. * unless the base type of the array does not match a user-defined
  264. * type in <code>map</code>, in which case it
  265. * uses the standard mapping. This version of the method
  266. * <code>getResultSet</code> uses either the given type map or the standard mapping;
  267. * it never uses the type map associated with the connection.
  268. * <P>
  269. * The result set has one row for each element of the SQL array
  270. * designated by this object, with the first row containing the
  271. * element at index <code>index</code>. The result set has
  272. * up to <code>count</code> rows in ascending order based on the
  273. * indices. Each row has two columns: The second column stores
  274. * the element value; the first column stroes the index into the
  275. * array for that element.
  276. * @param index the array index of the first element to retrieve;
  277. * the first element is at index 1
  278. * @param count the number of successive SQL array elements to retrieve
  279. * @param map the <code>Map</code> object that contains the mapping
  280. * of SQL type names to classes in the Java(tm) programming language
  281. * @return a <code>ResultSet</code> object containing up to
  282. * <code>count</code> consecutive elements of the SQL array
  283. * designated by this <code>Array</code> object, starting at
  284. * index <code>index</code>.
  285. * @exception SQLException if an error occurs while attempting to
  286. * access the array
  287. * @since 1.2
  288. * @see <a href="package-summary.html#2.0 API">What Is in the JDBC
  289. * 2.0 API</a>
  290. *
  291. */
  292. ResultSet getResultSet (long index, int count, java.util.Map map)
  293. throws SQLException;
  294. }