History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/sql/Array.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/sql/Array.java+366−0
@@ -0,0 +1,366 @@
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+ */
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 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+ */
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+ */
364+ void free() throws SQLException;
365+
366+}