001 /*
002 * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.sql;
027
028 /**
029 * The mapping in the Java programming language for the SQL type
030 * <code>ARRAY</code>.
031 * By default, an <code>Array</code> value is a transaction-duration
032 * reference to an SQL <code>ARRAY</code> value. By default, an <code>Array</code>
033 * object is implemented using an SQL LOCATOR(array) internally, which
034 * means that an <code>Array</code> object contains a logical pointer
035 * to the data in the SQL <code>ARRAY</code> value rather
036 * than containing the <code>ARRAY</code> value's data.
037 * <p>
038 * The <code>Array</code> interface provides methods for bringing an SQL
039 * <code>ARRAY</code> value's data to the client as either an array or a
040 * <code>ResultSet</code> object.
041 * If the elements of the SQL <code>ARRAY</code>
042 * are a UDT, they may be custom mapped. To create a custom mapping,
043 * a programmer must do two things:
044 * <ul>
045 * <li>create a class that implements the {@link SQLData}
046 * interface for the UDT to be custom mapped.
047 * <li>make an entry in a type map that contains
048 * <ul>
049 * <li>the fully-qualified SQL type name of the UDT
050 * <li>the <code>Class</code> object for the class implementing
051 * <code>SQLData</code>
052 * </ul>
053 * </ul>
054 * <p>
055 * When a type map with an entry for
056 * the base type is supplied to the methods <code>getArray</code>
057 * and <code>getResultSet</code>, the mapping
058 * it contains will be used to map the elements of the <code>ARRAY</code> value.
059 * If no type map is supplied, which would typically be the case,
060 * the connection's type map is used by default.
061 * If the connection's type map or a type map supplied to a method has no entry
062 * for the base type, the elements are mapped according to the standard mapping.
063 * <p>
064 * All methods on the <code>Array</code> interface must be fully implemented if the
065 * JDBC driver supports the data type.
066 *
067 * @since 1.2
068 */
069
070 public interface Array {
071
072 /**
073 * Retrieves the SQL type name of the elements in
074 * the array designated by this <code>Array</code> object.
075 * If the elements are a built-in type, it returns
076 * the database-specific type name of the elements.
077 * If the elements are a user-defined type (UDT),
078 * this method returns the fully-qualified SQL type name.
079 *
080 * @return a <code>String</code> that is the database-specific
081 * name for a built-in base type; or the fully-qualified SQL type
082 * name for a base type that is a UDT
083 * @exception SQLException if an error occurs while attempting
084 * to access the type name
085 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
086 * this method
087 * @since 1.2
088 */
089 String getBaseTypeName() throws SQLException;
090
091 /**
092 * Retrieves the JDBC type of the elements in the array designated
093 * by this <code>Array</code> object.
094 *
095 * @return a constant from the class {@link java.sql.Types} that is
096 * the type code for the elements in the array designated by this
097 * <code>Array</code> object
098 * @exception SQLException if an error occurs while attempting
099 * 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)
157 throws SQLException;
158
159 /**
160 * Retrieves a slice of the SQL <code>ARRAY</code>
161 * value designated by this <code>Array</code> object, beginning with the
162 * specified <code>index</code> and containing up to <code>count</code>
163 * successive elements of the SQL array. This method uses the type map
164 * associated with the connection for customizations of the type mappings.
165 * <p>
166 * <strong>Note:</strong> When <code>getArray</code> is used to materialize
167 * a base type that maps to a primitive data type, then it is
168 * implementation-defined whether the array returned is an array of
169 * that primitive data type or an array of <code>Object</code>.
170 *
171 * @param index the array index of the first element to retrieve;
172 * the first element is at index 1
173 * @param count the number of successive SQL array elements to retrieve
174 * @return an array containing up to <code>count</code> consecutive elements
175 * of the SQL array, beginning with element <code>index</code>
176 * @exception SQLException if an error occurs while attempting to
177 * access the array
178 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
179 * this method
180 * @since 1.2
181 */
182 Object getArray(long index, int count) throws SQLException;
183
184 /**
185 * Retreives a slice of the SQL <code>ARRAY</code> value
186 * designated by this <code>Array</code> object, beginning with the specified
187 * <code>index</code> and containing up to <code>count</code>
188 * successive elements of the SQL array.
189 * <P>
190 * This method uses
191 * the specified <code>map</code> for type map customizations
192 * unless the base type of the array does not match a user-defined
193 * type in <code>map</code>, in which case it
194 * uses the standard mapping. This version of the method
195 * <code>getArray</code> uses either the given type map or the standard mapping;
196 * it never uses the type map associated with the connection.
197 * <p>
198 * <strong>Note:</strong> When <code>getArray</code> is used to materialize
199 * a base type that maps to a primitive data type, then it is
200 * implementation-defined whether the array returned is an array of
201 * that primitive data type or an array of <code>Object</code>.
202 *
203 * @param index the array index of the first element to retrieve;
204 * the first element is at index 1
205 * @param count the number of successive SQL array elements to
206 * retrieve
207 * @param map a <code>java.util.Map</code> object
208 * that contains SQL type names and the classes in
209 * the Java programming language to which they are mapped
210 * @return an array containing up to <code>count</code>
211 * consecutive elements of the SQL <code>ARRAY</code> value designated by this
212 * <code>Array</code> object, beginning with element
213 * <code>index</code>
214 * @exception SQLException if an error occurs while attempting to
215 * access the array
216 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
217 * this method
218 * @since 1.2
219 */
220 Object getArray(long index, int count,
221 java.util.Map<String, Class<?>> map) throws SQLException;
222
223 /**
224 * Retrieves a result set that contains the elements of the SQL
225 * <code>ARRAY</code> value
226 * designated by this <code>Array</code> object. If appropriate,
227 * the elements of the array are mapped using the connection's type
228 * map; otherwise, the standard mapping is used.
229 * <p>
230 * The result set contains one row for each array element, with
231 * two columns in each row. The second column stores the element
232 * value; the first column stores the index into the array for
233 * that element (with the first array element being at index 1).
234 * The rows are in ascending order corresponding to
235 * the order of the indices.
236 *
237 * @return a {@link ResultSet} object containing one row for each
238 * of the elements in the array designated by this <code>Array</code>
239 * object, with the rows in ascending order based on the indices.
240 * @exception SQLException if an error occurs while attempting to
241 * access the array
242 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
243 * this method
244 * @since 1.2
245 */
246 ResultSet getResultSet() throws SQLException;
247
248 /**
249 * Retrieves a result set that contains the elements of the SQL
250 * <code>ARRAY</code> value designated by this <code>Array</code> object.
251 * This method uses
252 * the specified <code>map</code> for type map customizations
253 * unless the base type of the array does not match a user-defined
254 * type in <code>map</code>, in which case it
255 * uses the standard mapping. This version of the method
256 * <code>getResultSet</code> uses either the given type map or the standard mapping;
257 * it never uses the type map associated with the connection.
258 * <p>
259 * The result set contains one row for each array element, with
260 * two columns in each row. The second column stores the element
261 * value; the first column stores the index into the array for
262 * that element (with the first array element being at index 1).
263 * The rows are in ascending order corresponding to
264 * the order of the indices.
265 *
266 * @param map contains the mapping of SQL user-defined types to
267 * classes in the Java programming language
268 * @return a <code>ResultSet</code> object containing one row for each
269 * of the elements in the array designated by this <code>Array</code>
270 * object, with the rows in ascending order based on the indices.
271 * @exception SQLException if an error occurs while attempting to
272 * access the array
273 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
274 * this method
275 * @since 1.2
276 */
277 ResultSet getResultSet(java.util.Map<String, Class<?>> map)
278 throws SQLException;
279
280 /**
281 * Retrieves a result set holding the elements of the subarray that
282 * starts at index <code>index</code> and contains up to
283 * <code>count</code> successive elements. This method uses
284 * the connection's type map to map the elements of the array if
285 * the map contains an entry for the base type. Otherwise, the
286 * standard mapping is used.
287 * <P>
288 * The result set has one row for each element of the SQL array
289 * designated by this object, with the first row containing the
290 * element at index <code>index</code>. The result set has
291 * up to <code>count</code> rows in ascending order based on the
292 * indices. Each row has two columns: The second column stores
293 * the element value; the first column stores the index into the
294 * array for that element.
295 *
296 * @param index the array index of the first element to retrieve;
297 * the first element is at index 1
298 * @param count the number of successive SQL array elements to retrieve
299 * @return a <code>ResultSet</code> object containing up to
300 * <code>count</code> consecutive elements of the SQL array
301 * designated by this <code>Array</code> object, starting at
302 * index <code>index</code>.
303 * @exception SQLException if an error occurs while attempting to
304 * access the array
305 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
306 * this method
307 * @since 1.2
308 */
309 ResultSet getResultSet(long index, int count) throws SQLException;
310
311 /**
312 * Retrieves a result set holding the elements of the subarray that
313 * starts at index <code>index</code> and contains up to
314 * <code>count</code> successive elements.
315 * This method uses
316 * the specified <code>map</code> for type map customizations
317 * unless the base type of the array does not match a user-defined
318 * type in <code>map</code>, in which case it
319 * uses the standard mapping. This version of the method
320 * <code>getResultSet</code> uses either the given type map or the standard mapping;
321 * it never uses the type map associated with the connection.
322 * <P>
323 * The result set has one row for each element of the SQL array
324 * designated by this object, with the first row containing the
325 * element at index <code>index</code>. The result set has
326 * up to <code>count</code> rows in ascending order based on the
327 * indices. Each row has two columns: The second column stores
328 * the element value; the first column stroes the index into the
329 * array for that element.
330 *
331 * @param index the array index of the first element to retrieve;
332 * the first element is at index 1
333 * @param count the number of successive SQL array elements to retrieve
334 * @param map the <code>Map</code> object that contains the mapping
335 * of SQL type names to classes in the Java(tm) programming language
336 * @return a <code>ResultSet</code> object containing up to
337 * <code>count</code> consecutive elements of the SQL array
338 * designated by this <code>Array</code> object, starting at
339 * index <code>index</code>.
340 * @exception SQLException if an error occurs while attempting to
341 * access the array
342 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
343 * this method
344 * @since 1.2
345 */
346 ResultSet getResultSet(long index, int count,
347 java.util.Map<String, Class<?>> map) throws SQLException;
348
349 /**
350 * This method frees the <code>Array</code> object and releases the resources that
351 * it holds. The object is invalid once the <code>free</code>
352 * method is called.
353 *<p>
354 * After <code>free</code> has been called, any attempt to invoke a
355 * method other than <code>free</code> will result in a <code>SQLException</code>
356 * being thrown. If <code>free</code> is called multiple times, the subsequent
357 * calls to <code>free</code> are treated as a no-op.
358 *<p>
359 *
360 * @throws SQLException if an error occurs releasing
361 * the Array's resources
362 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
363 * this method
364 * @since 1.6
365 */
366 void free() throws SQLException;
367
368 }
|