1 /*
2 * Copyright (c) 1998, 2013, 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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 stores 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 */
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 *
357 * @throws SQLException if an error occurs releasing
358 * the Array's resources
359 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
360 * this method
361 * @since 1.6
362 */
363 void free() throws SQLException;
364
365 }