1 |
/* Statement.java -- Interface for executing SQL statements. |
/* Statement.java -- Interface for executing SQL statements. |
2 |
Copyright (C) 1999, 2000 Free Software Foundation, Inc. |
Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc. |
3 |
|
|
4 |
This file is part of GNU Classpath. |
This file is part of GNU Classpath. |
5 |
|
|
39 |
package java.sql; |
package java.sql; |
40 |
|
|
41 |
/** |
/** |
42 |
* This interface provides a mechanism for executing SQL statements. |
* This interface provides a mechanism for executing SQL statements. |
43 |
* |
* |
44 |
* @author Aaron M. Renn (arenn@urbanophile.com) |
* @author Aaron M. Renn (arenn@urbanophile.com) |
45 |
*/ |
*/ |
46 |
public interface Statement |
public interface Statement |
47 |
{ |
{ |
48 |
|
public static final int CLOSE_CURRENT_RESULT = 1; |
49 |
/** |
public static final int KEEP_CURRENT_RESULT = 2; |
50 |
* This method executes the specified SQL SELECT statement and returns a |
public static final int CLOSE_ALL_RESULTS = 3; |
51 |
* (possibly empty) <code>ResultSet</code> with the results of the query. |
public static final int SUCCESS_NO_INFO = -2; |
52 |
* |
public static final int EXECUTE_FAILED = -3; |
53 |
* @param sql The SQL statement to execute. |
public static final int RETURN_GENERATED_KEYS = 1; |
54 |
* |
public static final int NO_GENERATED_KEYS = 2; |
55 |
* @return The result set of the SQL statement. |
|
56 |
* |
/** |
57 |
* @exception SQLException If an error occurs. |
* This method executes the specified SQL SELECT statement and returns a |
58 |
*/ |
* (possibly empty) <code>ResultSet</code> with the results of the query. |
59 |
public abstract ResultSet |
* |
60 |
executeQuery(String sql) throws SQLException; |
* @param sql The SQL statement to execute. |
61 |
|
* @return The result set of the SQL statement. |
62 |
/*************************************************************************/ |
* @exception SQLException If an error occurs. |
63 |
|
*/ |
64 |
/** |
public ResultSet executeQuery(String sql) throws SQLException; |
65 |
* This method executes the specified SQL INSERT, UPDATE, or DELETE statement |
|
66 |
* and returns the number of rows affected, which may be 0. |
/** |
67 |
* |
* This method executes the specified SQL INSERT, UPDATE, or DELETE statement |
68 |
* @param sql The SQL statement to execute. |
* and returns the number of rows affected, which may be 0. |
69 |
* |
* |
70 |
* @return The number of rows affected by the SQL statement. |
* @param sql The SQL statement to execute. |
71 |
* |
* @return The number of rows affected by the SQL statement. |
72 |
* @exception SQLException If an error occurs. |
* @exception SQLException If an error occurs. |
73 |
*/ |
*/ |
74 |
public abstract int |
public int executeUpdate(String sql) throws SQLException; |
75 |
executeUpdate(String sql) throws SQLException; |
|
76 |
|
/** |
77 |
/*************************************************************************/ |
* This method closes the statement and frees any associated resources. |
78 |
|
* |
79 |
/** |
* @exception SQLException If an error occurs. |
80 |
* This method closes the statement and frees any associated resources. |
*/ |
81 |
* |
public void close() throws SQLException; |
82 |
* @exception SQLException If an error occurs. |
|
83 |
*/ |
/** |
84 |
public abstract void |
* This method returns the maximum length of any column value in bytes. |
85 |
close() throws SQLException; |
* |
86 |
|
* @return The maximum length of any column value in bytes. |
87 |
/*************************************************************************/ |
* @exception SQLException If an error occurs. |
88 |
|
*/ |
89 |
/** |
public int getMaxFieldSize() throws SQLException; |
90 |
* This method returns the maximum length of any column value in bytes. |
|
91 |
* |
/** |
92 |
* @return The maximum length of any column value in bytes. |
* This method sets the limit for the maximum length of any column in bytes. |
93 |
* |
* |
94 |
* @exception SQLException If an error occurs. |
* @param maxsize The new maximum length of any column in bytes. |
95 |
*/ |
* @exception SQLException If an error occurs. |
96 |
public abstract int |
*/ |
97 |
getMaxFieldSize() throws SQLException; |
public void setMaxFieldSize(int max) throws SQLException; |
98 |
|
|
99 |
/*************************************************************************/ |
/** |
100 |
|
* This method returns the maximum possible number of rows in a result set. |
101 |
/** |
* |
102 |
* This method sets the limit for the maximum length of any column in bytes. |
* @return The maximum possible number of rows in a result set. |
103 |
* |
* @exception SQLException If an error occurs. |
104 |
* @param maxsize The new maximum length of any column in bytes. |
*/ |
105 |
* |
public int getMaxRows() throws SQLException; |
106 |
* @exception SQLException If an error occurs. |
|
107 |
*/ |
/** |
108 |
public abstract void |
* This method sets the maximum number of rows that can be present in a |
109 |
setMaxFieldSize(int maxsize) throws SQLException; |
* result set. |
110 |
|
* |
111 |
/*************************************************************************/ |
* @param maxrows The maximum possible number of rows in a result set. |
112 |
|
* @exception SQLException If an error occurs. |
113 |
/** |
*/ |
114 |
* This method returns the maximum possible number of rows in a result set. |
public void setMaxRows(int max) throws SQLException; |
115 |
* |
|
116 |
* @return The maximum possible number of rows in a result set. |
/** |
117 |
* |
* This method sets the local escape processing mode on or off. The |
118 |
* @exception SQLException If an error occurs. |
* default value is on. |
119 |
*/ |
* |
120 |
public abstract int |
* @param escape <code>true</code> to enable local escape processing, |
121 |
getMaxRows() throws SQLException; |
* <code>false</code> to disable it. |
122 |
|
* @exception SQLException If an error occurs. |
123 |
/*************************************************************************/ |
*/ |
124 |
|
public void setEscapeProcessing(boolean enable) throws SQLException; |
125 |
/** |
|
126 |
* This method sets the maximum number of rows that can be present in a |
/** |
127 |
* result set. |
* The method returns the number of seconds a statement may be in process |
128 |
* |
* before timing out. A value of 0 means there is no timeout. |
129 |
* @param maxrows The maximum possible number of rows in a result set. |
* |
130 |
* |
* @return The SQL statement timeout in seconds. |
131 |
* @exception SQLException If an error occurs. |
* @exception SQLException If an error occurs. |
132 |
*/ |
*/ |
133 |
public abstract void |
public int getQueryTimeout() throws SQLException; |
134 |
setMaxRows(int maxrows) throws SQLException; |
|
135 |
|
/** |
136 |
/*************************************************************************/ |
* This method sets the number of seconds a statement may be in process |
137 |
|
* before timing out. A value of 0 means there is no timeout. |
138 |
/** |
* |
139 |
* This method sets the local escape processing mode on or off. The |
* @param timeout The new SQL statement timeout value. |
140 |
* default value is on. |
* @exception SQLException If an error occurs. |
141 |
* |
*/ |
142 |
* @param escape <code>true</code> to enable local escape processing, |
public void setQueryTimeout(int seconds) throws SQLException; |
143 |
* <code>false</code> to disable it. |
|
144 |
* |
/** |
145 |
* @exception SQLException If an error occurs. |
* This method cancels an outstanding statement, if the database supports |
146 |
*/ |
* that operation. |
147 |
public abstract void |
* |
148 |
setEscapeProcessing(boolean esacpe) throws SQLException; |
* @exception SQLException If an error occurs. |
149 |
|
*/ |
150 |
/*************************************************************************/ |
public void cancel() throws SQLException; |
151 |
|
|
152 |
/** |
/** |
153 |
* The method returns the number of seconds a statement may be in process |
* This method returns the first SQL warning attached to this statement. |
154 |
* before timing out. A value of 0 means there is no timeout. |
* Subsequent warnings will be chained to this one. |
155 |
* |
* |
156 |
* @return The SQL statement timeout in seconds. |
* @return The first SQL warning for this statement. |
157 |
* |
* @exception SQLException If an error occurs. |
158 |
* @exception SQLException If an error occurs. |
*/ |
159 |
*/ |
public SQLWarning getWarnings() throws SQLException; |
160 |
public abstract int |
|
161 |
getQueryTimeout() throws SQLException; |
/** |
162 |
|
* This method clears any SQL warnings that have been attached to this |
163 |
/*************************************************************************/ |
* statement. |
164 |
|
* |
165 |
/** |
* @exception SQLException If an error occurs. |
166 |
* This method sets the number of seconds a statement may be in process |
*/ |
167 |
* before timing out. A value of 0 means there is no timeout. |
public void clearWarnings() throws SQLException; |
168 |
* |
|
169 |
* @param timeout The new SQL statement timeout value. |
/** |
170 |
* |
* This method sets the cursor name that will be used by the result set. |
171 |
* @exception SQLException If an error occurs. |
* |
172 |
*/ |
* @param name The cursor name to use for this statement. |
173 |
public abstract void |
* @exception SQLException If an error occurs. |
174 |
setQueryTimeout(int timeout) throws SQLException; |
*/ |
175 |
|
public void setCursorName(String name) throws SQLException; |
176 |
/*************************************************************************/ |
|
177 |
|
/** |
178 |
/** |
* This method executes an arbitrary SQL statement of any time. The |
179 |
* This method cancels an outstanding statement, if the database supports |
* methods <code>getResultSet</code>, <code>getMoreResults</code> and |
180 |
* that operation. |
* <code>getUpdateCount</code> retrieve the results. |
181 |
* |
* |
182 |
* @exception SQLException If an error occurs. |
* @return <code>true</code> if a result set was returned, <code>false</code> |
183 |
*/ |
* if an update count was returned. |
184 |
public abstract void |
* @exception SQLException If an error occurs. |
185 |
cancel() throws SQLException; |
*/ |
186 |
|
public boolean execute(String sql) throws SQLException; |
187 |
/*************************************************************************/ |
|
188 |
|
/** |
189 |
/** |
* This method returns the result set of the SQL statement that was |
190 |
* This method returns the first SQL warning attached to this statement. |
* executed. This should be called only once per result set returned. |
191 |
* Subsequent warnings will be chained to this one. |
* |
192 |
* |
* @return The result set of the query, or <code>null</code> if there was |
193 |
* @return The first SQL warning for this statement. |
* no result set (for example, if the statement was an UPDATE). |
194 |
* |
* @exception SQLException If an error occurs. |
195 |
* @exception SQLException If an error occurs. |
* @see execute |
196 |
*/ |
*/ |
197 |
public abstract SQLWarning |
public ResultSet getResultSet() throws SQLException; |
198 |
getWarnings() throws SQLException; |
|
199 |
|
/** |
200 |
/*************************************************************************/ |
* This method returns the update count of the SQL statement that was |
201 |
|
* executed. This should be called only once per executed SQL statement. |
202 |
/** |
* |
203 |
* This method clears any SQL warnings that have been attached to this |
* @return The update count of the query, or -1 if there was no update |
204 |
* statement. |
* count (for example, if the statement was a SELECT). |
205 |
* |
* @exception SQLException If an error occurs. |
206 |
* @exception SQLException If an error occurs. |
* @see execute |
207 |
*/ |
*/ |
208 |
public abstract void |
public int getUpdateCount() throws SQLException; |
209 |
clearWarnings() throws SQLException; |
|
210 |
|
/** |
211 |
/*************************************************************************/ |
* This method advances the result set pointer to the next result set, |
212 |
|
* which can then be retrieved using <code>getResultSet</code> |
213 |
/** |
* |
214 |
* This method sets the cursor name that will be used by the result set. |
* @return <code>true</code> if there is another result set, |
215 |
* |
* <code>false</code> otherwise (for example, the next result is an |
216 |
* @param name The cursor name to use for this statement. |
* update count). |
217 |
* |
* @exception SQLException If an error occurs. |
218 |
* @exception SQLException If an error occurs. |
* @see execute |
219 |
*/ |
*/ |
220 |
public abstract void |
public boolean getMoreResults() throws SQLException; |
221 |
setCursorName(String name) throws SQLException; |
|
222 |
|
/** |
223 |
/*************************************************************************/ |
* This method informs the driver which direction the result set will |
224 |
|
* be accessed in. |
225 |
/** |
* |
226 |
* This method executes an arbitrary SQL statement of any time. The |
* @param direction The direction the result set will be accessed in (?????) |
227 |
* methods <code>getResultSet</code>, <code>getMoreResults</code> and |
* @exception SQLException If an error occurs. |
228 |
* <code>getUpdateCount</code> retrieve the results. |
*/ |
229 |
* |
public void setFetchDirection(int direction) throws SQLException; |
230 |
* @return <code>true</code> if a result set was returned, <code>false</code> |
|
231 |
* if an update count was returned. |
/** |
232 |
* |
* This method returns the current direction that the driver thinks the |
233 |
* @exception SQLException If an error occurs. |
* result set will be accessed int. |
234 |
*/ |
* |
235 |
public abstract boolean |
* @return The direction the result set will be accessed in (????) |
236 |
execute(String sql) throws SQLException; |
* @exception SQLException If an error occurs. |
237 |
|
*/ |
238 |
/*************************************************************************/ |
public int getFetchDirection() throws SQLException; |
239 |
|
|
240 |
/** |
/** |
241 |
* This method returns the result set of the SQL statement that was |
* This method informs the driver how many rows it should fetch from the |
242 |
* executed. This should be called only once per result set returned. |
* database at a time. |
243 |
* |
* |
244 |
* @return The result set of the query, or <code>null</code> if there was |
* @param numrows The number of rows the driver should fetch at a time |
245 |
* no result set (for example, if the statement was an UPDATE). |
* to populate the result set. |
246 |
* |
* @exception SQLException If an error occurs. |
247 |
* @exception SQLException If an error occurs. |
*/ |
248 |
* |
public void setFetchSize(int rows) throws SQLException; |
249 |
* @see execute |
|
250 |
*/ |
/** |
251 |
public abstract ResultSet |
* This method returns the number of rows the driver believes should be |
252 |
getResultSet() throws SQLException; |
* fetched from the database at a time. |
253 |
|
* |
254 |
/*************************************************************************/ |
* @return The number of rows that will be fetched from the database at a time. |
255 |
|
* @exception SQLException If an error occurs. |
256 |
/** |
*/ |
257 |
* This method returns the update count of the SQL statement that was |
public int getFetchSize() throws SQLException; |
258 |
* executed. This should be called only once per executed SQL statement. |
|
259 |
* |
/** |
260 |
* @return The update count of the query, or -1 if there was no update |
* This method returns the concurrency type of the result set for this |
261 |
* count (for example, if the statement was a SELECT). |
* statement. This will be one of the concurrency types defined in |
262 |
* |
* <code>ResultSet</code>. |
263 |
* @exception SQLException If an error occurs. |
* |
264 |
* |
* @return The concurrency type of the result set for this statement. |
265 |
* @see execute |
* @exception SQLException If an error occurs. |
266 |
*/ |
* @see ResultSet |
267 |
public abstract int |
*/ |
268 |
getUpdateCount() throws SQLException; |
public int getResultSetConcurrency() throws SQLException; |
269 |
|
|
270 |
/*************************************************************************/ |
/** |
271 |
|
* This method returns the result set type for this statement. This will |
272 |
/** |
* be one of the result set types defined in <code>ResultSet</code>. |
273 |
* This method advances the result set pointer to the next result set, |
* |
274 |
* which can then be retrieved using <code>getResultSet</code> |
* @return The result set type for this statement. |
275 |
* |
* @exception SQLException If an error occurs. |
276 |
* @return <code>true</code> if there is another result set, |
* @see ResultSet |
277 |
* <code>false</code> otherwise (for example, the next result is an |
*/ |
278 |
* update count). |
public int getResultSetType() throws SQLException; |
279 |
* |
|
280 |
* @exception SQLException If an error occurs. |
/** |
281 |
* |
* This method adds a SQL statement to a SQL batch. A driver is not |
282 |
* @see execute |
* required to implement this method. |
283 |
*/ |
* |
284 |
public abstract boolean |
* @param sql The sql statement to add to the batch. |
285 |
getMoreResults() throws SQLException; |
* @exception SQLException If an error occurs. |
286 |
|
*/ |
287 |
/*************************************************************************/ |
public void addBatch(String sql) throws SQLException; |
288 |
|
|
289 |
/** |
/** |
290 |
* This method returns the current direction that the driver thinks the |
* This method clears out any SQL statements that have been populated in |
291 |
* result set will be accessed int. |
* the current batch. A driver is not required to implement this method. |
292 |
* |
* |
293 |
* @return The direction the result set will be accessed in (????) |
* @exception SQLException If an error occurs. |
294 |
* |
*/ |
295 |
* @exception SQLException If an error occurs. |
public void clearBatch() throws SQLException; |
296 |
*/ |
|
297 |
public abstract int |
/** |
298 |
getFetchDirection() throws SQLException; |
* This method executes the SQL batch and returns an array of update |
299 |
|
* counts - one for each SQL statement in the batch - ordered in the same |
300 |
/*************************************************************************/ |
* order the statements were added to the batch. A driver is not required |
301 |
|
* to implement this method. |
302 |
/** |
* |
303 |
* This method informs the driver which direction the result set will |
* @return An array of update counts for this batch. |
304 |
* be accessed in. |
* @exception SQLException If an error occurs. |
305 |
* |
*/ |
306 |
* @param direction The direction the result set will be accessed in (?????) |
public int[] executeBatch() throws SQLException; |
307 |
* |
|
308 |
* @exception SQLException If an error occurs. |
/** |
309 |
*/ |
* This method returns the <code>Connection</code> instance that was |
310 |
public abstract void |
* used to create this object. |
311 |
setFetchDirection(int direction) throws SQLException; |
* |
312 |
|
* @return The connection used to create this object. |
313 |
/*************************************************************************/ |
* @exception SQLException If an error occurs. |
314 |
|
*/ |
315 |
/** |
public Connection getConnection() throws SQLException; |
316 |
* This method returns the number of rows the driver believes should be |
|
317 |
* fetched from the database at a time. |
/** |
318 |
* |
* @since 1.4 |
319 |
* @return The number of rows that will be fetched from the database at a time. |
*/ |
320 |
* |
public boolean getMoreResults(int current) throws SQLException; |
321 |
* @exception SQLException If an error occurs. |
|
322 |
*/ |
/** |
323 |
public abstract int |
* @since 1.4 |
324 |
getFetchSize() throws SQLException; |
*/ |
325 |
|
public ResultSet getGeneratedKeys() throws SQLException; |
326 |
/*************************************************************************/ |
|
327 |
|
/** |
328 |
/** |
* @since 1.4 |
329 |
* This method informs the driver how many rows it should fetch from the |
*/ |
330 |
* database at a time. |
public int executeUpdate(String sql, int autoGeneratedKeys) |
331 |
* |
throws SQLException; |
332 |
* @param numrows The number of rows the driver should fetch at a time |
|
333 |
* to populate the result set. |
/** |
334 |
* |
* @since 1.4 |
335 |
* @exception SQLException If an error occurs. |
*/ |
336 |
*/ |
public int executeUpdate(String sql, int[] columnIndexes) |
337 |
public abstract void |
throws SQLException; |
338 |
setFetchSize(int numrows) throws SQLException; |
|
339 |
|
/** |
340 |
/*************************************************************************/ |
* @since 1.4 |
341 |
|
*/ |
342 |
/** |
public int executeUpdate(String sql, String[] columnNames) |
343 |
* This method returns the concurrency type of the result set for this |
throws SQLException; |
344 |
* statement. This will be one of the concurrency types defined in |
|
345 |
* <code>ResultSet</code>. |
/** |
346 |
* |
* @since 1.4 |
347 |
* @return The concurrency type of the result set for this statement. |
*/ |
348 |
* |
public boolean execute(String sql, int autoGeneratedKeys) |
349 |
* @exception SQLException If an error occurs. |
throws SQLException; |
350 |
* |
|
351 |
* @see ResultSet |
/** |
352 |
*/ |
* @since 1.4 |
353 |
public abstract int |
*/ |
354 |
getResultSetConcurrency() throws SQLException; |
public boolean execute(String sql, int[] columnIndexes) throws SQLException; |
355 |
|
|
356 |
/*************************************************************************/ |
/** |
357 |
|
* @since 1.4 |
358 |
/** |
*/ |
359 |
* This method returns the result set type for this statement. This will |
public boolean execute(String sql, String[] columnNames) |
360 |
* be one of the result set types defined in <code>ResultSet</code>. |
throws SQLException; |
361 |
* |
|
362 |
* @return The result set type for this statement. |
/** |
363 |
* |
* @since 1.4 |
364 |
* @exception SQLException If an error occurs. |
*/ |
365 |
* |
public int getResultSetHoldability() throws SQLException; |
366 |
* @see ResultSet |
} |
|
*/ |
|
|
public abstract int |
|
|
getResultSetType() throws SQLException; |
|
|
|
|
|
/*************************************************************************/ |
|
|
|
|
|
/** |
|
|
* This method adds a SQL statement to a SQL batch. A driver is not |
|
|
* required to implement this method. |
|
|
* |
|
|
* @param sql The sql statement to add to the batch. |
|
|
* |
|
|
* @exception SQLException If an error occurs. |
|
|
*/ |
|
|
public abstract void |
|
|
addBatch(String sql) throws SQLException; |
|
|
|
|
|
/*************************************************************************/ |
|
|
|
|
|
/** |
|
|
* This method clears out any SQL statements that have been populated in |
|
|
* the current batch. A driver is not required to implement this method. |
|
|
* |
|
|
* @exception SQLException If an error occurs. |
|
|
*/ |
|
|
public abstract void |
|
|
clearBatch() throws SQLException; |
|
|
|
|
|
/*************************************************************************/ |
|
|
|
|
|
/** |
|
|
* This method executes the SQL batch and returns an array of update |
|
|
* counts - one for each SQL statement in the batch - ordered in the same |
|
|
* order the statements were added to the batch. A driver is not required |
|
|
* to implement this method. |
|
|
* |
|
|
* @return An array of update counts for this batch. |
|
|
* |
|
|
* @exception SQLException If an error occurs. |
|
|
*/ |
|
|
public abstract int[] |
|
|
executeBatch() throws SQLException; |
|
|
|
|
|
/*************************************************************************/ |
|
|
|
|
|
/** |
|
|
* This method returns the <code>Connection</code> instance that was |
|
|
* used to create this object. |
|
|
* |
|
|
* @return The connection used to create this object. |
|
|
* |
|
|
* @exception SQLException If an error occurs. |
|
|
*/ |
|
|
public abstract Connection |
|
|
getConnection() throws SQLException; |
|
|
|
|
|
} // interface Statement |
|
|
|
|