1 /*
2 * Copyright 1996-2005 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package 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
45 public 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 }
Save This Page