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 */ getColumnCount()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 */ isAutoIncrement(int column)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 */ isCaseSensitive(int column)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 */ isSearchable(int column)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 */ isCurrency(int column)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 */ isNullable(int column)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 */ isSigned(int column)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 */ getColumnDisplaySize(int column)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 */ getColumnLabel(int column)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 */ getColumnName(int column)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 */ getSchemaName(int column)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 */ getPrecision(int column)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 */ getScale(int column)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 */ getTableName(int column)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 */ getCatalogName(int column)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 */ getColumnType(int column)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 */ getColumnTypeName(int column)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 */ isReadOnly(int column)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 */ isWritable(int column)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 */ isDefinitelyWritable(int column)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 */ getColumnClassName(int column)276 String getColumnClassName(int column) throws SQLException; 277 } 278