src/java.sql/share/classes/java/sql/Array.java
author alanb
Tue, 15 May 2018 09:33:02 +0100
changeset 50109 ea54197f4fe4
parent 47216 71c04702a3d5
permissions -rw-r--r--
8203059: (so) Closing a socket channel registered with Selector and with SO_LINGER set to 0 does not reset connection Reviewed-by: chegar
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
25976
4de01a56e3ee 8054555: javadoc cleanup for java.sql and javax.sql
lancea
parents: 23590
diff changeset
     2
 * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    23
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
package java.sql;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
 * The mapping in the Java programming language for the SQL type
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
 * <code>ARRAY</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
 * By default, an <code>Array</code> value is a transaction-duration
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
 * reference to an SQL <code>ARRAY</code> value.  By default, an <code>Array</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
 * object is implemented using an SQL LOCATOR(array) internally, which
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
 * means that an <code>Array</code> object contains a logical pointer
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
 * to the data in the SQL <code>ARRAY</code> value rather
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
 * than containing the <code>ARRAY</code> value's data.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
 * The <code>Array</code> interface provides methods for bringing an SQL
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 * <code>ARRAY</code> value's data to the client as either an array or a
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
 * <code>ResultSet</code> object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
 * If the elements of the SQL <code>ARRAY</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
 * are a UDT, they may be custom mapped.  To create a custom mapping,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
 * a programmer must do two things:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
 * <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * <li>create a class that implements the {@link SQLData}
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
 * interface for the UDT to be custom mapped.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
 * <li>make an entry in a type map that contains
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
 *   <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
 *   <li>the fully-qualified SQL type name of the UDT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
 *   <li>the <code>Class</code> object for the class implementing
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
 *       <code>SQLData</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
 *   </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
 * </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * When a type map with an entry for
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * the base type is supplied to the methods <code>getArray</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * and <code>getResultSet</code>, the mapping
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
 * it contains will be used to map the elements of the <code>ARRAY</code> value.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
 * If no type map is supplied, which would typically be the case,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 * the connection's type map is used by default.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 * If the connection's type map or a type map supplied to a method has no entry
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 * for the base type, the elements are mapped according to the standard mapping.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 * All methods on the <code>Array</code> interface must be fully implemented if the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
 * JDBC driver supports the data type.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
 * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
public interface Array {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
   * Retrieves the SQL type name of the elements in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
   * the array designated by this <code>Array</code> object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
   * If the elements are a built-in type, it returns
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
   * the database-specific type name of the elements.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
   * If the elements are a user-defined type (UDT),
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
   * this method returns the fully-qualified SQL type name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
   * @return a <code>String</code> that is the database-specific
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
   * name for a built-in base type; or the fully-qualified SQL type
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
   * name for a base type that is a UDT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
   * @exception SQLException if an error occurs while attempting
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
   * to access the type name
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
  String getBaseTypeName() throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
   * Retrieves the JDBC type of the elements in the array designated
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
   * by this <code>Array</code> object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
   * @return a constant from the class {@link java.sql.Types} that is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
   * the type code for the elements in the array designated by this
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
   * <code>Array</code> object
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
   * @exception SQLException if an error occurs while attempting
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
   * to access the base type
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
  int getBaseType() throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
   * Retrieves the contents of the SQL <code>ARRAY</code> value designated
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
   * by this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
   * <code>Array</code> object in the form of an array in the Java
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
   * programming language. This version of the method <code>getArray</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
   * uses the type map associated with the connection for customizations of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
   * the type mappings.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
   * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
   * <strong>Note:</strong> When <code>getArray</code> is used to materialize
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
   * a base type that maps to a primitive data type, then it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
   * implementation-defined whether the array returned is an array of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
   * that primitive data type or an array of <code>Object</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
   * @return an array in the Java programming language that contains
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
   * the ordered elements of the SQL <code>ARRAY</code> value
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
   * designated by this <code>Array</code> object
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
   * access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
  Object getArray() throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
   * Retrieves the contents of the SQL <code>ARRAY</code> value designated by this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
   * <code>Array</code> object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
   * This method uses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
   * the specified <code>map</code> for type map customizations
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
   * unless the base type of the array does not match a user-defined
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
   * type in <code>map</code>, in which case it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
   * uses the standard mapping. This version of the method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
   * <code>getArray</code> uses either the given type map or the standard mapping;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
   * it never uses the type map associated with the connection.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
   * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
   * <strong>Note:</strong> When <code>getArray</code> is used to materialize
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
   * a base type that maps to a primitive data type, then it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
   * implementation-defined whether the array returned is an array of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
   * that primitive data type or an array of <code>Object</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
   * @param map a <code>java.util.Map</code> object that contains mappings
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
   *            of SQL type names to classes in the Java programming language
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
   * @return an array in the Java programming language that contains the ordered
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
   *         elements of the SQL array designated by this object
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
   *                         access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
  Object getArray(java.util.Map<String,Class<?>> map) throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
   * Retrieves a slice of the SQL <code>ARRAY</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
   * value designated by this <code>Array</code> object, beginning with the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
   * specified <code>index</code> and containing up to <code>count</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
   * successive elements of the SQL array.  This method uses the type map
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
   * associated with the connection for customizations of the type mappings.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
   * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
   * <strong>Note:</strong> When <code>getArray</code> is used to materialize
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
   * a base type that maps to a primitive data type, then it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
   * implementation-defined whether the array returned is an array of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
   * that primitive data type or an array of <code>Object</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
   * @param index the array index of the first element to retrieve;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
   *              the first element is at index 1
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
   * @param count the number of successive SQL array elements to retrieve
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
   * @return an array containing up to <code>count</code> consecutive elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
   * of the SQL array, beginning with element <code>index</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
   * access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
  Object getArray(long index, int count) throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
  /**
25976
4de01a56e3ee 8054555: javadoc cleanup for java.sql and javax.sql
lancea
parents: 23590
diff changeset
   184
   * Retrieves a slice of the SQL <code>ARRAY</code> value
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
   * designated by this <code>Array</code> object, beginning with the specified
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
   * <code>index</code> and containing up to <code>count</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
   * successive elements of the SQL array.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
   * <P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
   * This method uses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
   * the specified <code>map</code> for type map customizations
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
   * unless the base type of the array does not match a user-defined
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
   * type in <code>map</code>, in which case it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
   * uses the standard mapping. This version of the method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
   * <code>getArray</code> uses either the given type map or the standard mapping;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
   * it never uses the type map associated with the connection.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
   * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
   * <strong>Note:</strong> When <code>getArray</code> is used to materialize
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
   * a base type that maps to a primitive data type, then it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
   * implementation-defined whether the array returned is an array of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
   * that primitive data type or an array of <code>Object</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
   * @param index the array index of the first element to retrieve;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
   *              the first element is at index 1
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
   * @param count the number of successive SQL array elements to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
   * retrieve
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
   * @param map a <code>java.util.Map</code> object
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
   * that contains SQL type names and the classes in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
   * the Java programming language to which they are mapped
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
   * @return an array containing up to <code>count</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
   * consecutive elements of the SQL <code>ARRAY</code> value designated by this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
   * <code>Array</code> object, beginning with element
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
   * <code>index</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
   * access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
  Object getArray(long index, int count, java.util.Map<String,Class<?>> map)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
    throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
   * Retrieves a result set that contains the elements of the SQL
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
   * <code>ARRAY</code> value
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
   * designated by this <code>Array</code> object.  If appropriate,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
   * the elements of the array are mapped using the connection's type
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
   * map; otherwise, the standard mapping is used.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
   * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
   * The result set contains one row for each array element, with
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
   * two columns in each row.  The second column stores the element
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
   * value; the first column stores the index into the array for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
   * that element (with the first array element being at index 1).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
   * The rows are in ascending order corresponding to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
   * the order of the indices.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   236
   * @return a {@link ResultSet} object containing one row for each
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
   * of the elements in the array designated by this <code>Array</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   238
   * object, with the rows in ascending order based on the indices.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   239
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
   * access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   242
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   243
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
  ResultSet getResultSet () throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   248
   * Retrieves a result set that contains the elements of the SQL
90ce3da70b43 Initial load
duke
parents:
diff changeset
   249
   * <code>ARRAY</code> value designated by this <code>Array</code> object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
   * This method uses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   251
   * the specified <code>map</code> for type map customizations
90ce3da70b43 Initial load
duke
parents:
diff changeset
   252
   * unless the base type of the array does not match a user-defined
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
   * type in <code>map</code>, in which case it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
   * uses the standard mapping. This version of the method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
   * <code>getResultSet</code> uses either the given type map or the standard mapping;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   256
   * it never uses the type map associated with the connection.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
   * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
   * The result set contains one row for each array element, with
90ce3da70b43 Initial load
duke
parents:
diff changeset
   259
   * two columns in each row.  The second column stores the element
90ce3da70b43 Initial load
duke
parents:
diff changeset
   260
   * value; the first column stores the index into the array for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   261
   * that element (with the first array element being at index 1).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
   * The rows are in ascending order corresponding to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
   * the order of the indices.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
   * @param map contains the mapping of SQL user-defined types to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   266
   * classes in the Java programming language
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
   * @return a <code>ResultSet</code> object containing one row for each
90ce3da70b43 Initial load
duke
parents:
diff changeset
   268
   * of the elements in the array designated by this <code>Array</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   269
   * object, with the rows in ascending order based on the indices.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   270
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   271
   * access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   274
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
  ResultSet getResultSet (java.util.Map<String,Class<?>> map) throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   277
90ce3da70b43 Initial load
duke
parents:
diff changeset
   278
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   279
   * Retrieves a result set holding the elements of the subarray that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   280
   * starts at index <code>index</code> and contains up to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   281
   * <code>count</code> successive elements.  This method uses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   282
   * the connection's type map to map the elements of the array if
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
   * the map contains an entry for the base type. Otherwise, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
   * standard mapping is used.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   285
   * <P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   286
   * The result set has one row for each element of the SQL array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   287
   * designated by this object, with the first row containing the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
   * element at index <code>index</code>.  The result set has
90ce3da70b43 Initial load
duke
parents:
diff changeset
   289
   * up to <code>count</code> rows in ascending order based on the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   290
   * indices.  Each row has two columns:  The second column stores
90ce3da70b43 Initial load
duke
parents:
diff changeset
   291
   * the element value; the first column stores the index into the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   292
   * array for that element.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   293
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   294
   * @param index the array index of the first element to retrieve;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   295
   *              the first element is at index 1
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
   * @param count the number of successive SQL array elements to retrieve
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
   * @return a <code>ResultSet</code> object containing up to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   298
   * <code>count</code> consecutive elements of the SQL array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   299
   * designated by this <code>Array</code> object, starting at
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
   * index <code>index</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
   * access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   304
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
  ResultSet getResultSet(long index, int count) throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
90ce3da70b43 Initial load
duke
parents:
diff changeset
   309
  /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   310
   * Retrieves a result set holding the elements of the subarray that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
   * starts at index <code>index</code> and contains up to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
   * <code>count</code> successive elements.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   313
   * This method uses
90ce3da70b43 Initial load
duke
parents:
diff changeset
   314
   * the specified <code>map</code> for type map customizations
90ce3da70b43 Initial load
duke
parents:
diff changeset
   315
   * unless the base type of the array does not match a user-defined
90ce3da70b43 Initial load
duke
parents:
diff changeset
   316
   * type in <code>map</code>, in which case it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   317
   * uses the standard mapping. This version of the method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   318
   * <code>getResultSet</code> uses either the given type map or the standard mapping;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   319
   * it never uses the type map associated with the connection.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   320
   * <P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   321
   * The result set has one row for each element of the SQL array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   322
   * designated by this object, with the first row containing the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   323
   * element at index <code>index</code>.  The result set has
90ce3da70b43 Initial load
duke
parents:
diff changeset
   324
   * up to <code>count</code> rows in ascending order based on the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   325
   * indices.  Each row has two columns:  The second column stores
21278
ef8a3a2a72f2 8022746: List of spelling errors in API doc
malenkov
parents: 5506
diff changeset
   326
   * the element value; the first column stores the index into the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   327
   * array for that element.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   328
   *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   329
   * @param index the array index of the first element to retrieve;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   330
   *              the first element is at index 1
90ce3da70b43 Initial load
duke
parents:
diff changeset
   331
   * @param count the number of successive SQL array elements to retrieve
90ce3da70b43 Initial load
duke
parents:
diff changeset
   332
   * @param map the <code>Map</code> object that contains the mapping
90ce3da70b43 Initial load
duke
parents:
diff changeset
   333
   * of SQL type names to classes in the Java(tm) programming language
90ce3da70b43 Initial load
duke
parents:
diff changeset
   334
   * @return a <code>ResultSet</code> object containing up to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   335
   * <code>count</code> consecutive elements of the SQL array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   336
   * designated by this <code>Array</code> object, starting at
90ce3da70b43 Initial load
duke
parents:
diff changeset
   337
   * index <code>index</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   338
   * @exception SQLException if an error occurs while attempting to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   339
   * access the array
90ce3da70b43 Initial load
duke
parents:
diff changeset
   340
   * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   341
   * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   342
   * @since 1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   343
   */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   344
  ResultSet getResultSet (long index, int count,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   345
                          java.util.Map<String,Class<?>> map)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   346
    throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   347
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   348
     * This method frees the <code>Array</code> object and releases the resources that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   349
     * it holds. The object is invalid once the <code>free</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   350
     * method is called.
23590
ffd8b0b70511 8038493: Tidy warnings cleanup for java.sql
yan
parents: 23010
diff changeset
   351
     * <p>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   352
     * After <code>free</code> has been called, any attempt to invoke a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   353
     * method other than <code>free</code> will result in a <code>SQLException</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   354
     * being thrown.  If <code>free</code> is called multiple times, the subsequent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   355
     * calls to <code>free</code> are treated as a no-op.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   356
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   357
     * @throws SQLException if an error occurs releasing
90ce3da70b43 Initial load
duke
parents:
diff changeset
   358
     * the Array's resources
90ce3da70b43 Initial load
duke
parents:
diff changeset
   359
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
90ce3da70b43 Initial load
duke
parents:
diff changeset
   360
     * this method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   361
     * @since 1.6
90ce3da70b43 Initial load
duke
parents:
diff changeset
   362
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   363
    void free() throws SQLException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   364
90ce3da70b43 Initial load
duke
parents:
diff changeset
   365
}