1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.sql;
19
20/**
21 * An interface used to get information about the types and properties of
22 * parameters in a {@code PreparedStatement}.
23 */
24public interface ParameterMetaData extends Wrapper {
25
26    /**
27     * Indicates that the parameter mode is {@code IN}.
28     */
29    public static final int parameterModeIn = 1;
30
31    /**
32     * Indicates that the parameter mode is {@code INOUT}.
33     */
34    public static final int parameterModeInOut = 2;
35
36    /**
37     * Indicates that the parameter mode is {@code OUT}.
38     */
39    public static final int parameterModeOut = 4;
40
41    /**
42     * Indicates that the parameter mode is not known.
43     */
44    public static final int parameterModeUnknown = 0;
45
46    /**
47     * Indicates that a parameter is not permitted to be {@code NULL}.
48     */
49    public static final int parameterNoNulls = 0;
50
51    /**
52     * Indicates that a parameter is permitted to be {@code NULL}.
53     */
54    public static final int parameterNullable = 1;
55
56    /**
57     * Indicates that whether a parameter is allowed to be {@code null} or not
58     * is not known.
59     */
60    public static final int parameterNullableUnknown = 2;
61
62    /**
63     * Gets the fully-qualified name of the Java class which should be passed as
64     * a parameter to the method {@code PreparedStatement.setObject}.
65     *
66     * @param paramIndex
67     *            the index number of the parameter, where the first parameter
68     *            has index 1.
69     * @return the fully qualified Java class name of the parameter with the
70     *         specified index. This class name is used for custom mapping
71     *         between SQL types and Java objects.
72     * @throws SQLException
73     *             if a database error happens.
74     */
75    public String getParameterClassName(int paramIndex) throws SQLException;
76
77    /**
78     * Gets the number of parameters in the {@code PreparedStatement} for which
79     * this {@code ParameterMetaData} contains information.
80     *
81     * @return the number of parameters.
82     * @throws SQLException
83     *             if a database error happens.
84     */
85    public int getParameterCount() throws SQLException;
86
87    /**
88     * Gets the mode of the specified parameter. Can be one of:
89     * <ul>
90     * <li>ParameterMetaData.parameterModeIn</li>
91     * <li>ParameterMetaData.parameterModeOut</li>
92     * <li>ParameterMetaData.parameterModeInOut</li>
93     * <li>ParameterMetaData.parameterModeUnknown</li>
94     * </ul>
95     *
96     * @param paramIndex
97     *            the index number of the parameter, where the first parameter
98     *            has index 1.
99     * @return the parameter's mode.
100     * @throws SQLException
101     *             if a database error happens.
102     */
103    public int getParameterMode(int paramIndex) throws SQLException;
104
105    /**
106     * Gets the SQL type of a specified parameter.
107     *
108     * @param paramIndex
109     *            the index number of the parameter, where the first parameter
110     *            has index 1.
111     * @return the SQL type of the parameter as defined in {@code
112     *         java.sql.Types}.
113     * @throws SQLException
114     *             if a database error happens.
115     */
116    public int getParameterType(int paramIndex) throws SQLException;
117
118    /**
119     * Gets the database-specific type name of a specified parameter.
120     *
121     * @param paramIndex
122     *            the index number of the parameter, where the first parameter
123     *            has index 1.
124     * @return the type name for the parameter as used by the database. A
125     *         fully-qualified name is returned if the parameter is a <i>User
126     *         Defined Type</i> (UDT).
127     * @throws SQLException
128     *             if a database error happens.
129     */
130    public String getParameterTypeName(int paramIndex) throws SQLException;
131
132    /**
133     * Gets the number of decimal digits for a specified parameter.
134     *
135     * @param paramIndex
136     *            the index number of the parameter, where the first parameter
137     *            has index 1.
138     * @return the number of decimal digits ("the precision") for the parameter.
139     *         {@code 0} if the parameter is not a numeric type.
140     * @throws SQLException
141     *             if a database error happens.
142     */
143    public int getPrecision(int paramIndex) throws SQLException;
144
145    /**
146     * Gets the number of digits after the decimal point for a specified
147     * parameter.
148     *
149     * @param paramIndex
150     *            the index number of the parameter, where the first parameter
151     *            has index 1.
152     * @return the number of digits after the decimal point ("the scale") for
153     *         the parameter. {@code 0} if the parameter is not a numeric type.
154     * @throws SQLException
155     *             if a database error happens.
156     */
157    public int getScale(int paramIndex) throws SQLException;
158
159    /**
160     * Gets whether {@code null} values are allowed for the specified parameter.
161     * The returned value is one of:
162     * <ul>
163     * <li>ParameterMetaData.parameterNoNulls</li>
164     * <li>ParameterMetaData.parameterNullable</li>
165     * <li>ParameterMetaData.parameterNullableUnknown</li>
166     * </ul>
167     *
168     * @param paramIndex
169     *            the index number of the parameter, where the first parameter
170     *            has index 1.
171     * @return the int code indicating the nullability of the parameter.
172     * @throws SQLException
173     *             if a database error is encountered.
174     */
175    public int isNullable(int paramIndex) throws SQLException;
176
177    /**
178     * Gets whether values for the specified parameter can be signed numbers.
179     *
180     * @param paramIndex
181     *            the index number of the parameter, where the first parameter
182     *            has index 1.
183     * @return {@code true} if values can be signed numbers for this parameter,
184     *         {@code false} otherwise.
185     * @throws SQLException
186     *             if a database error happens.
187     */
188    public boolean isSigned(int paramIndex) throws SQLException;
189}
190