Array.java revision cec4dd4b1d33f78997603d0f89c0d0e56e64dbcd 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.sql;
19
20import java.util.Map;
21
22/**
23 * A Java representation of the SQL {@code ARRAY} type.
24 */
25public interface Array {
26
27    /**
28     * Retrieves the contents of the SQL {@code ARRAY} value as a Java array
29     * object.
30     *
31     * @return A Java array containing the elements of this Array
32     * @throws SQLException
33     *             if there is a database error.
34     */
35    public Object getArray() throws SQLException;
36
37    /**
38     * Returns part of the SQL {@code ARRAY} associated with this array,
39     * starting at a particular {@code index} and comprising up to {@code count}
40     * successive elements of the SQL array.
41     *
42     * @param index
43     *            the start position in the array where the values are
44     *            retrieved.
45     * @param count
46     *            the number of elements to retrieve.
47     * @return A Java array containing the desired set of elements from this Array
48     * @throws SQLException
49     *             if there is a database error.
50     */
51    public Object getArray(long index, int count) throws SQLException;
52
53    /**
54     * Returns part of the SQL {@code ARRAY} associated with this array,
55     * starting at a particular {@code index} and comprising up to {@code count}
56     * successive elements of the SQL array.
57     *
58     * @param index
59     *            the start position in the array where the values are
60     *            retrieved.
61     * @param count
62     *            the number of elements to retrieve.
63     * @param map
64     *            the map defining the correspondence between SQL type names
65     *            and Java types.
66     * @return A Java array containing the desired set of elements from this Array
67     * @throws SQLException
68     *             if there is a database error.
69     */
70    public Object getArray(long index, int count, Map<String, Class<?>> map)
71            throws SQLException;
72
73    /**
74     * Returns the data from the underlying SQL {@code ARRAY} as a Java array.
75     *
76     * @param map
77     *            the map defining the correspondence between SQL type names
78     *            and Java types.
79     * @return A Java array containing the elements of this array
80     * @throws SQLException
81     *             if there is a database error.
82     */
83    public Object getArray(Map<String, Class<?>> map) throws SQLException;
84
85    /**
86     * Returns the JDBC type of the entries in this array's underlying
87     * SQL array.
88     *
89     * @return An integer constant from the {@code java.sql.Types} class
90     * @throws SQLException
91     *             if there is a database error.
92     */
93    public int getBaseType() throws SQLException;
94
95    /**
96     * Returns the SQL type name of the entries in this array's underlying
97     * SQL array.
98     *
99     * @return The database specific name or a fully-qualified SQL type name.
100     * @throws SQLException
101     *              if there is a database error.
102     */
103    public String getBaseTypeName() throws SQLException;
104
105    /**
106     * Returns a ResultSet object which holds the entries of the SQL {@code
107     * ARRAY} associated with this array.
108     *
109     * @return the elements of the array as a {@code ResultSet}.
110     * @throws SQLException
111     *             if there is a database error.
112     */
113    public ResultSet getResultSet() throws SQLException;
114
115    /**
116     * Returns a {@code ResultSet} object that holds the entries of a subarray,
117     * beginning at a particular index and comprising up to {@code count}
118     * successive entries.
119     *
120     * @param index
121     *            the start position in the array where the values are
122     *            retrieved.
123     * @param count
124     *            the number of elements to retrieve.
125     * @return the elements of the array as a {@code ResultSet}.
126     * @throws SQLException
127     *             if there is a database error.
128     */
129    public ResultSet getResultSet(long index, int count) throws SQLException;
130
131    /**
132     * Returns a {@code ResultSet} object that holds the entries of a subarray,
133     * beginning at a particular index and comprising up to {@code count}
134     * successive entries.
135     *
136     * @param index
137     *            the start position in the array where the values are
138     *            retrieved.
139     * @param count
140     *            the number of elements to retrieve.
141     * @param map
142     *            the map defining the correspondence between SQL type names
143     *            and Java types.
144     * @return the {@code ResultSet} the array's custom type values. if a
145     *         database error has occurred.
146     * @throws SQLException
147     *             if there is a database error.
148     */
149    public ResultSet getResultSet(long index, int count,
150            Map<String, Class<?>> map) throws SQLException;
151
152    /**
153     * Returns a {@code ResultSet} object which holds the entries of the SQL
154     * {@code ARRAY} associated with this array.
155     *
156     * @param map
157     *            the map defining the correspondence between SQL type names
158     *            and Java types.
159     * @return the array as a {@code ResultSet}.
160     * @throws SQLException
161     *             if there is a database error.
162     */
163    public ResultSet getResultSet(Map<String, Class<?>> map)
164            throws SQLException;
165
166}
167