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 
18 package java.sql;
19 
20 /**
21  * An interface used to get information about the types and properties of
22  * parameters in a {@code PreparedStatement}.
23  */
24 public 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      */
getParameterClassName(int paramIndex)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      */
getParameterCount()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      */
getParameterMode(int paramIndex)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      */
getParameterType(int paramIndex)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      */
getParameterTypeName(int paramIndex)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      */
getPrecision(int paramIndex)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      */
getScale(int paramIndex)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      */
isNullable(int paramIndex)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      */
isSigned(int paramIndex)188     public boolean isSigned(int paramIndex) throws SQLException;
189 }
190