001 /*
002 * Copyright 2000-2006 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 for each parameter marker in a
031 * <code>PreparedStatement</code> object. For some queries and driver
032 * implementations, the data that would be returned by a <code>ParameterMetaData</code>
033 * object may not be available until the <code>PreparedStatement</code> has
034 * been executed.
035 *<p>
036 *Some driver implementations may not be able to provide information about the
037 *types and properties for each parameter marker in a <code>CallableStatement</code>
038 *object.
039 *
040 * @since 1.4
041 */
042
043 public interface ParameterMetaData extends Wrapper {
044
045 /**
046 * Retrieves the number of parameters in the <code>PreparedStatement</code>
047 * object for which this <code>ParameterMetaData</code> object contains
048 * information.
049 *
050 * @return the number of parameters
051 * @exception SQLException if a database access error occurs
052 * @since 1.4
053 */
054 int getParameterCount() throws SQLException;
055
056 /**
057 * Retrieves whether null values are allowed in the designated parameter.
058 *
059 * @param param the first parameter is 1, the second is 2, ...
060 * @return the nullability status of the given parameter; one of
061 * <code>ParameterMetaData.parameterNoNulls</code>,
062 * <code>ParameterMetaData.parameterNullable</code>, or
063 * <code>ParameterMetaData.parameterNullableUnknown</code>
064 * @exception SQLException if a database access error occurs
065 * @since 1.4
066 */
067 int isNullable(int param) throws SQLException;
068
069 /**
070 * The constant indicating that a
071 * parameter will not allow <code>NULL</code> values.
072 */
073 int parameterNoNulls = 0;
074
075 /**
076 * The constant indicating that a
077 * parameter will allow <code>NULL</code> values.
078 */
079 int parameterNullable = 1;
080
081 /**
082 * The constant indicating that the
083 * nullability of a parameter is unknown.
084 */
085 int parameterNullableUnknown = 2;
086
087 /**
088 * Retrieves whether values for the designated parameter can be signed numbers.
089 *
090 * @param param the first parameter is 1, the second is 2, ...
091 * @return <code>true</code> if so; <code>false</code> otherwise
092 * @exception SQLException if a database access error occurs
093 * @since 1.4
094 */
095 boolean isSigned(int param) throws SQLException;
096
097 /**
098 * Retrieves the designated parameter's specified column size.
099 *
100 * <P>The returned value represents the maximum column size for the given parameter.
101 * For numeric data, this is the maximum precision. For character data, this is the length in characters.
102 * For datetime datatypes, this is the length in characters of the String representation (assuming the
103 * maximum allowed precision of the fractional seconds component). For binary data, this is the length in bytes. For the ROWID datatype,
104 * this is the length in bytes. 0 is returned for data types where the
105 * column size is not applicable.
106 *
107 * @param param the first parameter is 1, the second is 2, ...
108 * @return precision
109 * @exception SQLException if a database access error occurs
110 * @since 1.4
111 */
112 int getPrecision(int param) throws SQLException;
113
114 /**
115 * Retrieves the designated parameter's number of digits to right of the decimal point.
116 * 0 is returned for data types where the scale is not applicable.
117 *
118 * @param param the first parameter is 1, the second is 2, ...
119 * @return scale
120 * @exception SQLException if a database access error occurs
121 * @since 1.4
122 */
123 int getScale(int param) throws SQLException;
124
125 /**
126 * Retrieves the designated parameter's SQL type.
127 *
128 * @param param the first parameter is 1, the second is 2, ...
129 * @return SQL type from <code>java.sql.Types</code>
130 * @exception SQLException if a database access error occurs
131 * @since 1.4
132 * @see Types
133 */
134 int getParameterType(int param) throws SQLException;
135
136 /**
137 * Retrieves the designated parameter's database-specific type name.
138 *
139 * @param param the first parameter is 1, the second is 2, ...
140 * @return type the name used by the database. If the parameter type is
141 * a user-defined type, then a fully-qualified type name is returned.
142 * @exception SQLException if a database access error occurs
143 * @since 1.4
144 */
145 String getParameterTypeName(int param) throws SQLException;
146
147 /**
148 * Retrieves the fully-qualified name of the Java class whose instances
149 * should be passed to the method <code>PreparedStatement.setObject</code>.
150 *
151 * @param param the first parameter is 1, the second is 2, ...
152 * @return the fully-qualified name of the class in the Java programming
153 * language that would be used by the method
154 * <code>PreparedStatement.setObject</code> to set the value
155 * in the specified parameter. This is the class name used
156 * for custom mapping.
157 * @exception SQLException if a database access error occurs
158 * @since 1.4
159 */
160 String getParameterClassName(int param) throws SQLException;
161
162 /**
163 * The constant indicating that the mode of the parameter is unknown.
164 */
165 int parameterModeUnknown = 0;
166
167 /**
168 * The constant indicating that the parameter's mode is IN.
169 */
170 int parameterModeIn = 1;
171
172 /**
173 * The constant indicating that the parameter's mode is INOUT.
174 */
175 int parameterModeInOut = 2;
176
177 /**
178 * The constant indicating that the parameter's mode is OUT.
179 */
180 int parameterModeOut = 4;
181
182 /**
183 * Retrieves the designated parameter's mode.
184 *
185 * @param param the first parameter is 1, the second is 2, ...
186 * @return mode of the parameter; one of
187 * <code>ParameterMetaData.parameterModeIn</code>,
188 * <code>ParameterMetaData.parameterModeOut</code>, or
189 * <code>ParameterMetaData.parameterModeInOut</code>
190 * <code>ParameterMetaData.parameterModeUnknown</code>.
191 * @exception SQLException if a database access error occurs
192 * @since 1.4
193 */
194 int getParameterMode(int param) throws SQLException;
195 }
|