View Javadoc
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  
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 }