1. /*

  2.  * @(#)Array.java	1.11 01/11/29

  3.  *

  4.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.sql;

  9.  

  10. /**

  11.  * JDBC 2.0

  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> is a transaction duration 

  17.  * reference to an SQL array.  By default, an <code>Array</code>

  18.  * is implemented using an SQL LOCATOR(array) internally.

  19.  */

  20. 

  21. public interface Array {

  22. 

  23.   /**

  24.    * Returns the SQL type name of the elements in 

  25.    * the array designated by this <code>Array</code> object.

  26.    * If the elements are a built-in type, it returns

  27.    * the database-specific type name of the elements. 

  28.    * If the elements are a user-defined type (UDT),

  29.    * this method returns the fully-qualified SQL type name.

  30.    * @return a <code>String</code> that is the database-specific

  31.    * name for a built-in base type or the fully-qualified SQL type

  32.    * name for a base type that is a UDT

  33.    * @exception SQLException if an error occurs while attempting

  34.    * to access the type name

  35.    */

  36.   String getBaseTypeName() throws SQLException;

  37. 

  38.   /**

  39.    * Returns the JDBC type of the elements in the array designated

  40.    * by this <code>Array</code> object.

  41.    * @return a constant from the class {@link java.sql.Types} that is

  42.    * the type code for the elements in the array designated by this

  43.    * <code>Array</code> object.

  44.    * @exception SQLException if an error occurs while attempting

  45.    * to access the base type 

  46.    */

  47.   int getBaseType() throws SQLException;

  48. 

  49.   /**

  50.    * Retrieves the contents of the SQL array designated by this

  51.    * <code>Array</code> object in the form of an array in the Java

  52.    * programming language. This version of the method <code>getArray</code>

  53.    * uses the type map associated with the connection for customizations of 

  54.    * the type mappings.

  55.    * @return an array in the Java programming language that contains 

  56.    * the ordered elements of the SQL ARRAY object designated by this object

  57.    * @exception SQLException if an error occurs while attempting to

  58.    * access the array

  59.    */

  60.   Object getArray() throws SQLException;

  61. 

  62.   /**

  63.    * Retrieves the contents of the SQL array designated by this 

  64.    * <code>Array</code>

  65.    * object, using the specified <code>map</code> for type map 

  66.    * customizations.  If the base type of the array does not

  67.    * match a user-defined type in <code>map</code>, the standard

  68.    * mapping is used instead.

  69.    * @param map a <code>java.util.Map</code> object that contains mappings

  70.    *            of SQL type names to classes in the Java programming language

  71.    * @return an array in the Java programming language that contains the ordered 

  72.    *         elements of the SQL array designated by this object

  73.    * @exception SQLException if an error occurs while attempting to 

  74.    *                         access the array

  75.    */

  76.   Object getArray(java.util.Map map) throws SQLException;

  77. 

  78.   /**

  79.    * Returns an array containing a  slice of the SQL array, beginning with the

  80.    * specified <code>index</code> and containing up to <code>count</code> 

  81.    * successive elements of the SQL array.  This method uses the type-map

  82.    * associated with the connection for customizations of the type-mappings.

  83.    * @param index the array index of the first element to retrieve;

  84.    *              the first element is at index 1

  85.    * @param count the number of successive SQL array elements to retrieve

  86.    * @return an array containing up to <code>count</code> consecutive elements 

  87.    * of the SQL array, beginning with element <code>index</code>

  88.    * @exception SQLException if an error occurs while attempting to

  89.    * access the array

  90.    */

  91.   Object getArray(long index, int count) throws SQLException;

  92. 

  93.   /**

  94.    * Returns an array containing a slice of the SQL array object 

  95.    * designated by this object, beginning with the specified

  96.    * <code>index</code> and containing up to <code>count</code>

  97.    * successive elements of the SQL array.  This method uses 

  98.    * the specified <code>map</code> for type-map customizations

  99.    * unless the base type of the array does not match a user-

  100.    * defined type in <code>map</code>, in which case it 

  101.    * uses the standard mapping.

  102.    * @param index the array index of the first element to retrieve;

  103.    *              the first element is at index 1

  104.    * @param count the number of successive SQL array elements to 

  105.    * retrieve

  106.    * @param map a <code>java.util.Map</code> object

  107.    * that contains SQL type names and the classes in

  108.    * the Java programming language to which they are mapped

  109.    * @return an array containing up to <code>count</code>

  110.    * consecutive elements of the SQL array designated by this

  111.    * <code>Array</code> object, beginning with element 

  112.    * <code>index</code>.

  113.    * @exception SQLException if an error occurs while attempting to

  114.    * access the array

  115.    */

  116.   Object getArray(long index, int count, java.util.Map map) 

  117.     throws SQLException;

  118. 

  119.   /**

  120.    * Returns a result set that contains the elements of the array

  121.    * designated by this <code>Array</code> object.  If appropriate,

  122.    * the elements of the array are mapped using the connection's type 

  123.    * map; otherwise, the standard mapping is used.

  124.    * <p>

  125.    * The result set contains one row for each array element, with

  126.    * two columns in each row.  The second column stores the element

  127.    * value; the first column stores the index into the array for 

  128.    * that element (with the first array element being at index 1). 

  129.    * The rows are in ascending order corresponding to

  130.    * the order of the indices.

  131.    * @return a {@link ResultSet} object containing one row for each

  132.    * of the elements in the array designated by this <code>Array</code>

  133.    * object, with the rows in ascending order based on the indices.

  134.    * @exception SQLException if an error occurs while attempting to

  135.    * access the array

  136.    */

  137.   ResultSet getResultSet () throws SQLException;

  138. 

  139.   /**

  140.    * Returns a result set that contains the elements of the array

  141.    * designated by this <code>Array</code> object and uses the given

  142.    * <code>map</code> to map the array elements.  If the base

  143.    * type of the array does not match a user-defined type in

  144.    * <code>map</code>, the standard mapping is used instead.

  145.    * <p>

  146.    * The result set contains one row for each array element, with

  147.    * two columns in each row.  The second column stores the element

  148.    * value; the first column stores the index into the array for 

  149.    * that element (with the first array element being at index 1). 

  150.    * The rows are in ascending order corresponding to

  151.    * the order of the indices.

  152.    * @param map contains mapping of SQL user-defined types to 

  153.    * classes in the Java(tm) programming language

  154.    * @return a <code>ResultSet</code> object containing one row for each

  155.    * of the elements in the array designated by this <code>Array</code>

  156.    * object, with the rows in ascending order based on the indices.

  157.    * @exception SQLException if an error occurs while attempting to

  158.    * access the array

  159.    */

  160.   ResultSet getResultSet (java.util.Map map) throws SQLException;

  161. 

  162.   /**

  163.    * Returns a result set holding the elements of the subarray that

  164.    * starts at index <code>index</code> and contains up to 

  165.    * <code>count</code> successive elements.  This method uses

  166.    * the connection's type map to map the elements of the array if

  167.    * the map contains an entry for the base type. Otherwise, the

  168.    * standard mapping is used.

  169.    * <P>

  170.    * The result set has one row for each element of the SQL array

  171.    * designated by this object, with the first row containing the 

  172.    * element at index <code>index</code>.  The result set has

  173.    * up to <code>count</code> rows in ascending order based on the

  174.    * indices.  Each row has two columns:  The second column stores

  175.    * the element value; the first column stroes the index into the

  176.    * array for that element.

  177.    * @param index the array index of the first element to retrieve;

  178.    *              the first element is at index 1

  179.    * @param count the number of successive SQL array elements to retrieve

  180.    * @return a <code>ResultSet</code> object containing up to

  181.    * <code>count</code> consecutive elements of the SQL array

  182.    * designated by this <code>Array</code> object, starting at

  183.    * index <code>index</code>.

  184.    * @exception SQLException if an error occurs while attempting to

  185.    * access the array

  186.    */

  187.   ResultSet getResultSet(long index, int count) throws SQLException;

  188. 

  189.   /**

  190.    * Returns a result set holding the elements of the subarray that

  191.    * starts at index <code>index</code> and contains up to

  192.    * <code>count</code> successive elements.  This method uses

  193.    * the <code>Map</code> object <code>map</code> to map the elements

  194.    * of the array unless the base type of the array does not match

  195.    * a user-defined type in <code>map</code>, in which case it uses

  196.    * the standard mapping.

  197.    * <P>

  198.    * The result set has one row for each element of the SQL array

  199.    * designated by this object, with the first row containing the

  200.    * element at index <code>index</code>.  The result set has   

  201.    * up to <code>count</code> rows in ascending order based on the

  202.    * indices.  Each row has two columns:  The second column stores  

  203.    * the element value; the first column stroes the index into the

  204.    * array for that element.

  205.    * @param index the array index of the first element to retrieve;

  206.    *              the first element is at index 1

  207.    * @param count the number of successive SQL array elements to retrieve

  208.    * @param map the <code>Map</code> object that contains the mapping

  209.    * of SQL type names to classes in the Java(tm) programming language

  210.    * @return a <code>ResultSet</code> object containing up to               

  211.    * <code>count</code> consecutive elements of the SQL array

  212.    * designated by this <code>Array</code> object, starting at

  213.    * index <code>index</code>.

  214.    * @exception SQLException if an error occurs while attempting to

  215.    * access the array

  216.    *

  217.    */

  218.   ResultSet getResultSet (long index, int count, java.util.Map map)

  219.     throws SQLException;

  220. 

  221. }

  222. 

  223.