001 /*
002 * Copyright 1996-2005 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 * An object that can be used to get information about the types
030 * and properties of the columns in a <code>ResultSet</code> object.
031 * The following code fragment creates the <code>ResultSet</code> object rs,
032 * creates the <code>ResultSetMetaData</code> object rsmd, and uses rsmd
033 * to find out how many columns rs has and whether the first column in rs
034 * can be used in a <code>WHERE</code> clause.
035 * <PRE>
036 *
037 * ResultSet rs = stmt.executeQuery("SELECT a, b, c FROM TABLE2");
038 * ResultSetMetaData rsmd = rs.getMetaData();
039 * int numberOfColumns = rsmd.getColumnCount();
040 * boolean b = rsmd.isSearchable(1);
041 *
042 * </PRE>
043 */
044
045 public interface ResultSetMetaData extends Wrapper {
046
047 /**
048 * Returns the number of columns in this <code>ResultSet</code> object.
049 *
050 * @return the number of columns
051 * @exception SQLException if a database access error occurs
052 */
053 int getColumnCount() throws SQLException;
054
055 /**
056 * Indicates whether the designated column is automatically numbered.
057 *
058 * @param column the first column is 1, the second is 2, ...
059 * @return <code>true</code> if so; <code>false</code> otherwise
060 * @exception SQLException if a database access error occurs
061 */
062 boolean isAutoIncrement(int column) throws SQLException;
063
064 /**
065 * Indicates whether a column's case matters.
066 *
067 * @param column the first column is 1, the second is 2, ...
068 * @return <code>true</code> if so; <code>false</code> otherwise
069 * @exception SQLException if a database access error occurs
070 */
071 boolean isCaseSensitive(int column) throws SQLException;
072
073 /**
074 * Indicates whether the designated column can be used in a where clause.
075 *
076 * @param column the first column is 1, the second is 2, ...
077 * @return <code>true</code> if so; <code>false</code> otherwise
078 * @exception SQLException if a database access error occurs
079 */
080 boolean isSearchable(int column) throws SQLException;
081
082 /**
083 * Indicates whether the designated column is a cash value.
084 *
085 * @param column the first column is 1, the second is 2, ...
086 * @return <code>true</code> if so; <code>false</code> otherwise
087 * @exception SQLException if a database access error occurs
088 */
089 boolean isCurrency(int column) throws SQLException;
090
091 /**
092 * Indicates the nullability of values in the designated column.
093 *
094 * @param column the first column is 1, the second is 2, ...
095 * @return the nullability status of the given column; one of <code>columnNoNulls</code>,
096 * <code>columnNullable</code> or <code>columnNullableUnknown</code>
097 * @exception SQLException if a database access error occurs
098 */
099 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 }
|