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