1/*
2 * Copyright (c) 1996, 2005, 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
26package java.sql;
27
28/**
29 * An object that can be used to get information about the types
30 * and properties of the columns in a <code>ResultSet</code> object.
31 * The following code fragment creates the <code>ResultSet</code> object rs,
32 * creates the <code>ResultSetMetaData</code> object rsmd, and uses rsmd
33 * to find out how many columns rs has and whether the first column in rs
34 * can be used in a <code>WHERE</code> clause.
35 * <PRE>
36 *
37 *     ResultSet rs = stmt.executeQuery("SELECT a, b, c FROM TABLE2");
38 *     ResultSetMetaData rsmd = rs.getMetaData();
39 *     int numberOfColumns = rsmd.getColumnCount();
40 *     boolean b = rsmd.isSearchable(1);
41 *
42 * </PRE>
43 */
44
45public interface ResultSetMetaData extends Wrapper {
46
47    /**
48     * Returns the number of columns in this <code>ResultSet</code> object.
49     *
50     * @return the number of columns
51     * @exception SQLException if a database access error occurs
52     */
53    int getColumnCount() throws SQLException;
54
55    /**
56     * Indicates whether the designated column is automatically numbered.
57     *
58     * @param column the first column is 1, the second is 2, ...
59     * @return <code>true</code> if so; <code>false</code> otherwise
60     * @exception SQLException if a database access error occurs
61     */
62    boolean isAutoIncrement(int column) throws SQLException;
63
64    /**
65     * Indicates whether a column's case matters.
66     *
67     * @param column the first column is 1, the second is 2, ...
68     * @return <code>true</code> if so; <code>false</code> otherwise
69     * @exception SQLException if a database access error occurs
70     */
71    boolean isCaseSensitive(int column) throws SQLException;
72
73    /**
74     * Indicates whether the designated column can be used in a where clause.
75     *
76     * @param column the first column is 1, the second is 2, ...
77     * @return <code>true</code> if so; <code>false</code> otherwise
78     * @exception SQLException if a database access error occurs
79     */
80    boolean isSearchable(int column) throws SQLException;
81
82    /**
83     * Indicates whether the designated column is a cash value.
84     *
85     * @param column the first column is 1, the second is 2, ...
86     * @return <code>true</code> if so; <code>false</code> otherwise
87     * @exception SQLException if a database access error occurs
88     */
89    boolean isCurrency(int column) throws SQLException;
90
91    /**
92     * Indicates the nullability of values in the designated column.
93     *
94     * @param column the first column is 1, the second is 2, ...
95     * @return the nullability status of the given column; one of <code>columnNoNulls</code>,
96     *          <code>columnNullable</code> or <code>columnNullableUnknown</code>
97     * @exception SQLException if a database access error occurs
98     */
99    int isNullable(int column) throws SQLException;
100
101    /**
102     * The constant indicating that a
103     * column does not allow <code>NULL</code> values.
104     */
105    int columnNoNulls = 0;
106
107    /**
108     * The constant indicating that a
109     * column allows <code>NULL</code> values.
110     */
111    int columnNullable = 1;
112
113    /**
114     * The constant indicating that the
115     * nullability of a column's values is unknown.
116     */
117    int columnNullableUnknown = 2;
118
119    /**
120     * Indicates whether values in the designated column are signed numbers.
121     *
122     * @param column the first column is 1, the second is 2, ...
123     * @return <code>true</code> if so; <code>false</code> otherwise
124     * @exception SQLException if a database access error occurs
125     */
126    boolean isSigned(int column) throws SQLException;
127
128    /**
129     * Indicates the designated column's normal maximum width in characters.
130     *
131     * @param column the first column is 1, the second is 2, ...
132     * @return the normal maximum number of characters allowed as the width
133     *          of the designated column
134     * @exception SQLException if a database access error occurs
135     */
136    int getColumnDisplaySize(int column) throws SQLException;
137
138    /**
139     * Gets the designated column's suggested title for use in printouts and
140     * displays. The suggested title is usually specified by the SQL <code>AS</code>
141     * clause.  If a SQL <code>AS</code> is not specified, the value returned from
142     * <code>getColumnLabel</code> will be the same as the value returned by the
143     * <code>getColumnName</code> method.
144     *
145     * @param column the first column is 1, the second is 2, ...
146     * @return the suggested column title
147     * @exception SQLException if a database access error occurs
148     */
149    String getColumnLabel(int column) throws SQLException;
150
151    /**
152     * Get the designated column's name.
153     *
154     * @param column the first column is 1, the second is 2, ...
155     * @return column name
156     * @exception SQLException if a database access error occurs
157     */
158    String getColumnName(int column) throws SQLException;
159
160    /**
161     * Get the designated column's table's schema.
162     *
163     * @param column the first column is 1, the second is 2, ...
164     * @return schema name or "" if not applicable
165     * @exception SQLException if a database access error occurs
166     */
167    String getSchemaName(int column) throws SQLException;
168
169    /**
170     * Get the designated column's specified column size.
171     * For numeric data, this is the maximum precision.  For character data, this is the length in characters.
172     * For datetime datatypes, this is the length in characters of the String representation (assuming the
173     * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes.  For the ROWID datatype,
174     * this is the length in bytes. 0 is returned for data types where the
175     * column size is not applicable.
176     *
177     * @param column the first column is 1, the second is 2, ...
178     * @return precision
179     * @exception SQLException if a database access error occurs
180     */
181    int getPrecision(int column) throws SQLException;
182
183    /**
184     * Gets the designated column's number of digits to right of the decimal point.
185     * 0 is returned for data types where the scale is not applicable.
186     *
187     * @param column the first column is 1, the second is 2, ...
188     * @return scale
189     * @exception SQLException if a database access error occurs
190     */
191    int getScale(int column) throws SQLException;
192
193    /**
194     * Gets the designated column's table name.
195     *
196     * @param column the first column is 1, the second is 2, ...
197     * @return table name or "" if not applicable
198     * @exception SQLException if a database access error occurs
199     */
200    String getTableName(int column) throws SQLException;
201
202    /**
203     * Gets the designated column's table's catalog name.
204     *
205     * @param column the first column is 1, the second is 2, ...
206     * @return the name of the catalog for the table in which the given column
207     *          appears or "" if not applicable
208     * @exception SQLException if a database access error occurs
209     */
210    String getCatalogName(int column) throws SQLException;
211
212    /**
213     * Retrieves the designated column's SQL type.
214     *
215     * @param column the first column is 1, the second is 2, ...
216     * @return SQL type from java.sql.Types
217     * @exception SQLException if a database access error occurs
218     * @see Types
219     */
220    int getColumnType(int column) throws SQLException;
221
222    /**
223     * Retrieves the designated column's database-specific type name.
224     *
225     * @param column the first column is 1, the second is 2, ...
226     * @return type name used by the database. If the column type is
227     * a user-defined type, then a fully-qualified type name is returned.
228     * @exception SQLException if a database access error occurs
229     */
230    String getColumnTypeName(int column) throws SQLException;
231
232    /**
233     * Indicates whether the designated column is definitely not writable.
234     *
235     * @param column the first column is 1, the second is 2, ...
236     * @return <code>true</code> if so; <code>false</code> otherwise
237     * @exception SQLException if a database access error occurs
238     */
239    boolean isReadOnly(int column) throws SQLException;
240
241    /**
242     * Indicates whether it is possible for a write on the designated column to succeed.
243     *
244     * @param column the first column is 1, the second is 2, ...
245     * @return <code>true</code> if so; <code>false</code> otherwise
246     * @exception SQLException if a database access error occurs
247     */
248    boolean isWritable(int column) throws SQLException;
249
250    /**
251     * Indicates whether a write on the designated column will definitely succeed.
252     *
253     * @param column the first column is 1, the second is 2, ...
254     * @return <code>true</code> if so; <code>false</code> otherwise
255     * @exception SQLException if a database access error occurs
256     */
257    boolean isDefinitelyWritable(int column) throws SQLException;
258
259    //--------------------------JDBC 2.0-----------------------------------
260
261    /**
262     * <p>Returns the fully-qualified name of the Java class whose instances
263     * are manufactured if the method <code>ResultSet.getObject</code>
264     * is called to retrieve a value
265     * from the column.  <code>ResultSet.getObject</code> may return a subclass of the
266     * class returned by this method.
267     *
268     * @param column the first column is 1, the second is 2, ...
269     * @return the fully-qualified name of the class in the Java programming
270     *         language that would be used by the method
271     * <code>ResultSet.getObject</code> to retrieve the value in the specified
272     * column. This is the class name used for custom mapping.
273     * @exception SQLException if a database access error occurs
274     * @since 1.2
275     */
276    String getColumnClassName(int column) throws SQLException;
277}
278