array.java

一个JDBC数据库连接的组件

/*
 * @(#)Array.java	1.5 98/04/24
 * 
 * Copyright 1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package java.sql;
 
/**
 * JDBC 2.0
 *
 * <p>SQL arrays are mapped to the Array interface.  By default, an 
 * Array is a transaction duration reference to an SQL array.  By 
 * default, an Array is implemented using an SQL LOCATOR(array) 
 * internally.
 */

public interface Array {

  /**
   * Return the fully qualified SQL type name of the elements of 
   * this array.
   *
   * @returns String containing SQL type name of array elements
   */
  String getBaseTypeName() throws SQLException;

  /**
   * Determine the code, from java.sql.Types, of the type of
   * the elements of the array.
   *
   * @return the type code of the elements of the array.
   */
  int getBaseType() throws SQLException;

  /**
   * Retrieve the contents of the SQL array designated by the object.  
   * Use the type-map associated with the connection for customizations of 
   * the type-mappings.
   *
   * Conceptually, this method calls getObject() on each element of the
   * array and returns a Java array containing the result. Except when
   * the array element type maps to a Java primitive type, such as int,
   * boolean, etc. In this case, an array of primitive type values, 
   * i.e. an array of int, is returned, not an array of Integer.  This 
   * exception for primitive types should improve performance as well as 
   * usability.
   *
   * @return a Java array containing the ordered elements of the SQL 
   * array designated by this object.
   */
  Object getArray() throws SQLException;

  /**
   * Retrieve the contents of the SQL array designated by this 
   * object. Use the given @map for type-map customizations.
   *
   * Conceptually, this method calls getObject() on each element of the
   * array and returns a Java array containing the result. Except when
   * the array element type maps to a Java primitive type, such as int,
   * boolean, etc. In this case, an array of primitive type values, 
   * i.e. an array of int, is returned, not an array of Integer.  This 
   * exception for primitive types should improve performance as well as 
   * usability.
   *   
   * @param map contains mapping of SQL type names to Java classes
   * @return a Java array containing the ordered elements of the SQL  
   * array designated by this object.
   */
  Object getArray(java.util.Map map) throws SQLException;

  /**
   * Like getArray() above, but returns an array containing a 
   * slice of the SQL array, beginning with the given @index and 
   * containing up to @count successive elements of the SQL array. 
   * Use the type-map associated with the connection for customizations 
   * of the type-mappings.
   *
   * @index the array-index of the first element to retrieve
   * @count the number of successive SQL array elements to retrieve
   * @return an array containing up to @count elements of the
   * SQL array, beginning with element @index.
   */
  Object getArray(long index, int count) throws SQLException;

  /**
   * Like getArray() above, but returns an array containing a 
   * slice of the SQL array, beginning with the given @index and 
   * containing up to @count successive elements of the SQL array. 
   * Use the given @map for type-map customizations.
   *
   * @index the array-index of the first element to retrieve
   * @count the number of successive SQL array elements to retrieve
   * @param map contains mapping of SQL user-defined types to classes
   * @return an array containing up to @count elements of the
   * SQL array, beginning with element @index.
   */
  Object getArray(long index, int count, java.util.Map map) 
    throws SQLException;

  /**
   * Materialize the item designated by the Array as a ResultSet
   * that contains a row for each element of the Array.  The 
   * first column of each row contains the array index of the
   * corresponding element in the Array.  The second column contains
   * the array element value.  The rows are ordered in ascending 
   * order of the array-element indexes.
   *  
   * @return a result set containing the elements of the array
   */
  ResultSet getResultSet () throws SQLException;

  /**
   * Materialize the item designated by the Array as a ResultSet
   * that contains a row for each element of the Array.  The 
   * first column of each row contains the array index of the
   * corresponding element in the Array.  The second column contains
   * the array element value.  The rows are ordered in ascending 
   * order of the array-element indexes.  Use the given @map for 
   * type-map customizations.
   *
   * @param map contains mapping of SQL user-defined types to 
   * classes
   *  
   * @return a result set containing the elements of the array
   */
  ResultSet getResultSet (java.util.Map map) throws SQLException;

  /**
   * Materialize the designated sub-array as a ResultSet
   * that contains a row for each element of the sub-array.  The 
   * first column of each row contains the array index of the
   * corresponding element in the Array.  The second column contains
   * the array element value.  The rows are ordered in ascending 
   * order of the array-element indexes.
   *  
   * @param index the index of the first element to retrieve
   * @param count the number of successive SQL array elements to retrieve
   * @return a result set containing the elements of the array
   */
  ResultSet getResultSet(long index, int count) throws SQLException;

  /**
   * Materialize the designated sub-array as a ResultSet
   * that contains a row for each element of the sub-array.  The 
   * first column of each row contains the array index of the
   * corresponding element in the Array.  The second column contains
   * the array element value.  The rows are ordered in ascending 
   * order of the array-element indexes. Use the given @map for 
   * type-map customizations.
   *
   * @param index the index of the first element to retrieve
   * @param count the number of successive SQL array elements to retrieve
   * @param map contains mapping of SQL user-defined types to 
   * classes
   *  
   * @return a result set containing the elements of the array
   */
  ResultSet getResultSet (long index, int count, java.util.Map map)
    throws SQLException;

}