1 /*

     2  * Copyright (c) 1998, 2013, 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 stores 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      *

   357      * @throws SQLException if an error occurs releasing

   358      * the Array's resources

   359      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   360      * this method

   361      * @since 1.6

   362      */

   363     void free() throws SQLException;

   364 

   365 }