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