Array


1   /*
2    * @(#)Array.java   1.23 04/05/05
3    *
4    * Copyright 2004 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   * The mapping in the Java programming language for the SQL type
12   * <code>ARRAY</code>.
13   * By default, an <code>Array</code> value is a transaction-duration 
14   * reference to an SQL <code>ARRAY</code> value.  By default, an <code>Array</code>
15   * object is implemented using an SQL LOCATOR(array) internally, which
16   * means that an <code>Array</code> object contains a logical pointer
17   * to the data in the SQL <code>ARRAY</code> value rather
18   * than containing the <code>ARRAY</code> value's data.
19   * <p>
20   * The <code>Array</code> interface provides methods for bringing an SQL
21   * <code>ARRAY</code> value's data to the client as either an array or a
22   * <code>ResultSet</code> object.
23   * If the elements of the SQL <code>ARRAY</code>
24   * are a UDT, they may be custom mapped.  To create a custom mapping,
25   * a programmer must do two things:
26   * <ul>
27   * <li>create a class that implements the {@link SQLData}
28   * interface for the UDT to be custom mapped. 
29   * <li>make an entry in a type map that contains 
30   *   <ul>
31   *   <li>the fully-qualified SQL type name of the UDT
32   *   <li>the <code>Class</code> object for the class implementing
33   *       <code>SQLData</code>
34   *   </ul>
35   * </ul>
36   * <p>
37   * When a type map with an entry for
38   * the base type is supplied to the methods <code>getArray</code>
39   * and <code>getResultSet</code>, the mapping
40   * it contains will be used to map the elements of the <code>ARRAY</code> value.
41   * If no type map is supplied, which would typically be the case,
42   * the connection's type map is used by default.
43   * If the connection's type map or a type map supplied to a method has no entry
44   * for the base type, the elements are mapped according to the standard mapping.
45   * <p>
46   * @since 1.2 
47   */
48  
49  public interface Array {
50  
51    /**
52     * Retrieves the SQL type name of the elements in 
53     * the array designated by this <code>Array</code> object.
54     * If the elements are a built-in type, it returns
55     * the database-specific type name of the elements. 
56     * If the elements are a user-defined type (UDT),
57     * this method returns the fully-qualified SQL type name.
58     *
59     * @return a <code>String</code> that is the database-specific
60     * name for a built-in base type; or the fully-qualified SQL type
61     * name for a base type that is a UDT
62     * @exception SQLException if an error occurs while attempting
63     * to access the type name
64     * @since 1.2
65     */
66    String   getBaseTypeName() throws SQLException  ;
67  
68    /**
69     * Retrieves the JDBC type of the elements in the array designated
70     * by this <code>Array</code> object.
71     *
72     * @return a constant from the class {@link java.sql.Types} that is
73     * the type code for the elements in the array designated by this
74     * <code>Array</code> object
75     * @exception SQLException if an error occurs while attempting
76     * to access the base type 
77     * @since 1.2
78     */
79    int getBaseType() throws SQLException  ;
80  
81    /**
82     * Retrieves the contents of the SQL <code>ARRAY</code> value designated 
83     * by this
84     * <code>Array</code> object in the form of an array in the Java
85     * programming language. This version of the method <code>getArray</code>
86     * uses the type map associated with the connection for customizations of 
87     * the type mappings.
88     *
89     * @return an array in the Java programming language that contains 
90     * the ordered elements of the SQL <code>ARRAY</code> value
91     * designated by this <code>Array</code> object
92     * @exception SQLException if an error occurs while attempting to
93     * access the array
94     * @since 1.2
95     */
96    Object   getArray() throws SQLException  ;
97  
98    /**
99     * Retrieves the contents of the SQL <code>ARRAY</code> value designated by this 
100    * <code>Array</code> object.
101    * This method uses 
102    * the specified <code>map</code> for type map customizations
103    * unless the base type of the array does not match a user-defined 
104    * type in <code>map</code>, in which case it 
105    * uses the standard mapping. This version of the method
106    * <code>getArray</code> uses either the given type map or the standard mapping;
107    * it never uses the type map associated with the connection.
108    *
109    * @param map a <code>java.util.Map</code> object that contains mappings
110    *            of SQL type names to classes in the Java programming language
111    * @return an array in the Java programming language that contains the ordered 
112    *         elements of the SQL array designated by this object
113    * @exception SQLException if an error occurs while attempting to 
114    *                         access the array
115    * @since 1.2
116    */
117   Object   getArray(java.util.Map  <String  ,Class  <?>> map) throws SQLException  ;
118 
119   /**
120    * Retrieves a slice of the SQL <code>ARRAY</code>
121    * value designated by this <code>Array</code> object, beginning with the
122    * specified <code>index</code> and containing up to <code>count</code> 
123    * successive elements of the SQL array.  This method uses the type map
124    * associated with the connection for customizations of the type mappings.
125    *
126    * @param index the array index of the first element to retrieve;
127    *              the first element is at index 1
128    * @param count the number of successive SQL array elements to retrieve
129    * @return an array containing up to <code>count</code> consecutive elements 
130    * of the SQL array, beginning with element <code>index</code>
131    * @exception SQLException if an error occurs while attempting to
132    * access the array
133    * @since 1.2
134    */
135   Object   getArray(long index, int count) throws SQLException  ;
136 
137   /**
138    * Retreives a slice of the SQL <code>ARRAY</code> value 
139    * designated by this <code>Array</code> object, beginning with the specified
140    * <code>index</code> and containing up to <code>count</code>
141    * successive elements of the SQL array.  
142    * <P>
143    * This method uses 
144    * the specified <code>map</code> for type map customizations
145    * unless the base type of the array does not match a user-defined 
146    * type in <code>map</code>, in which case it 
147    * uses the standard mapping. This version of the method
148    * <code>getArray</code> uses either the given type map or the standard mapping;
149    * it never uses the type map associated with the connection.
150    *
151    * @param index the array index of the first element to retrieve;
152    *              the first element is at index 1
153    * @param count the number of successive SQL array elements to 
154    * retrieve
155    * @param map a <code>java.util.Map</code> object
156    * that contains SQL type names and the classes in
157    * the Java programming language to which they are mapped
158    * @return an array containing up to <code>count</code>
159    * consecutive elements of the SQL <code>ARRAY</code> value designated by this
160    * <code>Array</code> object, beginning with element 
161    * <code>index</code>
162    * @exception SQLException if an error occurs while attempting to
163    * access the array
164    * @since 1.2
165    */
166   Object   getArray(long index, int count, java.util.Map  <String  ,Class  <?>> map)
167     throws SQLException  ;
168 
169   /**
170    * Retrieves a result set that contains the elements of the SQL 
171    * <code>ARRAY</code> value
172    * designated by this <code>Array</code> object.  If appropriate,
173    * the elements of the array are mapped using the connection's type 
174    * map; otherwise, the standard mapping is used.
175    * <p>
176    * The result set contains one row for each array element, with
177    * two columns in each row.  The second column stores the element
178    * value; the first column stores the index into the array for 
179    * that element (with the first array element being at index 1). 
180    * The rows are in ascending order corresponding to
181    * the order of the indices.
182    *
183    * @return a {@link ResultSet} object containing one row for each
184    * of the elements in the array designated by this <code>Array</code>
185    * object, with the rows in ascending order based on the indices.
186    * @exception SQLException if an error occurs while attempting to
187    * access the array
188    * @since 1.2
189    */
190   ResultSet   getResultSet () throws SQLException  ;
191 
192   /**
193    * Retrieves a result set that contains the elements of the SQL 
194    * <code>ARRAY</code> value designated by this <code>Array</code> object.
195    * This method uses 
196    * the specified <code>map</code> for type map customizations
197    * unless the base type of the array does not match a user-defined 
198    * type in <code>map</code>, in which case it 
199    * uses the standard mapping. This version of the method
200    * <code>getResultSet</code> uses either the given type map or the standard mapping;
201    * it never uses the type map associated with the connection.
202    * <p>
203    * The result set contains one row for each array element, with
204    * two columns in each row.  The second column stores the element
205    * value; the first column stores the index into the array for 
206    * that element (with the first array element being at index 1). 
207    * The rows are in ascending order corresponding to
208    * the order of the indices.
209    *
210    * @param map contains the mapping of SQL user-defined types to 
211    * classes in the Java programming language
212    * @return a <code>ResultSet</code> object containing one row for each
213    * of the elements in the array designated by this <code>Array</code>
214    * object, with the rows in ascending order based on the indices.
215    * @exception SQLException if an error occurs while attempting to
216    * access the array
217    * @since 1.2
218    */
219   ResultSet   getResultSet (java.util.Map  <String  ,Class  <?>> map) throws SQLException  ;
220 
221   /**
222    * Retrieves a result set holding the elements of the subarray that
223    * starts at index <code>index</code> and contains up to 
224    * <code>count</code> successive elements.  This method uses
225    * the connection's type map to map the elements of the array if
226    * the map contains an entry for the base type. Otherwise, the
227    * standard mapping is used.
228    * <P>
229    * The result set has one row for each element of the SQL array
230    * designated by this object, with the first row containing the 
231    * element at index <code>index</code>.  The result set has
232    * up to <code>count</code> rows in ascending order based on the
233    * indices.  Each row has two columns:  The second column stores
234    * the element value; the first column stores the index into the
235    * array for that element.
236    *
237    * @param index the array index of the first element to retrieve;
238    *              the first element is at index 1
239    * @param count the number of successive SQL array elements to retrieve
240    * @return a <code>ResultSet</code> object containing up to
241    * <code>count</code> consecutive elements of the SQL array
242    * designated by this <code>Array</code> object, starting at
243    * index <code>index</code>.
244    * @exception SQLException if an error occurs while attempting to
245    * access the array
246    * @since 1.2
247    */
248   ResultSet   getResultSet(long index, int count) throws SQLException  ;
249 
250   /**
251    * Retrieves a result set holding the elements of the subarray that
252    * starts at index <code>index</code> and contains up to
253    * <code>count</code> successive elements.
254    * This method uses 
255    * the specified <code>map</code> for type map customizations
256    * unless the base type of the array does not match a user-defined 
257    * type in <code>map</code>, in which case it 
258    * uses the standard mapping. This version of the method
259    * <code>getResultSet</code> uses either the given type map or the standard mapping;
260    * it never uses the type map associated with the connection.
261    * <P>
262    * The result set has one row for each element of the SQL array
263    * designated by this object, with the first row containing the
264    * element at index <code>index</code>.  The result set has   
265    * up to <code>count</code> rows in ascending order based on the
266    * indices.  Each row has two columns:  The second column stores  
267    * the element value; the first column stroes the index into the
268    * array for that element.
269    *
270    * @param index the array index of the first element to retrieve;
271    *              the first element is at index 1
272    * @param count the number of successive SQL array elements to retrieve
273    * @param map the <code>Map</code> object that contains the mapping
274    * of SQL type names to classes in the Java(tm) programming language
275    * @return a <code>ResultSet</code> object containing up to               
276    * <code>count</code> consecutive elements of the SQL array
277    * designated by this <code>Array</code> object, starting at
278    * index <code>index</code>.
279    * @exception SQLException if an error occurs while attempting to
280    * access the array
281    * @since 1.2
282    */
283   ResultSet   getResultSet (long index, int count,
284               java.util.Map  <String  ,Class  <?>> map)
285     throws SQLException  ;
286 
287 }
288 
289 
290
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags