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: }
|
