1 /* 2 * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.sql; 27 28 /** 29 * The mapping in the Java programming language for the SQL type 30 * <code>ARRAY</code>. 31 * By default, an <code>Array</code> value is a transaction-duration 32 * reference to an SQL <code>ARRAY</code> value. By default, an <code>Array</code> 33 * object is implemented using an SQL LOCATOR(array) internally, which 34 * means that an <code>Array</code> object contains a logical pointer 35 * to the data in the SQL <code>ARRAY</code> value rather 36 * than containing the <code>ARRAY</code> value's data. 37 * <p> 38 * The <code>Array</code> interface provides methods for bringing an SQL 39 * <code>ARRAY</code> value's data to the client as either an array or a 40 * <code>ResultSet</code> object. 41 * If the elements of the SQL <code>ARRAY</code> 42 * are a UDT, they may be custom mapped. To create a custom mapping, 43 * a programmer must do two things: 44 * <ul> 45 * <li>create a class that implements the {@link SQLData} 46 * interface for the UDT to be custom mapped. 47 * <li>make an entry in a type map that contains 48 * <ul> 49 * <li>the fully-qualified SQL type name of the UDT 50 * <li>the <code>Class</code> object for the class implementing 51 * <code>SQLData</code> 52 * </ul> 53 * </ul> 54 * <p> 55 * When a type map with an entry for 56 * the base type is supplied to the methods <code>getArray</code> 57 * and <code>getResultSet</code>, the mapping 58 * it contains will be used to map the elements of the <code>ARRAY</code> value. 59 * If no type map is supplied, which would typically be the case, 60 * the connection's type map is used by default. 61 * If the connection's type map or a type map supplied to a method has no entry 62 * for the base type, the elements are mapped according to the standard mapping. 63 * <p> 64 * All methods on the <code>Array</code> interface must be fully implemented if the 65 * JDBC driver supports the data type. 66 * 67 * @since 1.2 68 */ 69 70 public interface Array { 71 72 /** 73 * Retrieves the SQL type name of the elements in 74 * the array designated by this <code>Array</code> object. 75 * If the elements are a built-in type, it returns 76 * the database-specific type name of the elements. 77 * If the elements are a user-defined type (UDT), 78 * this method returns the fully-qualified SQL type name. 79 * 80 * @return a <code>String</code> that is the database-specific 81 * name for a built-in base type; or the fully-qualified SQL type 82 * name for a base type that is a UDT 83 * @exception SQLException if an error occurs while attempting 84 * to access the type name 85 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 86 * this method 87 * @since 1.2 88 */ 89 String getBaseTypeName() throws SQLException; 90 91 /** 92 * Retrieves the JDBC type of the elements in the array designated 93 * by this <code>Array</code> object. 94 * 95 * @return a constant from the class {@link java.sql.Types} that is 96 * the type code for the elements in the array designated by this 97 * <code>Array</code> object 98 * @exception SQLException if an error occurs while attempting 99 * to access the base type 100 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 101 * this method 102 * @since 1.2 103 */ 104 int getBaseType() throws SQLException; 105 106 /** 107 * Retrieves the contents of the SQL <code>ARRAY</code> value designated 108 * by this 109 * <code>Array</code> object in the form of an array in the Java 110 * programming language. This version of the method <code>getArray</code> 111 * uses the type map associated with the connection for customizations of 112 * the type mappings. 113 * <p> 114 * <strong>Note:</strong> When <code>getArray</code> is used to materialize 115 * a base type that maps to a primitive data type, then it is 116 * implementation-defined whether the array returned is an array of 117 * that primitive data type or an array of <code>Object</code>. 118 * 119 * @return an array in the Java programming language that contains 120 * the ordered elements of the SQL <code>ARRAY</code> value 121 * designated by this <code>Array</code> object 122 * @exception SQLException if an error occurs while attempting to 123 * access the array 124 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 125 * this method 126 * @since 1.2 127 */ 128 Object getArray() throws SQLException; 129 130 /** 131 * Retrieves the contents of the SQL <code>ARRAY</code> value designated by this 132 * <code>Array</code> object. 133 * This method uses 134 * the specified <code>map</code> for type map customizations 135 * unless the base type of the array does not match a user-defined 136 * type in <code>map</code>, in which case it 137 * uses the standard mapping. This version of the method 138 * <code>getArray</code> uses either the given type map or the standard mapping; 139 * it never uses the type map associated with the connection. 140 * <p> 141 * <strong>Note:</strong> When <code>getArray</code> is used to materialize 142 * a base type that maps to a primitive data type, then it is 143 * implementation-defined whether the array returned is an array of 144 * that primitive data type or an array of <code>Object</code>. 145 * 146 * @param map a <code>java.util.Map</code> object that contains mappings 147 * of SQL type names to classes in the Java programming language 148 * @return an array in the Java programming language that contains the ordered 149 * elements of the SQL array designated by this object 150 * @exception SQLException if an error occurs while attempting to 151 * access the array 152 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 153 * this method 154 * @since 1.2 155 */ 156 Object getArray(java.util.Map<String,Class<?>> map) throws SQLException; 157 158 /** 159 * Retrieves a slice of the SQL <code>ARRAY</code> 160 * value designated by this <code>Array</code> object, beginning with the 161 * specified <code>index</code> and containing up to <code>count</code> 162 * successive elements of the SQL array. This method uses the type map 163 * associated with the connection for customizations of the type mappings. 164 * <p> 165 * <strong>Note:</strong> When <code>getArray</code> is used to materialize 166 * a base type that maps to a primitive data type, then it is 167 * implementation-defined whether the array returned is an array of 168 * that primitive data type or an array of <code>Object</code>. 169 * 170 * @param index the array index of the first element to retrieve; 171 * the first element is at index 1 172 * @param count the number of successive SQL array elements to retrieve 173 * @return an array containing up to <code>count</code> consecutive elements 174 * of the SQL array, beginning with element <code>index</code> 175 * @exception SQLException if an error occurs while attempting to 176 * access the array 177 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 178 * this method 179 * @since 1.2 180 */ 181 Object getArray(long index, int count) throws SQLException; 182 183 /** 184 * Retreives a slice of the SQL <code>ARRAY</code> value 185 * designated by this <code>Array</code> object, beginning with the specified 186 * <code>index</code> and containing up to <code>count</code> 187 * successive elements of the SQL array. 188 * <P> 189 * This method uses 190 * the specified <code>map</code> for type map customizations 191 * unless the base type of the array does not match a user-defined 192 * type in <code>map</code>, in which case it 193 * uses the standard mapping. This version of the method 194 * <code>getArray</code> uses either the given type map or the standard mapping; 195 * it never uses the type map associated with the connection. 196 * <p> 197 * <strong>Note:</strong> When <code>getArray</code> is used to materialize 198 * a base type that maps to a primitive data type, then it is 199 * implementation-defined whether the array returned is an array of 200 * that primitive data type or an array of <code>Object</code>. 201 * 202 * @param index the array index of the first element to retrieve; 203 * the first element is at index 1 204 * @param count the number of successive SQL array elements to 205 * retrieve 206 * @param map a <code>java.util.Map</code> object 207 * that contains SQL type names and the classes in 208 * the Java programming language to which they are mapped 209 * @return an array containing up to <code>count</code> 210 * consecutive elements of the SQL <code>ARRAY</code> value designated by this 211 * <code>Array</code> object, beginning with element 212 * <code>index</code> 213 * @exception SQLException if an error occurs while attempting to 214 * access the array 215 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 216 * this method 217 * @since 1.2 218 */ 219 Object getArray(long index, int count, java.util.Map<String,Class<?>> map) 220 throws SQLException; 221 222 /** 223 * Retrieves a result set that contains the elements of the SQL 224 * <code>ARRAY</code> value 225 * designated by this <code>Array</code> object. If appropriate, 226 * the elements of the array are mapped using the connection's type 227 * map; otherwise, the standard mapping is used. 228 * <p> 229 * The result set contains one row for each array element, with 230 * two columns in each row. The second column stores the element 231 * value; the first column stores the index into the array for 232 * that element (with the first array element being at index 1). 233 * The rows are in ascending order corresponding to 234 * the order of the indices. 235 * 236 * @return a {@link ResultSet} object containing one row for each 237 * of the elements in the array designated by this <code>Array</code> 238 * object, with the rows in ascending order based on the indices. 239 * @exception SQLException if an error occurs while attempting to 240 * access the array 241 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 242 * this method 243 * @since 1.2 244 */ 245 ResultSet getResultSet () throws SQLException; 246 247 /** 248 * Retrieves a result set that contains the elements of the SQL 249 * <code>ARRAY</code> value designated by this <code>Array</code> object. 250 * This method uses 251 * the specified <code>map</code> for type map customizations 252 * unless the base type of the array does not match a user-defined 253 * type in <code>map</code>, in which case it 254 * uses the standard mapping. This version of the method 255 * <code>getResultSet</code> uses either the given type map or the standard mapping; 256 * it never uses the type map associated with the connection. 257 * <p> 258 * The result set contains one row for each array element, with 259 * two columns in each row. The second column stores the element 260 * value; the first column stores the index into the array for 261 * that element (with the first array element being at index 1). 262 * The rows are in ascending order corresponding to 263 * the order of the indices. 264 * 265 * @param map contains the mapping of SQL user-defined types to 266 * classes in the Java programming language 267 * @return a <code>ResultSet</code> object containing one row for each 268 * of the elements in the array designated by this <code>Array</code> 269 * object, with the rows in ascending order based on the indices. 270 * @exception SQLException if an error occurs while attempting to 271 * access the array 272 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 273 * this method 274 * @since 1.2 275 */ 276 ResultSet getResultSet (java.util.Map<String,Class<?>> map) throws SQLException; 277 278 /** 279 * Retrieves a result set holding the elements of the subarray that 280 * starts at index <code>index</code> and contains up to 281 * <code>count</code> successive elements. This method uses 282 * the connection's type map to map the elements of the array if 283 * the map contains an entry for the base type. Otherwise, the 284 * standard mapping is used. 285 * <P> 286 * The result set has one row for each element of the SQL array 287 * designated by this object, with the first row containing the 288 * element at index <code>index</code>. The result set has 289 * up to <code>count</code> rows in ascending order based on the 290 * indices. Each row has two columns: The second column stores 291 * the element value; the first column stores the index into the 292 * array for that element. 293 * 294 * @param index the array index of the first element to retrieve; 295 * the first element is at index 1 296 * @param count the number of successive SQL array elements to retrieve 297 * @return a <code>ResultSet</code> object containing up to 298 * <code>count</code> consecutive elements of the SQL array 299 * designated by this <code>Array</code> object, starting at 300 * index <code>index</code>. 301 * @exception SQLException if an error occurs while attempting to 302 * access the array 303 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 304 * this method 305 * @since 1.2 306 */ 307 ResultSet getResultSet(long index, int count) throws SQLException; 308 309 /** 310 * Retrieves a result set holding the elements of the subarray that 311 * starts at index <code>index</code> and contains up to 312 * <code>count</code> successive elements. 313 * This method uses 314 * the specified <code>map</code> for type map customizations 315 * unless the base type of the array does not match a user-defined 316 * type in <code>map</code>, in which case it 317 * uses the standard mapping. This version of the method 318 * <code>getResultSet</code> uses either the given type map or the standard mapping; 319 * it never uses the type map associated with the connection. 320 * <P> 321 * The result set has one row for each element of the SQL array 322 * designated by this object, with the first row containing the 323 * element at index <code>index</code>. The result set has 324 * up to <code>count</code> rows in ascending order based on the 325 * indices. Each row has two columns: The second column stores 326 * the element value; the first column stroes the index into the 327 * array for that element. 328 * 329 * @param index the array index of the first element to retrieve; 330 * the first element is at index 1 331 * @param count the number of successive SQL array elements to retrieve 332 * @param map the <code>Map</code> object that contains the mapping 333 * of SQL type names to classes in the Java(tm) programming language 334 * @return a <code>ResultSet</code> object containing up to 335 * <code>count</code> consecutive elements of the SQL array 336 * designated by this <code>Array</code> object, starting at 337 * index <code>index</code>. 338 * @exception SQLException if an error occurs while attempting to 339 * access the array 340 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 341 * this method 342 * @since 1.2 343 */ 344 ResultSet getResultSet (long index, int count, 345 java.util.Map<String,Class<?>> map) 346 throws SQLException; 347 /** 348 * This method frees the <code>Array</code> object and releases the resources that 349 * it holds. The object is invalid once the <code>free</code> 350 * method is called. 351 *<p> 352 * After <code>free</code> has been called, any attempt to invoke a 353 * method other than <code>free</code> will result in a <code>SQLException</code> 354 * being thrown. If <code>free</code> is called multiple times, the subsequent 355 * calls to <code>free</code> are treated as a no-op. 356 *<p> 357 * 358 * @throws SQLException if an error occurs releasing 359 * the Array's resources 360 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 361 * this method 362 * @since 1.6 363 */ 364 void free() throws SQLException; 365 366 } 367
