001/* Connection.java -- Manage a database connection.
002   Copyright (C) 1999, 2000, 2002, 2006 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.sql;
040
041import java.util.Map;
042
043/**
044 * This interface provides methods for managing a connection to a database.
045 *
046 * @author Aaron M. Renn (arenn@urbanophile.com)
047 */
048public interface Connection
049  extends AutoCloseable
050{
051  /**
052   * This transaction isolation level indicates that transactions are not
053   * supported.
054   */
055  int TRANSACTION_NONE = 0;
056
057  /**
058   * This transaction isolation level indicates that one transaction can
059   * read modifications by other transactions before the other transactions
060   * have committed their changes.  This could result in invalid reads.
061   */
062  int TRANSACTION_READ_UNCOMMITTED = 1;
063
064  /**
065   * This transaction isolation level indicates that only committed data from
066   * other transactions will be read.  If a transaction reads a row, then
067   * another transaction commits a change to that row, the first transaction
068   * would retrieve the changed row on subsequent reads of the same row.
069   */
070  int TRANSACTION_READ_COMMITTED = 2;
071
072  /**
073   * This transaction isolation level indicates that only committed data from
074   * other transactions will be read.  It also ensures that data read from
075   * a row will not be different on a subsequent read even if another
076   * transaction commits a change.
077   */
078  int TRANSACTION_REPEATABLE_READ = 4;
079
080  /**
081   * This transaction isolation level indicates that only committed data from
082   * other transactions will be read.  It also ensures that data read from
083   * a row will not be different on a subsequent read even if another
084   * transaction commits a change.  Additionally, rows modified by other
085   * transactions will not affect the result set returned during subsequent
086   * executions of the same WHERE clause in this transaction.
087   */
088  int TRANSACTION_SERIALIZABLE = 8;
089
090  /**
091   * This method creates a new SQL statement.  The default result set type
092   * and concurrency will be used.
093   *
094   * @return A new <code>Statement</code> object.
095   * @exception SQLException If an error occurs.
096   * @see Statement
097   */
098  Statement createStatement() throws SQLException;
099
100  /**
101   * This method creates a new <code>PreparedStatement</code> for the specified
102   * SQL string.  This method is designed for use with parameterized
103   * statements.  The default result set type and concurrency will be used.
104   *
105   * @param sql The SQL statement to use in creating this
106   *            <code>PreparedStatement</code>.
107   * @return A new <code>PreparedStatement</code>.
108   * @exception SQLException If an error occurs.
109   * @see PreparedStatement
110   */
111  PreparedStatement prepareStatement(String sql) throws SQLException;
112
113  /**
114   * This method creates a new <code>CallableStatement</code> for the
115   * specified SQL string.  Thie method is designed to be used with
116   * stored procedures.  The default result set type and concurrency
117   * will be used.
118   *
119   * @param sql The SQL statement to use in creating this
120   *            <code>CallableStatement</code>.
121   * @return A new <code>CallableStatement</code>.
122   * @exception SQLException If an error occurs.
123   * @see CallableStatement
124   */
125  CallableStatement prepareCall(String sql) throws SQLException;
126
127  /**
128   * This method converts the specified generic SQL statement into the
129   * native grammer of the database this object is connected to.
130   *
131   * @param sql The JDBC generic SQL statement.
132   * @return The native SQL statement.
133   * @exception SQLException If an error occurs.
134   */
135  String nativeSQL(String sql) throws SQLException;
136
137  /**
138   * This method turns auto commit mode on or off.  In auto commit mode,
139   * every SQL statement is committed its own transaction.  Otherwise a
140   * transaction must be explicitly committed or rolled back.
141   *
142   * @param autoCommit <code>true</code> to enable auto commit mode,
143   *                   <code>false</code> to disable it.
144   * @exception SQLException If an error occurs.
145   * @see #commit()
146   * @see #rollback()
147   */
148  void setAutoCommit(boolean autoCommit) throws SQLException;
149
150  /**
151   * This method tests whether or not auto commit mode is currently enabled.
152   * In auto commit mode,  every SQL statement is committed its own transaction.
153   * Otherwise a transaction must be explicitly committed or rolled back.
154   *
155   * @return <code>true</code> if auto commit mode is enabled,
156   *         <code>false</code> otherwise.
157   * @exception SQLException If an error occurs.
158   * @see #commit()
159   * @see #rollback()
160   */
161  boolean getAutoCommit() throws SQLException;
162
163 /**
164  * This method commits any SQL statements executed on this connection since
165  * the last commit or rollback.
166  *
167  * @exception SQLException If an error occurs.
168  */
169  void commit() throws SQLException;
170
171  /**
172   * This method rolls back any SQL statements executed on this connection
173   * since the last commit or rollback.
174   *
175   * @exception SQLException If an error occurs.
176   */
177  void rollback() throws SQLException;
178
179  /**
180   * This method immediately closes this database connection.
181   *
182   * @exception SQLException If an error occurs.
183   */
184  void close() throws SQLException;
185
186  /**
187   * This method tests whether or not this connection has been closed.
188   *
189   * @return <code>true</code> if the connection is closed, <code>false</code>
190   *         otherwise.
191   * @exception SQLException If an error occurs.
192   */
193  boolean isClosed() throws SQLException;
194
195  /**
196   * This method returns the meta data for this database connection.
197   *
198   * @return The meta data for this database.
199   * @exception SQLException If an error occurs.
200   * @see DatabaseMetaData
201   */
202  DatabaseMetaData getMetaData() throws SQLException;
203
204  /**
205   * This method turns read only mode on or off.  It may not be called while
206   * a transaction is in progress.
207   *
208   * @param readOnly <code>true</code> if this connection is read only,
209   *                 <code>false</code> otherwise.
210   * @exception SQLException If an error occurs.
211   */
212  void setReadOnly(boolean readOnly) throws SQLException;
213
214  /**
215   * This method tests whether or not this connection is in read only mode.
216   *
217   * @return <code>true</code> if the connection is read only <code>false</code>
218   *         otherwise.
219   * @exception SQLException If an error occurs.
220   */
221  boolean isReadOnly() throws SQLException;
222
223  /**
224   * This method sets the name of the catalog in use by this connection.
225   * Note that this method does nothing if catalogs are not supported by
226   * this database.
227   *
228   * @param catalog The name of the catalog to use for this connection.
229   * @exception SQLException If an error occurs.
230   */
231  void setCatalog(String catalog) throws SQLException;
232
233  /**
234   * This method returns the name of the catalog in use by this connection,
235   * if any.
236   *
237   * @return The name of the catalog, or <code>null</code> if none
238   *         exists or catalogs are not supported by this database.
239   * @exception SQLException If an error occurs.
240   */
241  String getCatalog() throws SQLException;
242
243  /**
244   * This method sets the current transaction isolation mode.  This must
245   * be one of the constants defined in this interface.
246   *
247   * @param level The transaction isolation level.
248   * @exception SQLException If an error occurs.
249   */
250  void setTransactionIsolation(int level) throws SQLException;
251
252  /**
253   * This method returns the current transaction isolation mode.  This will
254   * be one of the constants defined in this interface.
255   *
256   * @return The transaction isolation level.
257   * @exception SQLException If an error occurs.
258   */
259  int getTransactionIsolation() throws SQLException;
260
261  /**
262   * This method returns the first warning that occurred on this connection,
263   * if any.  If there were any subsequence warnings, they will be chained
264   * to the first one.
265   *
266   * @return The first <code>SQLWarning</code> that occurred, or
267   *         <code>null</code> if there have been no warnings.
268   * @exception SQLException If an error occurs.
269   */
270  SQLWarning getWarnings() throws SQLException;
271
272  /**
273   * This method clears all warnings that have occurred on this connection.
274   *
275   * @exception SQLException If an error occurs.
276   */
277  void clearWarnings() throws SQLException;
278
279  /**
280   * This method creates a new SQL statement with the specified type and
281   * concurrency.  Valid values for these parameters are specified in the
282   * <code>ResultSet</code> class.
283   *
284   * @param resultSetType The type of result set to use for this statement.
285   * @param resultSetConcurrency  The type of concurrency to be used in
286   *                              the result set for this statement.
287   * @return A new <code>Statement</code> object.
288   * @exception SQLException If an error occurs.
289   * @see Statement
290   * @see ResultSet
291   */
292  Statement createStatement(int resultSetType, int resultSetConcurrency)
293    throws SQLException;
294
295  /**
296   * This method creates a new <code>PreparedStatement</code> for the specified
297   * SQL string.  This method is designed for use with parameterized
298   * statements.  The specified result set type and concurrency will be used.
299   * Valid values for these parameters are specified in the
300   * <code>ResultSet</code> class.
301   *
302   * @param sql The SQL statement to use in creating this
303   *            <code>PreparedStatement</code>.
304   * @param resultSetType The type of result set to use for this statement.
305   * @param resultSetConcurrency  The type of concurrency to be used in
306   *                              the result set for this statement.
307   * @return A new <code>PreparedStatement</code>.
308   * @exception SQLException If an error occurs.
309   * @see PreparedStatement
310   * @see ResultSet
311   */
312  PreparedStatement prepareStatement(String sql, int resultSetType,
313    int resultSetConcurrency) throws SQLException;
314
315  /**
316   * This method creates a new <code>CallableStatement</code> for the
317   * specified SQL string.  Thie method is designed to be used with
318   * stored procedures.  The specified result set type and concurrency
319   * will be used.  Valid values for these parameters are specified in the
320   * <code>ResultSet</code> class.
321   *
322   * @param sql The SQL statement to use in creating this
323   *            <code>PreparedStatement</code>.
324   * @param resultSetType The type of result set to use for this statement.
325   * @param resultSetConcurrency  The type of concurrency to be used in
326   *                              the result set for this statement.
327   * @return A new <code>CallableStatement</code>.
328   * @exception SQLException If an error occurs.
329   * @see CallableStatement
330   * @see ResultSet
331   */
332  CallableStatement prepareCall(String sql, int resultSetType, int
333    resultSetConcurrency) throws SQLException;
334
335  /**
336   * This method returns the mapping of SQL types to Java classes
337   * currently in use by this connection.  This mapping will have no
338   * entries unless they have been manually added.
339   *
340   * @return The SQL type to Java class mapping.
341   * @exception SQLException If an error occurs.
342   */
343  Map<String, Class<?>> getTypeMap() throws SQLException;
344
345  /**
346   * This method sets the mapping table for SQL types to Java classes.
347   * Any entries in this map override the defaults.
348   *
349   * @param map The new SQL mapping table.
350   * @exception SQLException If an error occurs.
351   */
352  void setTypeMap(Map<String, Class<?>> map) throws SQLException;
353
354  /**
355   * Sets the default holdability of <code>ResultSet</code>S that are created
356   * from <code>Statement</code>S using this <code>Connection</code>.
357   *
358   * @param holdability The default holdability value to set, this must be one
359   *                    of <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
360   *                    <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>.
361   * @exception SQLException If an error occurs.
362   * @see ResultSet
363   * @since 1.4
364   */
365  void setHoldability(int holdability) throws SQLException;
366
367  /**
368   * Gets the default holdability of <code>ResultSet</code>S that are created
369   * from <code>Statement</code>S using this <code>Connection</code>.
370   *
371   * @return The current default holdability value, this must be one of
372   *          <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
373   *          <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>.
374   * @exception SQLException If an error occurs.
375   * @see ResultSet
376   * @since 1.4
377   */
378  int getHoldability() throws SQLException;
379
380  /**
381   * Creates a new unnamed savepoint for this <code>Connection</code>
382   *
383   * @return The <code>Savepoint</code> object representing the savepoint.
384   * @exception SQLException If an error occurs.
385   * @since 1.4
386   */
387  Savepoint setSavepoint() throws SQLException;
388
389  /**
390   * Creates a new savepoint with the specifiend name for this
391   * <code>Connection</code>.
392   *
393   * @param name The name of the savepoint.
394   * @return The <code>Savepoint</code> object representing the savepoint.
395   * @exception SQLException If an error occurs.
396   * @since 1.4
397   */
398  Savepoint setSavepoint(String name) throws SQLException;
399
400  /**
401   * Undoes all changes made after the specified savepoint was set.
402   *
403   * @param savepoint The safepoint to roll back to.
404   * @exception SQLException If an error occurs.
405   * @since 1.4
406   */
407  void rollback(Savepoint savepoint) throws SQLException;
408
409  /**
410   * Removes the specified savepoint from this <code>Connection</code>.
411   * Refering to a savepoint after it was removed is an error and will throw an
412   * SQLException.
413   *
414   * @param savepoint The savepoint to release.
415   * @exception SQLException If an error occurs.
416   * @since 1.4
417   */
418  void releaseSavepoint(Savepoint savepoint) throws SQLException;
419
420  /**
421   * This method creates a new SQL statement with the specified type,
422   * concurrency and holdability, instead of using the defaults.  Valid values
423   * for these parameters are specified in the <code>ResultSet</code> class.
424   *
425   * @param resultSetType The type of result set to use for this statement.
426   * @param resultSetConcurrency The type of concurrency to be used in
427   *                             the result set for this statement.
428   * @param resultSetHoldability The type of holdability to be usd in the
429   *                             result set for this statement.
430   * @return A new <code>Statement</code>
431   * @exception SQLException If an error occurs.
432   * @see ResultSet
433   * @since 1.4
434   */
435  Statement createStatement(int resultSetType, int
436      resultSetConcurrency, int resultSetHoldability) throws SQLException;
437
438  /**
439   * This method creates a new <code>PreparedStatement</code> for the specified
440   * SQL string.  This method is designed for use with parameterized
441   * statements.  The specified result set type, concurrency and holdability
442   * will be used. Valid values for these parameters are specified in the
443   * <code>ResultSet</code> class.
444   *
445   * @param sql The SQL statement to use in creating this
446   *            <code>PreparedStatement</code>.
447   * @param resultSetType The type of result set to use for this statement.
448   * @param resultSetConcurrency The type of concurrency to be used in
449   *                             the result set for this statement.
450   * @param resultSetHoldability The type of holdability to be usd in the
451   *                             result set for this statement.
452   * @return A new <code>PreparedStatement</code>.
453   * @exception SQLException If an error occurs.
454   * @see PreparedStatement
455   * @see ResultSet
456   * @since 1.4
457   */
458  PreparedStatement prepareStatement(String sql, int resultSetType, int
459      resultSetConcurrency, int resultSetHoldability) throws SQLException;
460
461  /**
462   * This method creates a new <code>CallableStatement</code> for the
463   * specified SQL string.  Thie method is designed to be used with
464   * stored procedures.  The specified result set type, concurrency and
465   * holdability will be used.  Valid values for these parameters are specified
466   * in the <code>ResultSet</code> class.
467   *
468   * @param sql The SQL statement to use in creating this
469   *            <code>PreparedStatement</code>.
470   * @param resultSetType The type of result set to use for this statement.
471   * @param resultSetConcurrency The type of concurrency to be used in
472   *                             the result set for this statement.
473   * @param resultSetHoldability The type of holdability to be used in the
474   *                             result set for this statement.
475   * @return A new <code>CallableStatement</code>.
476   * @exception SQLException If an error occurs.
477   * @see CallableStatement
478   * @see ResultSet
479   * @since 1.4
480   */
481  CallableStatement prepareCall(String sql, int resultSetType, int
482      resultSetConcurrency, int resultSetHoldability) throws SQLException;
483
484  /**
485   * @since 1.4
486   */
487  PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
488      throws SQLException;
489
490  /**
491   * @since 1.4
492   */
493  PreparedStatement prepareStatement(String sql, int[] columnIndexes)
494      throws SQLException;
495
496  /**
497   * @since 1.4
498   */
499  PreparedStatement prepareStatement(String sql, String[] columnNames)
500      throws SQLException;
501}