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 javax.sql;
19
20import java.sql.ResultSetMetaData;
21import java.sql.SQLException;
22
23/**
24 * An interface which provides facilities for getting information about the
25 * columns in a {@code RowSet}.
26 * <p>
27 * {@code RowSetMetaData} extends {@link java.sql.ResultSetMetaData}, adding new
28 * operations for carrying out value sets.
29 * <p>
30 * Application code would not normally call this interface directly. It would be
31 * called internally when {@code RowSet.execute} is called.
32 *
33 * @see RowSetInternal#setMetaData(RowSetMetaData)
34 */
35public interface RowSetMetaData extends ResultSetMetaData {
36
37    /**
38     * Sets automatic numbering for a specified column in the {@code RowSet}. If
39     * automatic numbering is on, the column is read-only. The default value for
40     * the auto increment parameter is {@code false}.
41     *
42     * @param columnIndex
43     *            the index number for the column; the first column's index is
44     *            1.
45     * @param autoIncrement
46     *            {@code true} to set automatic numbering on, {@code false} to
47     *            turn it off (default).
48     * @throws SQLException
49     *             if a problem occurs accessing the database.
50     */
51    public void setAutoIncrement(int columnIndex, boolean autoIncrement)
52            throws SQLException;
53
54    /**
55     * Sets the case sensitive property for a specified column in the {@code
56     * RowSet}. The default is that the column is not case sensitive.
57     *
58     * @param columnIndex
59     *            the index number for the column; the first column's index is
60     *            1.
61     * @param caseSensitive
62     *            {@code true} to make the column case sensitive, {@code false}
63     *            to make it case insensitive (default).
64     * @throws SQLException
65     *             if a problem occurs accessing the database.
66     */
67    public void setCaseSensitive(int columnIndex, boolean caseSensitive)
68            throws SQLException;
69
70    /**
71     * Sets the catalog name for a specified column in the {@code RowSet}.
72     *
73     * @param columnIndex
74     *            the index number for the column; the first column's index is
75     *            1.
76     * @param catalogName
77     *            the new catalog's name.
78     * @throws SQLException
79     *             if a problem occurs accessing the database.
80     */
81    public void setCatalogName(int columnIndex, String catalogName)
82            throws SQLException;
83
84    /**
85     * Sets the number of columns contained in the row set.
86     *
87     * @param columnCount
88     *            the number of columns contained in the {@code RowSet}.
89     * @throws SQLException
90     *             if a problem occurs accessing the database.
91     */
92    public void setColumnCount(int columnCount) throws SQLException;
93
94    /**
95     * Sets the normal maximum width in characters for a specified column in the
96     * {@code RowSet}.
97     *
98     * @param columnIndex
99     *            the index number for the column; the first column's index is
100     *            1.
101     * @param displaySize
102     *            the normal maximum column width in characters.
103     * @throws SQLException
104     *             if a problem occurs accessing the database.
105     */
106    public void setColumnDisplaySize(int columnIndex, int displaySize)
107            throws SQLException;
108
109    /**
110     * Sets the suggested name as label for the column contained in the {@code
111     * RowSet}. The label is an alias for printing and displaying purposes.
112     *
113     * @param columnIndex
114     *            the index number for the column; the first column's index is
115     *            1.
116     * @param theLabel
117     *            the alias name for the column.
118     * @throws SQLException
119     *             if a problem occurs accessing the database.
120     */
121    public void setColumnLabel(int columnIndex, String theLabel)
122            throws SQLException;
123
124    /**
125     * Sets the column name for a specified column in the {@code RowSet}.
126     *
127     * @param columnIndex
128     *            the index number for the column; the first column's index is
129     *            1.
130     * @param theColumnName
131     *            the column's label.
132     * @throws SQLException
133     *             if a problem occurs accessing the database.
134     */
135    public void setColumnName(int columnIndex, String theColumnName)
136            throws SQLException;
137
138    /**
139     * Sets the SQL type for a specified column in the {@code RowSet}.
140     *
141     * @param columnIndex
142     *            the index number for the column; the first column's index is
143     *            1.
144     * @param theSQLType
145     *            the SQL Type, as defined by {@code java.sql.Types}.
146     * @throws SQLException
147     *             if a problem occurs accessing the database.
148     */
149    public void setColumnType(int columnIndex, int theSQLType)
150            throws SQLException;
151
152    /**
153     * Sets the type name for a specified column in the {@code RowSet}, where
154     * the data type is specific to the data source.
155     *
156     * @param columnIndex
157     *            the index number for the column; the first column's index is
158     *            1.
159     * @param theTypeName
160     *            the SQL type name for the column.
161     * @throws SQLException
162     *             if a problem occurs accessing the database.
163     */
164    public void setColumnTypeName(int columnIndex, String theTypeName)
165            throws SQLException;
166
167    /**
168     * Sets whether a specified column is a currency value. The default value is
169     * {@code false}.
170     *
171     * @param columnIndex
172     *            the index number for the column; the first column's index is
173     *            1.
174     * @param isCurrency
175     *            {@code true} if the column should be treated as a currency
176     *            value, {@code false} if it should not be treated as a currency
177     *            value (default).
178     * @throws SQLException
179     *             if a problem occurs accessing the database.
180     */
181    public void setCurrency(int columnIndex, boolean isCurrency)
182            throws SQLException;
183
184    /**
185     * Sets whether a specified column can contain SQL {@code NULL} values.
186     *
187     * @param columnIndex
188     *            the index number for the column; the first column's index is
189     *            1.
190     * @param nullability
191     *            an integer which is one of the following values:
192     *            <ul>
193     *            <li>{@code ResultSetMetaData.columnNoNulls}</li>
194     *            <li>{@code ResultSetMetaData.columnNullable}</li>
195     *            <li>{@code ResultSetMetaData.columnNullableUnknown}</li>
196     *            </ul>
197     *            <p>
198     *            The default value is {@code
199     *            ResultSetMetaData.columnNullableUnknown}.
200     * @throws SQLException
201     *             if a problem occurs accessing the database.
202     */
203    public void setNullable(int columnIndex, int nullability)
204            throws SQLException;
205
206    /**
207     * Sets the number of decimal digits for a specified column in the {@code
208     * RowSet}.
209     *
210     * @param columnIndex
211     *            the index number for the column; the first column's index is
212     *            1.
213     * @param thePrecision
214     *            the number of decimal digits.
215     * @throws SQLException
216     *             if a problem occurs accessing the database.
217     */
218    public void setPrecision(int columnIndex, int thePrecision)
219            throws SQLException;
220
221    /**
222     * Declares how many decimal digits there should be after a decimal point
223     * for the column specified by {@code columnIndex}.
224     *
225     * @param columnIndex
226     *            the index number for the column; the first column's index is
227     *            1.
228     * @param theScale
229     *            the number of digits after the decimal point.
230     * @throws SQLException
231     *             if a problem occurs accessing the database.
232     */
233    public void setScale(int columnIndex, int theScale) throws SQLException;
234
235    /**
236     * Sets the schema name for a specified column in the {@code RowSet}.
237     *
238     * @param columnIndex
239     *            the index number for the column; the first column's index is
240     *            1.
241     * @param theSchemaName
242     *            a {@code String} containing the schema name.
243     * @throws SQLException
244     *             if a problem occurs accessing the database.
245     */
246    public void setSchemaName(int columnIndex, String theSchemaName)
247            throws SQLException;
248
249    /**
250     * Sets whether a specified column can be used in a search involving a
251     * {@code WHERE} clause. The default value is {@code false}.
252     *
253     * @param columnIndex
254     *            the index number for the column; the first column's index is
255     *            1.
256     * @param isSearchable
257     *            {@code true} of the column can be used in a {@code WHERE}
258     *            clause search, {@code false} otherwise.
259     * @throws SQLException
260     *             if a problem occurs accessing the database.
261     */
262    public void setSearchable(int columnIndex, boolean isSearchable)
263            throws SQLException;
264
265    /**
266     * Sets if a specified column can contain signed numbers.
267     *
268     * @param columnIndex
269     *            the index number for the column; the first column's index is
270     *            1.
271     * @param isSigned
272     *            {@code true} if the column can contain signed numbers, {@code
273     *            false} otherwise.
274     * @throws SQLException
275     *             if a problem occurs accessing the database.
276     */
277    public void setSigned(int columnIndex, boolean isSigned)
278            throws SQLException;
279
280    /**
281     * Sets the table name for a specified column in the {@code RowSet}.
282     *
283     * @param columnIndex
284     *            the index number for the column; the first column's index is
285     *            1.
286     * @param theTableName
287     *            the table name for the column.
288     * @throws SQLException
289     *             if a problem occurs accessing the database.
290     */
291    public void setTableName(int columnIndex, String theTableName)
292            throws SQLException;
293}
294