2362N/A * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The mapping in the Java programming language for the SQL type 0N/A * <code>ARRAY</code>. 0N/A * By default, an <code>Array</code> value is a transaction-duration 0N/A * reference to an SQL <code>ARRAY</code> value. By default, an <code>Array</code> 0N/A * object is implemented using an SQL LOCATOR(array) internally, which 0N/A * means that an <code>Array</code> object contains a logical pointer 0N/A * to the data in the SQL <code>ARRAY</code> value rather 0N/A * than containing the <code>ARRAY</code> value's data. 0N/A * The <code>Array</code> interface provides methods for bringing an SQL 0N/A * <code>ARRAY</code> value's data to the client as either an array or a 0N/A * <code>ResultSet</code> object. 0N/A * If the elements of the SQL <code>ARRAY</code> 0N/A * are a UDT, they may be custom mapped. To create a custom mapping, 0N/A * a programmer must do two things: 0N/A * <li>create a class that implements the {@link SQLData} 0N/A * interface for the UDT to be custom mapped. 0N/A * <li>make an entry in a type map that contains 0N/A * <li>the fully-qualified SQL type name of the UDT 0N/A * <li>the <code>Class</code> object for the class implementing 0N/A * <code>SQLData</code> 0N/A * When a type map with an entry for 0N/A * the base type is supplied to the methods <code>getArray</code> 0N/A * and <code>getResultSet</code>, the mapping 0N/A * it contains will be used to map the elements of the <code>ARRAY</code> value. 0N/A * If no type map is supplied, which would typically be the case, 0N/A * the connection's type map is used by default. 0N/A * If the connection's type map or a type map supplied to a method has no entry 0N/A * for the base type, the elements are mapped according to the standard mapping. 0N/A * All methods on the <code>Array</code> interface must be fully implemented if the 0N/A * JDBC driver supports the data type. 0N/A * Retrieves the SQL type name of the elements in 0N/A * the array designated by this <code>Array</code> object. 0N/A * If the elements are a built-in type, it returns 0N/A * the database-specific type name of the elements. 0N/A * If the elements are a user-defined type (UDT), 0N/A * this method returns the fully-qualified SQL type name. 0N/A * @return a <code>String</code> that is the database-specific 0N/A * name for a built-in base type; or the fully-qualified SQL type 0N/A * name for a base type that is a UDT 0N/A * @exception SQLException if an error occurs while attempting 0N/A * to access the type name 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves the JDBC type of the elements in the array designated 0N/A * by this <code>Array</code> object. 0N/A * @return a constant from the class {@link java.sql.Types} that is 0N/A * the type code for the elements in the array designated by this 0N/A * <code>Array</code> object 0N/A * @exception SQLException if an error occurs while attempting 0N/A * to access the base type 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves the contents of the SQL <code>ARRAY</code> value designated 0N/A * <code>Array</code> object in the form of an array in the Java 0N/A * programming language. This version of the method <code>getArray</code> 0N/A * uses the type map associated with the connection for customizations of 0N/A * the type mappings. 0N/A * <strong>Note:</strong> When <code>getArray</code> is used to materialize 0N/A * a base type that maps to a primitive data type, then it is 0N/A * implementation-defined whether the array returned is an array of 0N/A * that primitive data type or an array of <code>Object</code>. 0N/A * @return an array in the Java programming language that contains 0N/A * the ordered elements of the SQL <code>ARRAY</code> value 0N/A * designated by this <code>Array</code> object 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves the contents of the SQL <code>ARRAY</code> value designated by this 0N/A * <code>Array</code> object. 0N/A * the specified <code>map</code> for type map customizations 0N/A * unless the base type of the array does not match a user-defined 0N/A * type in <code>map</code>, in which case it 0N/A * uses the standard mapping. This version of the method 0N/A * <code>getArray</code> uses either the given type map or the standard mapping; 0N/A * it never uses the type map associated with the connection. 0N/A * <strong>Note:</strong> When <code>getArray</code> is used to materialize 0N/A * a base type that maps to a primitive data type, then it is 0N/A * implementation-defined whether the array returned is an array of 0N/A * that primitive data type or an array of <code>Object</code>. 0N/A * @param map a <code>java.util.Map</code> object that contains mappings 0N/A * of SQL type names to classes in the Java programming language 0N/A * @return an array in the Java programming language that contains the ordered 0N/A * elements of the SQL array designated by this object 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves a slice of the SQL <code>ARRAY</code> 0N/A * value designated by this <code>Array</code> object, beginning with the 0N/A * specified <code>index</code> and containing up to <code>count</code> 0N/A * successive elements of the SQL array. This method uses the type map 0N/A * associated with the connection for customizations of the type mappings. 0N/A * <strong>Note:</strong> When <code>getArray</code> is used to materialize 0N/A * a base type that maps to a primitive data type, then it is 0N/A * implementation-defined whether the array returned is an array of 0N/A * that primitive data type or an array of <code>Object</code>. 0N/A * @param index the array index of the first element to retrieve; 0N/A * the first element is at index 1 0N/A * @param count the number of successive SQL array elements to retrieve 0N/A * @return an array containing up to <code>count</code> consecutive elements 0N/A * of the SQL array, beginning with element <code>index</code> 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retreives a slice of the SQL <code>ARRAY</code> value 0N/A * designated by this <code>Array</code> object, beginning with the specified 0N/A * <code>index</code> and containing up to <code>count</code> 0N/A * successive elements of the SQL array. 0N/A * the specified <code>map</code> for type map customizations 0N/A * unless the base type of the array does not match a user-defined 0N/A * type in <code>map</code>, in which case it 0N/A * uses the standard mapping. This version of the method 0N/A * <code>getArray</code> uses either the given type map or the standard mapping; 0N/A * it never uses the type map associated with the connection. 0N/A * <strong>Note:</strong> When <code>getArray</code> is used to materialize 0N/A * a base type that maps to a primitive data type, then it is 0N/A * implementation-defined whether the array returned is an array of 0N/A * that primitive data type or an array of <code>Object</code>. 0N/A * @param index the array index of the first element to retrieve; 0N/A * the first element is at index 1 0N/A * @param count the number of successive SQL array elements to 0N/A * @param map a <code>java.util.Map</code> object 0N/A * that contains SQL type names and the classes in 0N/A * the Java programming language to which they are mapped 0N/A * @return an array containing up to <code>count</code> 0N/A * consecutive elements of the SQL <code>ARRAY</code> value designated by this 0N/A * <code>Array</code> object, beginning with element 0N/A * <code>index</code> 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves a result set that contains the elements of the SQL 0N/A * <code>ARRAY</code> value 0N/A * designated by this <code>Array</code> object. If appropriate, 0N/A * the elements of the array are mapped using the connection's type 0N/A * map; otherwise, the standard mapping is used. 0N/A * The result set contains one row for each array element, with 0N/A * two columns in each row. The second column stores the element 0N/A * value; the first column stores the index into the array for 0N/A * that element (with the first array element being at index 1). 0N/A * The rows are in ascending order corresponding to 0N/A * the order of the indices. 0N/A * @return a {@link ResultSet} object containing one row for each 0N/A * of the elements in the array designated by this <code>Array</code> 0N/A * object, with the rows in ascending order based on the indices. 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves a result set that contains the elements of the SQL 0N/A * <code>ARRAY</code> value designated by this <code>Array</code> object. 0N/A * the specified <code>map</code> for type map customizations 0N/A * unless the base type of the array does not match a user-defined 0N/A * type in <code>map</code>, in which case it 0N/A * uses the standard mapping. This version of the method 0N/A * <code>getResultSet</code> uses either the given type map or the standard mapping; 0N/A * it never uses the type map associated with the connection. 0N/A * The result set contains one row for each array element, with 0N/A * two columns in each row. The second column stores the element 0N/A * value; the first column stores the index into the array for 0N/A * that element (with the first array element being at index 1). 0N/A * The rows are in ascending order corresponding to 0N/A * the order of the indices. 0N/A * @param map contains the mapping of SQL user-defined types to 0N/A * classes in the Java programming language 0N/A * @return a <code>ResultSet</code> object containing one row for each 0N/A * of the elements in the array designated by this <code>Array</code> 0N/A * object, with the rows in ascending order based on the indices. 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves a result set holding the elements of the subarray that 0N/A * starts at index <code>index</code> and contains up to 0N/A * <code>count</code> successive elements. This method uses 0N/A * the connection's type map to map the elements of the array if 0N/A * the map contains an entry for the base type. Otherwise, the 0N/A * standard mapping is used. 0N/A * The result set has one row for each element of the SQL array 0N/A * designated by this object, with the first row containing the 0N/A * element at index <code>index</code>. The result set has 0N/A * up to <code>count</code> rows in ascending order based on the 0N/A * indices. Each row has two columns: The second column stores 0N/A * the element value; the first column stores the index into the 0N/A * array for that element. 0N/A * @param index the array index of the first element to retrieve; 0N/A * the first element is at index 1 0N/A * @param count the number of successive SQL array elements to retrieve 0N/A * @return a <code>ResultSet</code> object containing up to 0N/A * <code>count</code> consecutive elements of the SQL array 0N/A * designated by this <code>Array</code> object, starting at 0N/A * index <code>index</code>. 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * Retrieves a result set holding the elements of the subarray that 0N/A * starts at index <code>index</code> and contains up to 0N/A * <code>count</code> successive elements. 0N/A * the specified <code>map</code> for type map customizations 0N/A * unless the base type of the array does not match a user-defined 0N/A * type in <code>map</code>, in which case it 0N/A * uses the standard mapping. This version of the method 0N/A * <code>getResultSet</code> uses either the given type map or the standard mapping; 0N/A * it never uses the type map associated with the connection. 0N/A * The result set has one row for each element of the SQL array 0N/A * designated by this object, with the first row containing the 0N/A * element at index <code>index</code>. The result set has 0N/A * up to <code>count</code> rows in ascending order based on the 0N/A * indices. Each row has two columns: The second column stores 0N/A * the element value; the first column stroes the index into the 0N/A * array for that element. 0N/A * @param index the array index of the first element to retrieve; 0N/A * the first element is at index 1 0N/A * @param count the number of successive SQL array elements to retrieve 0N/A * @param map the <code>Map</code> object that contains the mapping 0N/A * of SQL type names to classes in the Java(tm) programming language 0N/A * @return a <code>ResultSet</code> object containing up to 0N/A * <code>count</code> consecutive elements of the SQL array 0N/A * designated by this <code>Array</code> object, starting at 0N/A * index <code>index</code>. 0N/A * @exception SQLException if an error occurs while attempting to 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 0N/A * This method frees the <code>Array</code> object and releases the resources that 0N/A * it holds. The object is invalid once the <code>free</code> 0N/A * After <code>free</code> has been called, any attempt to invoke a 0N/A * method other than <code>free</code> will result in a <code>SQLException</code> 0N/A * being thrown. If <code>free</code> is called multiple times, the subsequent 0N/A * calls to <code>free</code> are treated as a no-op. 0N/A * @throws SQLException if an error occurs releasing 0N/A * the Array's resources 0N/A * @exception SQLFeatureNotSupportedException if the JDBC driver does not support