home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / sql / Array.java next >
Encoding:
Java Source  |  1999-05-28  |  10.2 KB  |  231 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Array.java    1.9 98/09/13
  3.  * 
  4.  * Copyright 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * JDBC 2.0
  19.  *
  20.  * <p>
  21.  * The mapping in the Java programming language for the SQL type
  22.  * <code>ARRAY</code>.
  23.  * By default, an <code>Array</code> is a transaction duration 
  24.  * reference to an SQL array.  By default, an <code>Array</code>
  25.  * is implemented using an SQL LOCATOR(array) internally.
  26.  */
  27.  
  28. public interface Array {
  29.  
  30.   /**
  31.    * Returns the SQL type name of the elements in 
  32.    * the array designated by this <code>Array</code> object.
  33.    * If the elements are a built-in type, it returns
  34.    * the database-specific type name of the elements. 
  35.    * If the elements are a user-defined type (UDT),
  36.    * this method returns the fully-qualified SQL type name.
  37.    * @return a <code>String</code> that is the database-specific
  38.    * name for a built-in base type or the fully-qualified SQL type
  39.    * name for a base type that is a UDT
  40.    * @exception SQLException if an error occurs while attempting
  41.    * to access the type name
  42.    */
  43.   String getBaseTypeName() throws SQLException;
  44.  
  45.   /**
  46.    * Returns the JDBC type of the elements in the array designated
  47.    * by this <code>Array</code> object.
  48.    * @return a constant from the class {@link java.sql.Types} that is
  49.    * the type code for the elements in the array designated by this
  50.    * <code>Array</code> object.
  51.    * @exception SQLException if an error occurs while attempting
  52.    * to access the base type 
  53.    */
  54.   int getBaseType() throws SQLException;
  55.  
  56.   /**
  57.    * Retrieves the contents of the SQL array designated by this
  58.    * <code>Array</code> object in the form of an array in the Java
  59.    * programming language. This version of the method <code>getArray</code>
  60.    * uses the type map associated with the connection for customizations of 
  61.    * the type mappings.
  62.    * @return an array in the Java programming language that contains 
  63.    * the ordered elements of the SQL ARRAY object designated by this object
  64.    * @exception SQLException if an error occurs while attempting to
  65.    * access the array
  66.    */
  67.   Object getArray() throws SQLException;
  68.  
  69.   /**
  70.    * Retrieves the contents of the SQL array designated by this 
  71.    * <code>Array</code>
  72.    * object, using the specified <code>map</code> for type map 
  73.    * customizations.  If the base type of the array does not
  74.    * match a user-defined type in <code>map</code>, the standard
  75.    * mapping is used instead.
  76.    * @param map a <code>java.util.Map</code> object that contains mappings
  77.    *            of SQL type names to classes in the Java programming language
  78.    * @return an array in the Java programming language that contains the ordered 
  79.    *         elements of the SQL array designated by this object
  80.    * @exception SQLException if an error occurs while attempting to 
  81.    *                         access the array
  82.    */
  83.   Object getArray(java.util.Map map) throws SQLException;
  84.  
  85.   /**
  86.    * Returns an array containing a  slice of the SQL array, beginning with the
  87.    * specified <code>index</code> and containing up to <code>count</code> 
  88.    * successive elements of the SQL array.  This method uses the type-map
  89.    * associated with the connection for customizations of the type-mappings.
  90.    * @param index the array index of the first element to retrieve;
  91.    *              the first element is at index 1
  92.    * @param count the number of successive SQL array elements to retrieve
  93.    * @return an array containing up to <code>count</code> consecutive elements 
  94.    * of the SQL array, beginning with element <code>index</code>
  95.    * @exception SQLException if an error occurs while attempting to
  96.    * access the array
  97.    */
  98.   Object getArray(long index, int count) throws SQLException;
  99.  
  100.   /**
  101.    * Returns an array containing a slice of the SQL array object 
  102.    * designated by this object, beginning with the specified
  103.    * <code>index</code> and containing up to <code>count</code>
  104.    * successive elements of the SQL array.  This method uses 
  105.    * the specified <code>map</code> for type-map customizations
  106.    * unless the base type of the array does not match a user-
  107.    * defined type in <code>map</code>, in which case it 
  108.    * uses the standard mapping.
  109.    * @param index the array index of the first element to retrieve;
  110.    *              the first element is at index 1
  111.    * @param count the number of successive SQL array elements to 
  112.    * retrieve
  113.    * @param map a <code>java.util.Map</code> object
  114.    * that contains SQL type names and the classes in
  115.    * the Java programming language to which they are mapped
  116.    * @return an array containing up to <code>count</code>
  117.    * consecutive elements of the SQL array designated by this
  118.    * <code>Array</code> object, beginning with element 
  119.    * <code>index</code>.
  120.    * @exception SQLException if an error occurs while attempting to
  121.    * access the array
  122.    */
  123.   Object getArray(long index, int count, java.util.Map map) 
  124.     throws SQLException;
  125.  
  126.   /**
  127.    * Returns a result set that contains the elements of the array
  128.    * designated by this <code>Array</code> object.  If appropriate,
  129.    * the elements of the array are mapped using the connection's type 
  130.    * map; otherwise, the standard mapping is used.
  131.    * <p>
  132.    * The result set contains one row for each array element, with
  133.    * two columns in each row.  The second column stores the element
  134.    * value; the first column stores the index into the array for 
  135.    * that element (with the first array element being at index 1). 
  136.    * The rows are in ascending order corresponding to
  137.    * the order of the indices.
  138.    * @return a {@link ResultSet} object containing one row for each
  139.    * of the elements in the array designated by this <code>Array</code>
  140.    * object, with the rows in ascending order based on the indices.
  141.    * @exception SQLException if an error occurs while attempting to
  142.    * access the array
  143.    */
  144.   ResultSet getResultSet () throws SQLException;
  145.  
  146.   /**
  147.    * Returns a result set that contains the elements of the array
  148.    * designated by this <code>Array</code> object and uses the given
  149.    * <code>map</code> to map the array elements.  If the base
  150.    * type of the array does not match a user-defined type in
  151.    * <code>map</code>, the standard mapping is used instead.
  152.    * <p>
  153.    * The result set contains one row for each array element, with
  154.    * two columns in each row.  The second column stores the element
  155.    * value; the first column stores the index into the array for 
  156.    * that element (with the first array element being at index 1). 
  157.    * The rows are in ascending order corresponding to
  158.    * the order of the indices.
  159.    * @param map contains mapping of SQL user-defined types to 
  160.    * classes in the Java(tm) programming language
  161.    * @return a <code>ResultSet</code> object containing one row for each
  162.    * of the elements in the array designated by this <code>Array</code>
  163.    * object, with the rows in ascending order based on the indices.
  164.    * @exception SQLException if an error occurs while attempting to
  165.    * access the array
  166.    */
  167.   ResultSet getResultSet (java.util.Map map) throws SQLException;
  168.  
  169.   /**
  170.    * Returns a result set holding the elements of the subarray that
  171.    * starts at index <code>index</code> and contains up to 
  172.    * <code>count</code> successive elements.  This method uses
  173.    * the connection's type map to map the elements of the array if
  174.    * the map contains an entry for the base type. Otherwise, the
  175.    * standard mapping is used.
  176.    * <P>
  177.    * The result set has one row for each element of the SQL array
  178.    * designated by this object, with the first row containing the 
  179.    * element at index <code>index</code>.  The result set has
  180.    * up to <code>count</code> rows in ascending order based on the
  181.    * indices.  Each row has two columns:  The second column stores
  182.    * the element value; the first column stroes the index into the
  183.    * array for that element.
  184.    * @param index the array index of the first element to retrieve;
  185.    *              the first element is at index 1
  186.    * @param count the number of successive SQL array elements to retrieve
  187.    * @return a <code>ResultSet</code> object containing up to
  188.    * <code>count</code> consecutive elements of the SQL array
  189.    * designated by this <code>Array</code> object, starting at
  190.    * index <code>index</code>.
  191.    * @exception SQLException if an error occurs while attempting to
  192.    * access the array
  193.    */
  194.   ResultSet getResultSet(long index, int count) throws SQLException;
  195.  
  196.   /**
  197.    * Returns a result set holding the elements of the subarray that
  198.    * starts at index <code>index</code> and contains up to
  199.    * <code>count</code> successive elements.  This method uses
  200.    * the <code>Map</code> object <code>map</code> to map the elements
  201.    * of the array unless the base type of the array does not match
  202.    * a user-defined type in <code>map</code>, in which case it uses
  203.    * the standard mapping.
  204.    * <P>
  205.    * The result set has one row for each element of the SQL array
  206.    * designated by this object, with the first row containing the
  207.    * element at index <code>index</code>.  The result set has   
  208.    * up to <code>count</code> rows in ascending order based on the
  209.    * indices.  Each row has two columns:  The second column stores  
  210.    * the element value; the first column stroes the index into the
  211.    * array for that element.
  212.    * @param index the array index of the first element to retrieve;
  213.    *              the first element is at index 1
  214.    * @param count the number of successive SQL array elements to retrieve
  215.    * @param map the <code>Map</code> object that contains the mapping
  216.    * of SQL type names to classes in the Java(tm) programming language
  217.    * @return a <code>ResultSet</code> object containing up to               
  218.    * <code>count</code> consecutive elements of the SQL array
  219.    * designated by this <code>Array</code> object, starting at
  220.    * index <code>index</code>.
  221.    * @exception SQLException if an error occurs while attempting to
  222.    * access the array
  223.    *
  224.    */
  225.   ResultSet getResultSet (long index, int count, java.util.Map map)
  226.     throws SQLException;
  227.  
  228. }
  229.  
  230.  
  231.