Source Code Cross Referenced for Connection.java in  » 6.0-JDK-Core » sql » java » sql » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Home
Java Source Code / Java Documentation
1.6.0 JDK Core
2.6.0 JDK Modules
3.6.0 JDK Modules com.sun
4.6.0 JDK Modules com.sun.java
5.6.0 JDK Modules sun
6.6.0 JDK Platform
7.Ajax
8.Apache Harmony Java SE
9.Aspect oriented
10.Authentication Authorization
11.Blogger System
12.Build
13.Byte Code
14.Cache
15.Chart
16.Chat
17.Code Analyzer
18.Collaboration
19.Content Management System
20.Database Client
21.Database DBMS
22.Database JDBC Connection Pool
23.Database ORM
24.Development
25.EJB Server
26.ERP CRM Financial
27.ESB
28.Forum
29.Game
30.GIS
31.Graphic 3D
32.Graphic Library
33.Groupware
34.HTML Parser
35.IDE
36.IDE Eclipse
37.IDE Netbeans
38.Installer
39.Internationalization Localization
40.Inversion of Control
41.Issue Tracking
42.J2EE
43.J2ME
44.JBoss
45.JMS
46.JMX
47.Library
48.Mail Clients
49.Music
50.Net
51.Parser
52.PDF
53.Portal
54.Profiler
55.Project Management
56.Report
57.RSS RDF
58.Rule Engine
59.Science
60.Scripting
61.Search Engine
62.Security
63.Sevlet Container
64.Source Control
65.Swing Library
66.Template Engine
67.Test Coverage
68.Testing
69.UML
70.Web Crawler
71.Web Framework
72.Web Mail
73.Web Server
74.Web Services
75.Web Services apache cxf 2.2.6
76.Web Services AXIS2
77.Wiki Engine
78.Workflow Engines
79.XML
80.XML UI
Java Source Code / Java Documentation » 6.0 JDK Core » sql » java.sql 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


0001        /*
0002         * Copyright 1996-2006 Sun Microsystems, Inc.  All Rights Reserved.
0003         * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004         *
0005         * This code is free software; you can redistribute it and/or modify it
0006         * under the terms of the GNU General Public License version 2 only, as
0007         * published by the Free Software Foundation.  Sun designates this
0008         * particular file as subject to the "Classpath" exception as provided
0009         * by Sun in the LICENSE file that accompanied this code.
0010         *
0011         * This code is distributed in the hope that it will be useful, but WITHOUT
0012         * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013         * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
0014         * version 2 for more details (a copy is included in the LICENSE file that
0015         * accompanied this code).
0016         *
0017         * You should have received a copy of the GNU General Public License version
0018         * 2 along with this work; if not, write to the Free Software Foundation,
0019         * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020         *
0021         * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022         * CA 95054 USA or visit www.sun.com if you need additional information or
0023         * have any questions.
0024         */
0025
0026        package java.sql;
0027
0028        import java.util.Properties;
0029
0030        /**
0031         * <P>A connection (session) with a specific
0032         * database. SQL statements are executed and results are returned
0033         * within the context of a connection.
0034         * <P>
0035         * A <code>Connection</code> object's database is able to provide information
0036         * describing its tables, its supported SQL grammar, its stored
0037         * procedures, the capabilities of this connection, and so on. This
0038         * information is obtained with the <code>getMetaData</code> method.
0039         *
0040         * <P><B>Note:</B> When configuring a <code>Connection</code>, JDBC applications
0041         *  should use the appropritate <code>Connection</code> method such as 
0042         *  <code>setAutoCommit</code> or <code>setTransactionIsolation</code>.  
0043         *  Applications should not invoke SQL commands directly to change the connection's
0044         *   configuration when there is a JDBC method available.  By default a <code>Connection</code> object is in
0045         * auto-commit mode, which means that it automatically commits changes 
0046         * after executing each statement. If auto-commit mode has been
0047         * disabled, the method <code>commit</code> must be called explicitly in
0048         * order to commit changes; otherwise, database changes will not be saved.
0049         * <P>
0050         * A new <code>Connection</code> object created using the JDBC 2.1 core API
0051         * has an initially empty type map associated with it. A user may enter a
0052         * custom mapping for a UDT in this type map.
0053         * When a UDT is retrieved from a data source with the
0054         * method <code>ResultSet.getObject</code>, the <code>getObject</code> method
0055         * will check the connection's type map to see if there is an entry for that
0056         * UDT.  If so, the <code>getObject</code> method will map the UDT to the
0057         * class indicated.  If there is no entry, the UDT will be mapped using the
0058         * standard mapping.
0059         * <p>
0060         * A user may create a new type map, which is a <code>java.util.Map</code>
0061         * object, make an entry in it, and pass it to the <code>java.sql</code>
0062         * methods that can perform custom mapping.  In this case, the method
0063         * will use the given type map instead of the one associated with
0064         * the connection.
0065         * <p>
0066         * For example, the following code fragment specifies that the SQL
0067         * type <code>ATHLETES</code> will be mapped to the class
0068         * <code>Athletes</code> in the Java programming language.
0069         * The code fragment retrieves the type map for the <code>Connection
0070         * </code> object <code>con</code>, inserts the entry into it, and then sets
0071         * the type map with the new entry as the connection's type map.
0072         * <pre>
0073         *      java.util.Map map = con.getTypeMap();
0074         *      map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
0075         *      con.setTypeMap(map);
0076         * </pre>
0077         *
0078         * @see DriverManager#getConnection
0079         * @see Statement 
0080         * @see ResultSet
0081         * @see DatabaseMetaData
0082         */
0083        public interface Connection extends Wrapper {
0084
0085            /**
0086             * Creates a <code>Statement</code> object for sending
0087             * SQL statements to the database.
0088             * SQL statements without parameters are normally
0089             * executed using <code>Statement</code> objects. If the same SQL statement 
0090             * is executed many times, it may be more efficient to use a 
0091             * <code>PreparedStatement</code> object.
0092             * <P>
0093             * Result sets created using the returned <code>Statement</code>
0094             * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0095             * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 
0096             * The holdability of the created result sets can be determined by 
0097             * calling {@link #getHoldability}.
0098             *
0099             * @return a new default <code>Statement</code> object 
0100             * @exception SQLException if a database access error occurs 
0101             * or this method is called on a closed connection
0102             */
0103            Statement createStatement() throws SQLException;
0104
0105            /**
0106             * Creates a <code>PreparedStatement</code> object for sending
0107             * parameterized SQL statements to the database.
0108             * <P>
0109             * A SQL statement with or without IN parameters can be
0110             * pre-compiled and stored in a <code>PreparedStatement</code> object. This
0111             * object can then be used to efficiently execute this statement
0112             * multiple times.
0113             *
0114             * <P><B>Note:</B> This method is optimized for handling
0115             * parametric SQL statements that benefit from precompilation. If
0116             * the driver supports precompilation,
0117             * the method <code>prepareStatement</code> will send
0118             * the statement to the database for precompilation. Some drivers
0119             * may not support precompilation. In this case, the statement may
0120             * not be sent to the database until the <code>PreparedStatement</code> 
0121             * object is executed.  This has no direct effect on users; however, it does
0122             * affect which methods throw certain <code>SQLException</code> objects.
0123             * <P>
0124             * Result sets created using the returned <code>PreparedStatement</code>
0125             * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0126             * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 
0127             * The holdability of the created result sets can be determined by 
0128             * calling {@link #getHoldability}.
0129             *
0130             * @param sql an SQL statement that may contain one or more '?' IN
0131             * parameter placeholders
0132             * @return a new default <code>PreparedStatement</code> object containing the
0133             * pre-compiled SQL statement 
0134             * @exception SQLException if a database access error occurs 
0135             * or this method is called on a closed connection
0136             */
0137            PreparedStatement prepareStatement(String sql) throws SQLException;
0138
0139            /**
0140             * Creates a <code>CallableStatement</code> object for calling
0141             * database stored procedures.
0142             * The <code>CallableStatement</code> object provides
0143             * methods for setting up its IN and OUT parameters, and
0144             * methods for executing the call to a stored procedure.
0145             *
0146             * <P><B>Note:</B> This method is optimized for handling stored
0147             * procedure call statements. Some drivers may send the call
0148             * statement to the database when the method <code>prepareCall</code>
0149             * is done; others
0150             * may wait until the <code>CallableStatement</code> object
0151             * is executed. This has no
0152             * direct effect on users; however, it does affect which method
0153             * throws certain SQLExceptions.
0154             * <P>
0155             * Result sets created using the returned <code>CallableStatement</code>
0156             * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0157             * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 
0158             * The holdability of the created result sets can be determined by 
0159             * calling {@link #getHoldability}.
0160             *
0161             * @param sql an SQL statement that may contain one or more '?'
0162             * parameter placeholders. Typically this statement is specified using JDBC
0163             * call escape syntax.
0164             * @return a new default <code>CallableStatement</code> object containing the
0165             * pre-compiled SQL statement 
0166             * @exception SQLException if a database access error occurs 
0167             * or this method is called on a closed connection
0168             */
0169            CallableStatement prepareCall(String sql) throws SQLException;
0170
0171            /**
0172             * Converts the given SQL statement into the system's native SQL grammar.
0173             * A driver may convert the JDBC SQL grammar into its system's
0174             * native SQL grammar prior to sending it. This method returns the
0175             * native form of the statement that the driver would have sent.
0176             *
0177             * @param sql an SQL statement that may contain one or more '?'
0178             * parameter placeholders
0179             * @return the native form of this statement
0180             * @exception SQLException if a database access error occurs 
0181             * or this method is called on a closed connection
0182             */
0183            String nativeSQL(String sql) throws SQLException;
0184
0185            /**
0186             * Sets this connection's auto-commit mode to the given state.
0187             * If a connection is in auto-commit mode, then all its SQL
0188             * statements will be executed and committed as individual
0189             * transactions.  Otherwise, its SQL statements are grouped into
0190             * transactions that are terminated by a call to either
0191             * the method <code>commit</code> or the method <code>rollback</code>.
0192             * By default, new connections are in auto-commit
0193             * mode.
0194             * <P>
0195             * The commit occurs when the statement completes. The time when the statement 
0196             * completes depends on the type of SQL Statement:
0197             * <ul>
0198             * <li>For DML statements, such as Insert, Update or Delete, and DDL statements, 
0199             * the statement is complete as soon as it has finished executing.
0200             * <li>For Select statements, the statement is complete when the associated result 
0201             * set is closed.
0202             * <li>For <code>CallableStatement</code> objects or for statements that return 
0203             * multiple results, the statement is complete 
0204             * when all of the associated result sets have been closed, and all update 
0205             * counts and output parameters have been retrieved.
0206             *</ul>
0207             * <P>
0208             * <B>NOTE:</B>  If this method is called during a transaction and the 
0209             * auto-commit mode is changed, the transaction is committed.  If
0210             * <code>setAutoCommit</code> is called and the auto-commit mode is 
0211             * not changed, the call is a no-op.
0212             *
0213             * @param autoCommit <code>true</code> to enable auto-commit mode; 
0214             *         <code>false</code> to disable it
0215             * @exception SQLException if a database access error occurs,
0216             *  setAutoCommit(true) is called while participating in a distributed transaction, 
0217             * or this method is called on a closed connection
0218             * @see #getAutoCommit
0219             */
0220            void setAutoCommit(boolean autoCommit) throws SQLException;
0221
0222            /**
0223             * Retrieves the current auto-commit mode for this <code>Connection</code>
0224             * object.
0225             *
0226             * @return the current state of this <code>Connection</code> object's 
0227             *         auto-commit mode
0228             * @exception SQLException if a database access error occurs 
0229             * or this method is called on a closed connection
0230             * @see #setAutoCommit 
0231             */
0232            boolean getAutoCommit() throws SQLException;
0233
0234            /**
0235             * Makes all changes made since the previous
0236             * commit/rollback permanent and releases any database locks
0237             * currently held by this <code>Connection</code> object. 
0238             * This method should be
0239             * used only when auto-commit mode has been disabled.
0240             *
0241             * @exception SQLException if a database access error occurs, 
0242             * this method is called while participating in a distributed transaction,
0243             * if this method is called on a closed conection or this
0244             *            <code>Connection</code> object is in auto-commit mode
0245             * @see #setAutoCommit 
0246             */
0247            void commit() throws SQLException;
0248
0249            /**
0250             * Undoes all changes made in the current transaction
0251             * and releases any database locks currently held
0252             * by this <code>Connection</code> object. This method should be 
0253             * used only when auto-commit mode has been disabled.
0254             *
0255             * @exception SQLException if a database access error occurs, 
0256             * this method is called while participating in a distributed transaction,
0257             * this method is called on a closed connection or this
0258             *            <code>Connection</code> object is in auto-commit mode
0259             * @see #setAutoCommit 
0260             */
0261            void rollback() throws SQLException;
0262
0263            /**
0264             * Releases this <code>Connection</code> object's database and JDBC resources
0265             * immediately instead of waiting for them to be automatically released.
0266             * <P>
0267             * Calling the method <code>close</code> on a <code>Connection</code>
0268             * object that is already closed is a no-op.
0269             * <P>
0270             * It is <b>strongly recommended</b> that an application explicitly 
0271             * commits or rolls back an active transaction prior to calling the 
0272             * <code>close</code> method.  If the <code>close</code> method is called
0273             * and there is an active transaction, the results are implementation-defined.
0274             * <P>
0275             * 
0276             * @exception SQLException SQLException if a database access error occurs 
0277             */
0278            void close() throws SQLException;
0279
0280            /**
0281             * Retrieves whether this <code>Connection</code> object has been
0282             * closed.  A connection is closed if the method <code>close</code>
0283             * has been called on it or if certain fatal errors have occurred.
0284             * This method is guaranteed to return <code>true</code> only when
0285             * it is called after the method <code>Connection.close</code> has
0286             * been called.
0287             * <P>
0288             * This method generally cannot be called to determine whether a
0289             * connection to a database is valid or invalid.  A typical client
0290             * can determine that a connection is invalid by catching any
0291             * exceptions that might be thrown when an operation is attempted.
0292             *
0293             * @return <code>true</code> if this <code>Connection</code> object 
0294             *         is closed; <code>false</code> if it is still open
0295             * @exception SQLException if a database access error occurs
0296             */
0297            boolean isClosed() throws SQLException;
0298
0299            //======================================================================
0300            // Advanced features:
0301
0302            /**
0303             * Retrieves a <code>DatabaseMetaData</code> object that contains
0304             * metadata about the database to which this
0305             * <code>Connection</code> object represents a connection.
0306             * The metadata includes information about the database's
0307             * tables, its supported SQL grammar, its stored
0308             * procedures, the capabilities of this connection, and so on.
0309             *
0310             * @return a <code>DatabaseMetaData</code> object for this 
0311             *         <code>Connection</code> object
0312             * @exception  SQLException if a database access error occurs 
0313             * or this method is called on a closed connection
0314             */
0315            DatabaseMetaData getMetaData() throws SQLException;
0316
0317            /**
0318             * Puts this connection in read-only mode as a hint to the driver to enable 
0319             * database optimizations.
0320             *
0321             * <P><B>Note:</B> This method cannot be called during a transaction.
0322             *
0323             * @param readOnly <code>true</code> enables read-only mode; 
0324             *        <code>false</code> disables it
0325             * @exception SQLException if a database access error occurs, this
0326             *  method is called on a closed connection or this
0327             *            method is called during a transaction
0328             */
0329            void setReadOnly(boolean readOnly) throws SQLException;
0330
0331            /**
0332             * Retrieves whether this <code>Connection</code> 
0333             * object is in read-only mode.
0334             *
0335             * @return <code>true</code> if this <code>Connection</code> object
0336             *         is read-only; <code>false</code> otherwise
0337             * @exception SQLException SQLException if a database access error occurs 
0338             * or this method is called on a closed connection
0339             */
0340            boolean isReadOnly() throws SQLException;
0341
0342            /**
0343             * Sets the given catalog name in order to select 	
0344             * a subspace of this <code>Connection</code> object's database 
0345             * in which to work.
0346             * <P>
0347             * If the driver does not support catalogs, it will
0348             * silently ignore this request.
0349             *
0350             * @param catalog the name of a catalog (subspace in this 
0351             *        <code>Connection</code> object's database) in which to work
0352             * @exception SQLException if a database access error occurs 
0353             * or this method is called on a closed connection
0354             * @see #getCatalog
0355             */
0356            void setCatalog(String catalog) throws SQLException;
0357
0358            /**
0359             * Retrieves this <code>Connection</code> object's current catalog name.
0360             *
0361             * @return the current catalog name or <code>null</code> if there is none
0362             * @exception SQLException if a database access error occurs 
0363             * or this method is called on a closed connection
0364             * @see #setCatalog
0365             */
0366            String getCatalog() throws SQLException;
0367
0368            /**
0369             * A constant indicating that transactions are not supported. 
0370             */
0371            int TRANSACTION_NONE = 0;
0372
0373            /**
0374             * A constant indicating that
0375             * dirty reads, non-repeatable reads and phantom reads can occur.
0376             * This level allows a row changed by one transaction to be read
0377             * by another transaction before any changes in that row have been
0378             * committed (a "dirty read").  If any of the changes are rolled back, 
0379             * the second transaction will have retrieved an invalid row.
0380             */
0381            int TRANSACTION_READ_UNCOMMITTED = 1;
0382
0383            /**
0384             * A constant indicating that
0385             * dirty reads are prevented; non-repeatable reads and phantom
0386             * reads can occur.  This level only prohibits a transaction
0387             * from reading a row with uncommitted changes in it.
0388             */
0389            int TRANSACTION_READ_COMMITTED = 2;
0390
0391            /**
0392             * A constant indicating that
0393             * dirty reads and non-repeatable reads are prevented; phantom
0394             * reads can occur.  This level prohibits a transaction from
0395             * reading a row with uncommitted changes in it, and it also
0396             * prohibits the situation where one transaction reads a row,
0397             * a second transaction alters the row, and the first transaction
0398             * rereads the row, getting different values the second time
0399             * (a "non-repeatable read").
0400             */
0401            int TRANSACTION_REPEATABLE_READ = 4;
0402
0403            /**
0404             * A constant indicating that
0405             * dirty reads, non-repeatable reads and phantom reads are prevented.
0406             * This level includes the prohibitions in
0407             * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the 
0408             * situation where one transaction reads all rows that satisfy
0409             * a <code>WHERE</code> condition, a second transaction inserts a row that
0410             * satisfies that <code>WHERE</code> condition, and the first transaction
0411             * rereads for the same condition, retrieving the additional
0412             * "phantom" row in the second read.
0413             */
0414            int TRANSACTION_SERIALIZABLE = 8;
0415
0416            /**
0417             * Attempts to change the transaction isolation level for this
0418             * <code>Connection</code> object to the one given.
0419             * The constants defined in the interface <code>Connection</code>
0420             * are the possible transaction isolation levels.
0421             * <P>
0422             * <B>Note:</B> If this method is called during a transaction, the result
0423             * is implementation-defined.
0424             *
0425             * @param level one of the following <code>Connection</code> constants:
0426             *        <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
0427             *        <code>Connection.TRANSACTION_READ_COMMITTED</code>,
0428             *        <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
0429             *        <code>Connection.TRANSACTION_SERIALIZABLE</code>.
0430             *        (Note that <code>Connection.TRANSACTION_NONE</code> cannot be used 
0431             *        because it specifies that transactions are not supported.)
0432             * @exception SQLException if a database access error occurs, this 
0433             * method is called on a closed connection 
0434             *            or the given parameter is not one of the <code>Connection</code>
0435             *            constants
0436             * @see DatabaseMetaData#supportsTransactionIsolationLevel 
0437             * @see #getTransactionIsolation
0438             */
0439            void setTransactionIsolation(int level) throws SQLException;
0440
0441            /**
0442             * Retrieves this <code>Connection</code> object's current 
0443             * transaction isolation level.
0444             *
0445             * @return the current transaction isolation level, which will be one
0446             *         of the following constants:
0447             *        <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>, 
0448             *        <code>Connection.TRANSACTION_READ_COMMITTED</code>,
0449             *        <code>Connection.TRANSACTION_REPEATABLE_READ</code>, 
0450             *        <code>Connection.TRANSACTION_SERIALIZABLE</code>, or
0451             *        <code>Connection.TRANSACTION_NONE</code>.
0452             * @exception SQLException if a database access error occurs 
0453             * or this method is called on a closed connection
0454             * @see #setTransactionIsolation
0455             */
0456            int getTransactionIsolation() throws SQLException;
0457
0458            /**
0459             * Retrieves the first warning reported by calls on this 
0460             * <code>Connection</code> object.  If there is more than one
0461             * warning, subsequent warnings will be chained to the first one
0462             * and can be retrieved by calling the method
0463             * <code>SQLWarning.getNextWarning</code> on the warning 
0464             * that was retrieved previously.
0465             * <P>
0466             * This method may not be
0467             * called on a closed connection; doing so will cause an
0468             * <code>SQLException</code> to be thrown.
0469             *
0470             * <P><B>Note:</B> Subsequent warnings will be chained to this
0471             * SQLWarning.
0472             *
0473             * @return the first <code>SQLWarning</code> object or <code>null</code>
0474             *         if there are none 
0475             * @exception SQLException if a database access error occurs or
0476             *            this method is called on a closed connection
0477             * @see SQLWarning
0478             */
0479            SQLWarning getWarnings() throws SQLException;
0480
0481            /**
0482             * Clears all warnings reported for this <code>Connection</code> object.	
0483             * After a call to this method, the method <code>getWarnings</code>
0484             * returns <code>null</code> until a new warning is
0485             * reported for this <code>Connection</code> object.  
0486             *
0487             * @exception SQLException SQLException if a database access error occurs 
0488             * or this method is called on a closed connection
0489             */
0490            void clearWarnings() throws SQLException;
0491
0492            //--------------------------JDBC 2.0-----------------------------
0493
0494            /**
0495             * Creates a <code>Statement</code> object that will generate
0496             * <code>ResultSet</code> objects with the given type and concurrency.
0497             * This method is the same as the <code>createStatement</code> method
0498             * above, but it allows the default result set
0499             * type and concurrency to be overridden. 
0500             * The holdability of the created result sets can be determined by 
0501             * calling {@link #getHoldability}.
0502             *
0503             * @param resultSetType a result set type; one of 
0504             *        <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0505             *        <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0506             *        <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0507             * @param resultSetConcurrency a concurrency type; one of
0508             *        <code>ResultSet.CONCUR_READ_ONLY</code> or
0509             *        <code>ResultSet.CONCUR_UPDATABLE</code>
0510             * @return a new <code>Statement</code> object that will generate
0511             *         <code>ResultSet</code> objects with the given type and
0512             *         concurrency
0513             * @exception SQLException if a database access error occurs, this 
0514             * method is called on a closed connection 
0515             *         or the given parameters are not <code>ResultSet</code> 
0516             *         constants indicating type and concurrency
0517             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0518             * this method or this method is not supported for the specified result 
0519             * set type and result set concurrency.
0520             * @since 1.2
0521             */
0522            Statement createStatement(int resultSetType,
0523                    int resultSetConcurrency) throws SQLException;
0524
0525            /**
0526             *
0527             * Creates a <code>PreparedStatement</code> object that will generate
0528             * <code>ResultSet</code> objects with the given type and concurrency.
0529             * This method is the same as the <code>prepareStatement</code> method
0530             * above, but it allows the default result set
0531             * type and concurrency to be overridden. 
0532             * The holdability of the created result sets can be determined by 
0533             * calling {@link #getHoldability}.
0534             *
0535             * @param sql a <code>String</code> object that is the SQL statement to
0536             *            be sent to the database; may contain one or more '?' IN
0537             *            parameters
0538             * @param resultSetType a result set type; one of 
0539             *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
0540             *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0541             *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0542             * @param resultSetConcurrency a concurrency type; one of
0543             *         <code>ResultSet.CONCUR_READ_ONLY</code> or
0544             *         <code>ResultSet.CONCUR_UPDATABLE</code>
0545             * @return a new PreparedStatement object containing the
0546             * pre-compiled SQL statement that will produce <code>ResultSet</code>
0547             * objects with the given type and concurrency
0548             * @exception SQLException if a database access error occurs, this 
0549             * method is called on a closed connection 
0550             *         or the given parameters are not <code>ResultSet</code> 
0551             *         constants indicating type and concurrency
0552             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0553             * this method or this method is not supported for the specified result 
0554             * set type and result set concurrency.
0555             * @since 1.2
0556             */
0557            PreparedStatement prepareStatement(String sql, int resultSetType,
0558                    int resultSetConcurrency) throws SQLException;
0559
0560            /**
0561             * Creates a <code>CallableStatement</code> object that will generate
0562             * <code>ResultSet</code> objects with the given type and concurrency.
0563             * This method is the same as the <code>prepareCall</code> method
0564             * above, but it allows the default result set
0565             * type and concurrency to be overridden. 
0566             * The holdability of the created result sets can be determined by 
0567             * calling {@link #getHoldability}.
0568             *
0569             * @param sql a <code>String</code> object that is the SQL statement to
0570             *            be sent to the database; may contain on or more '?' parameters
0571             * @param resultSetType a result set type; one of 
0572             *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
0573             *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0574             *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0575             * @param resultSetConcurrency a concurrency type; one of
0576             *         <code>ResultSet.CONCUR_READ_ONLY</code> or
0577             *         <code>ResultSet.CONCUR_UPDATABLE</code>
0578             * @return a new <code>CallableStatement</code> object containing the
0579             * pre-compiled SQL statement that will produce <code>ResultSet</code>
0580             * objects with the given type and concurrency
0581             * @exception SQLException if a database access error occurs, this method 
0582             * is called on a closed connection 
0583             *         or the given parameters are not <code>ResultSet</code> 
0584             *         constants indicating type and concurrency
0585             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0586             * this method or this method is not supported for the specified result 
0587             * set type and result set concurrency.
0588             * @since 1.2
0589             */
0590            CallableStatement prepareCall(String sql, int resultSetType,
0591                    int resultSetConcurrency) throws SQLException;
0592
0593            /**
0594             * Retrieves the <code>Map</code> object associated with this 
0595             * <code>Connection</code> object.
0596             * Unless the application has added an entry, the type map returned 
0597             * will be empty.
0598             *
0599             * @return the <code>java.util.Map</code> object associated 
0600             *         with this <code>Connection</code> object
0601             * @exception SQLException if a database access error occurs 
0602             * or this method is called on a closed connection
0603             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0604             * this method
0605             * @since 1.2
0606             * @see #setTypeMap
0607             */
0608            java.util.Map<String, Class<?>> getTypeMap() throws SQLException;
0609
0610            /**
0611             * Installs the given <code>TypeMap</code> object as the type map for
0612             * this <code>Connection</code> object.  The type map will be used for the
0613             * custom mapping of SQL structured types and distinct types.
0614             *
0615             * @param map the <code>java.util.Map</code> object to install
0616             *        as the replacement for this <code>Connection</code>
0617             *        object's default type map
0618             * @exception SQLException if a database access error occurs, this 
0619             * method is called on a closed connection or
0620             *        the given parameter is not a <code>java.util.Map</code> 
0621             *        object
0622             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0623             * this method
0624             * @since 1.2
0625             * @see #getTypeMap
0626             */
0627            void setTypeMap(java.util.Map<String, Class<?>> map)
0628                    throws SQLException;
0629
0630            //--------------------------JDBC 3.0-----------------------------
0631
0632            /**
0633             * Changes the default holdability of <code>ResultSet</code> objects
0634             * created using this <code>Connection</code> object to the given
0635             * holdability.  The default holdability of <code>ResultSet</code> objects
0636             * can be be determined by invoking 
0637             * {@link DatabaseMetaData#getResultSetHoldability}.
0638             *
0639             * @param holdability a <code>ResultSet</code> holdability constant; one of
0640             *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0641             *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0642             * @throws SQLException if a database access occurs, this method is called
0643             * on a closed connection, or the given parameter
0644             *         is not a <code>ResultSet</code> constant indicating holdability
0645             * @exception SQLFeatureNotSupportedException if the given holdability is not supported
0646             * @see #getHoldability
0647             * @see DatabaseMetaData#getResultSetHoldability
0648             * @see ResultSet
0649             * @since 1.4
0650             */
0651            void setHoldability(int holdability) throws SQLException;
0652
0653            /**
0654             * Retrieves the current holdability of <code>ResultSet</code> objects
0655             * created using this <code>Connection</code> object.
0656             *
0657             * @return the holdability, one of
0658             *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0659             *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0660             * @throws SQLException if a database access error occurs 
0661             * or this method is called on a closed connection
0662             * @see #setHoldability
0663             * @see DatabaseMetaData#getResultSetHoldability
0664             * @see ResultSet
0665             * @since 1.4
0666             */
0667            int getHoldability() throws SQLException;
0668
0669            /**
0670             * Creates an unnamed savepoint in the current transaction and 
0671             * returns the new <code>Savepoint</code> object that represents it.
0672             *
0673             *<p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created 
0674             *savepoint.
0675             *
0676             * @return the new <code>Savepoint</code> object
0677             * @exception SQLException if a database access error occurs,
0678             * this method is called while participating in a distributed transaction,
0679             * this method is called on a closed connection 
0680             *            or this <code>Connection</code> object is currently in
0681             *            auto-commit mode
0682             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0683             * this method
0684             * @see Savepoint
0685             * @since 1.4
0686             */
0687            Savepoint setSavepoint() throws SQLException;
0688
0689            /**
0690             * Creates a savepoint with the given name in the current transaction
0691             * and returns the new <code>Savepoint</code> object that represents it.
0692             *
0693             * <p> if setSavepoint is invoked outside of an active transaction, a transaction will be started at this newly created 
0694             *savepoint.
0695             *
0696             * @param name a <code>String</code> containing the name of the savepoint
0697             * @return the new <code>Savepoint</code> object
0698             * @exception SQLException if a database access error occurs,
0699             * this method is called while participating in a distributed transaction, 
0700             * this method is called on a closed connection 
0701             *            or this <code>Connection</code> object is currently in
0702             *            auto-commit mode
0703             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0704             * this method
0705             * @see Savepoint
0706             * @since 1.4
0707             */
0708            Savepoint setSavepoint(String name) throws SQLException;
0709
0710            /**
0711             * Undoes all changes made after the given <code>Savepoint</code> object
0712             * was set. 
0713             * <P>
0714             * This method should be used only when auto-commit has been disabled.
0715             *
0716             * @param savepoint the <code>Savepoint</code> object to roll back to
0717             * @exception SQLException if a database access error occurs, 
0718             * this method is called while participating in a distributed transaction,  
0719             * this method is called on a closed connection, 
0720             *            the <code>Savepoint</code> object is no longer valid,
0721             *            or this <code>Connection</code> object is currently in
0722             *            auto-commit mode
0723             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0724             * this method
0725             * @see Savepoint
0726             * @see #rollback
0727             * @since 1.4
0728             */
0729            void rollback(Savepoint savepoint) throws SQLException;
0730
0731            /**
0732             * Removes the specified <code>Savepoint</code>  and subsequent <code>Savepoint</code> objects from the current 
0733             * transaction. Any reference to the savepoint after it have been removed 
0734             * will cause an <code>SQLException</code> to be thrown.
0735             *
0736             * @param savepoint the <code>Savepoint</code> object to be removed
0737             * @exception SQLException if a database access error occurs, this 
0738             *  method is called on a closed connection or
0739             *            the given <code>Savepoint</code> object is not a valid 
0740             *            savepoint in the current transaction
0741             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0742             * this method
0743             * @since 1.4
0744             */
0745            void releaseSavepoint(Savepoint savepoint) throws SQLException;
0746
0747            /**
0748             * Creates a <code>Statement</code> object that will generate
0749             * <code>ResultSet</code> objects with the given type, concurrency,
0750             * and holdability.
0751             * This method is the same as the <code>createStatement</code> method
0752             * above, but it allows the default result set
0753             * type, concurrency, and holdability to be overridden.
0754             *
0755             * @param resultSetType one of the following <code>ResultSet</code> 
0756             *        constants:
0757             *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
0758             *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0759             *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0760             * @param resultSetConcurrency one of the following <code>ResultSet</code> 
0761             *        constants:
0762             *         <code>ResultSet.CONCUR_READ_ONLY</code> or
0763             *         <code>ResultSet.CONCUR_UPDATABLE</code>
0764             * @param resultSetHoldability one of the following <code>ResultSet</code> 
0765             *        constants:
0766             *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0767             *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0768             * @return a new <code>Statement</code> object that will generate
0769             *         <code>ResultSet</code> objects with the given type,
0770             *         concurrency, and holdability
0771             * @exception SQLException if a database access error occurs, this 
0772             * method is called on a closed connection 
0773             *            or the given parameters are not <code>ResultSet</code> 
0774             *            constants indicating type, concurrency, and holdability
0775             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0776             * this method or this method is not supported for the specified result 
0777             * set type, result set holdability and result set concurrency.
0778             * @see ResultSet
0779             * @since 1.4
0780             */
0781            Statement createStatement(int resultSetType,
0782                    int resultSetConcurrency, int resultSetHoldability)
0783                    throws SQLException;
0784
0785            /**
0786             * Creates a <code>PreparedStatement</code> object that will generate
0787             * <code>ResultSet</code> objects with the given type, concurrency,
0788             * and holdability.
0789             * <P>
0790             * This method is the same as the <code>prepareStatement</code> method
0791             * above, but it allows the default result set
0792             * type, concurrency, and holdability to be overridden.
0793             *
0794             * @param sql a <code>String</code> object that is the SQL statement to
0795             *            be sent to the database; may contain one or more '?' IN
0796             *            parameters
0797             * @param resultSetType one of the following <code>ResultSet</code> 
0798             *        constants:
0799             *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
0800             *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0801             *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0802             * @param resultSetConcurrency one of the following <code>ResultSet</code> 
0803             *        constants:
0804             *         <code>ResultSet.CONCUR_READ_ONLY</code> or
0805             *         <code>ResultSet.CONCUR_UPDATABLE</code>
0806             * @param resultSetHoldability one of the following <code>ResultSet</code> 
0807             *        constants:
0808             *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0809             *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0810             * @return a new <code>PreparedStatement</code> object, containing the
0811             *         pre-compiled SQL statement, that will generate
0812             *         <code>ResultSet</code> objects with the given type,
0813             *         concurrency, and holdability
0814             * @exception SQLException if a database access error occurs, this 
0815             * method is called on a closed connection 
0816             *            or the given parameters are not <code>ResultSet</code> 
0817             *            constants indicating type, concurrency, and holdability
0818             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0819             * this method or this method is not supported for the specified result 
0820             * set type, result set holdability and result set concurrency.
0821             * @see ResultSet
0822             * @since 1.4
0823             */
0824            PreparedStatement prepareStatement(String sql, int resultSetType,
0825                    int resultSetConcurrency, int resultSetHoldability)
0826                    throws SQLException;
0827
0828            /**
0829             * Creates a <code>CallableStatement</code> object that will generate
0830             * <code>ResultSet</code> objects with the given type and concurrency.
0831             * This method is the same as the <code>prepareCall</code> method
0832             * above, but it allows the default result set
0833             * type, result set concurrency type and holdability to be overridden.
0834             *
0835             * @param sql a <code>String</code> object that is the SQL statement to
0836             *            be sent to the database; may contain on or more '?' parameters
0837             * @param resultSetType one of the following <code>ResultSet</code> 
0838             *        constants:
0839             *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
0840             *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0841             *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0842             * @param resultSetConcurrency one of the following <code>ResultSet</code> 
0843             *        constants:
0844             *         <code>ResultSet.CONCUR_READ_ONLY</code> or
0845             *         <code>ResultSet.CONCUR_UPDATABLE</code>
0846             * @param resultSetHoldability one of the following <code>ResultSet</code> 
0847             *        constants:
0848             *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
0849             *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
0850             * @return a new <code>CallableStatement</code> object, containing the
0851             *         pre-compiled SQL statement, that will generate
0852             *         <code>ResultSet</code> objects with the given type,
0853             *         concurrency, and holdability
0854             * @exception SQLException if a database access error occurs, this 
0855             * method is called on a closed connection 
0856             *            or the given parameters are not <code>ResultSet</code> 
0857             *            constants indicating type, concurrency, and holdability
0858             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0859             * this method or this method is not supported for the specified result 
0860             * set type, result set holdability and result set concurrency.
0861             * @see ResultSet
0862             * @since 1.4
0863             */
0864            CallableStatement prepareCall(String sql, int resultSetType,
0865                    int resultSetConcurrency, int resultSetHoldability)
0866                    throws SQLException;
0867
0868            /**
0869             * Creates a default <code>PreparedStatement</code> object that has
0870             * the capability to retrieve auto-generated keys. The given constant
0871             * tells the driver whether it should make auto-generated keys
0872             * available for retrieval.  This parameter is ignored if the SQL statement
0873             * is not an <code>INSERT</code> statement, or an SQL statement able to return
0874             * auto-generated keys (the list of such statements is vendor-specific).
0875             * <P>
0876             * <B>Note:</B> This method is optimized for handling
0877             * parametric SQL statements that benefit from precompilation. If
0878             * the driver supports precompilation,
0879             * the method <code>prepareStatement</code> will send
0880             * the statement to the database for precompilation. Some drivers
0881             * may not support precompilation. In this case, the statement may
0882             * not be sent to the database until the <code>PreparedStatement</code> 
0883             * object is executed.  This has no direct effect on users; however, it does
0884             * affect which methods throw certain SQLExceptions.
0885             * <P>
0886             * Result sets created using the returned <code>PreparedStatement</code>
0887             * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0888             * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 
0889             * The holdability of the created result sets can be determined by 
0890             * calling {@link #getHoldability}.
0891             *
0892             * @param sql an SQL statement that may contain one or more '?' IN
0893             *        parameter placeholders
0894             * @param autoGeneratedKeys a flag indicating whether auto-generated keys 
0895             *        should be returned; one of
0896             *        <code>Statement.RETURN_GENERATED_KEYS</code> or
0897             *	      <code>Statement.NO_GENERATED_KEYS</code>  
0898             * @return a new <code>PreparedStatement</code> object, containing the
0899             *         pre-compiled SQL statement, that will have the capability of
0900             *         returning auto-generated keys
0901             * @exception SQLException if a database access error occurs, this
0902             *  method is called on a closed connection 
0903             *         or the given parameter is not a <code>Statement</code>
0904             *         constant indicating whether auto-generated keys should be
0905             *         returned
0906             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0907             * this method with a constant of Statement.RETURN_GENERATED_KEYS
0908             * @since 1.4
0909             */
0910            PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
0911                    throws SQLException;
0912
0913            /**
0914             * Creates a default <code>PreparedStatement</code> object capable
0915             * of returning the auto-generated keys designated by the given array.
0916             * This array contains the indexes of the columns in the target
0917             * table that contain the auto-generated keys that should be made
0918             * available.  The driver will ignore the array if the SQL statement
0919             * is not an <code>INSERT</code> statement, or an SQL statement able to return
0920             * auto-generated keys (the list of such statements is vendor-specific).
0921             *<p>
0922             * An SQL statement with or without IN parameters can be
0923             * pre-compiled and stored in a <code>PreparedStatement</code> object. This
0924             * object can then be used to efficiently execute this statement
0925             * multiple times.
0926             * <P>
0927             * <B>Note:</B> This method is optimized for handling
0928             * parametric SQL statements that benefit from precompilation. If
0929             * the driver supports precompilation,
0930             * the method <code>prepareStatement</code> will send
0931             * the statement to the database for precompilation. Some drivers
0932             * may not support precompilation. In this case, the statement may
0933             * not be sent to the database until the <code>PreparedStatement</code> 
0934             * object is executed.  This has no direct effect on users; however, it does
0935             * affect which methods throw certain SQLExceptions.
0936             * <P>
0937             * Result sets created using the returned <code>PreparedStatement</code>
0938             * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0939             * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 
0940             * The holdability of the created result sets can be determined by 
0941             * calling {@link #getHoldability}.
0942             *
0943             * @param sql an SQL statement that may contain one or more '?' IN
0944             *        parameter placeholders
0945             * @param columnIndexes an array of column indexes indicating the columns
0946             *        that should be returned from the inserted row or rows 
0947             * @return a new <code>PreparedStatement</code> object, containing the
0948             *         pre-compiled statement, that is capable of returning the
0949             *         auto-generated keys designated by the given array of column
0950             *         indexes
0951             * @exception SQLException if a database access error occurs 
0952             * or this method is called on a closed connection
0953             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0954             * this method
0955             *
0956             * @since 1.4
0957             */
0958            PreparedStatement prepareStatement(String sql, int columnIndexes[])
0959                    throws SQLException;
0960
0961            /**
0962             * Creates a default <code>PreparedStatement</code> object capable
0963             * of returning the auto-generated keys designated by the given array.
0964             * This array contains the names of the columns in the target
0965             * table that contain the auto-generated keys that should be returned.
0966             * The driver will ignore the array if the SQL statement
0967             * is not an <code>INSERT</code> statement, or an SQL statement able to return
0968             * auto-generated keys (the list of such statements is vendor-specific).
0969             * <P>
0970             * An SQL statement with or without IN parameters can be
0971             * pre-compiled and stored in a <code>PreparedStatement</code> object. This
0972             * object can then be used to efficiently execute this statement
0973             * multiple times.
0974             * <P>
0975             * <B>Note:</B> This method is optimized for handling
0976             * parametric SQL statements that benefit from precompilation. If
0977             * the driver supports precompilation,
0978             * the method <code>prepareStatement</code> will send
0979             * the statement to the database for precompilation. Some drivers
0980             * may not support precompilation. In this case, the statement may
0981             * not be sent to the database until the <code>PreparedStatement</code> 
0982             * object is executed.  This has no direct effect on users; however, it does
0983             * affect which methods throw certain SQLExceptions.
0984             * <P>
0985             * Result sets created using the returned <code>PreparedStatement</code>
0986             * object will by default be type <code>TYPE_FORWARD_ONLY</code>
0987             * and have a concurrency level of <code>CONCUR_READ_ONLY</code>. 
0988             * The holdability of the created result sets can be determined by 
0989             * calling {@link #getHoldability}.
0990             *
0991             * @param sql an SQL statement that may contain one or more '?' IN
0992             *        parameter placeholders
0993             * @param columnNames an array of column names indicating the columns
0994             *        that should be returned from the inserted row or rows 
0995             * @return a new <code>PreparedStatement</code> object, containing the
0996             *         pre-compiled statement, that is capable of returning the
0997             *         auto-generated keys designated by the given array of column
0998             *         names
0999             * @exception SQLException if a database access error occurs 
1000             * or this method is called on a closed connection
1001             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1002             * this method
1003             *
1004             * @since 1.4
1005             */
1006            PreparedStatement prepareStatement(String sql, String columnNames[])
1007                    throws SQLException;
1008
1009            /**
1010             * Constructs an object that implements the <code>Clob</code> interface. The object
1011             * returned initially contains no data.  The <code>setAsciiStream</code>,
1012             * <code>setCharacterStream</code> and <code>setString</code> methods of 
1013             * the <code>Clob</code> interface may be used to add data to the <code>Clob</code>.
1014             * @return An object that implements the <code>Clob</code> interface
1015             * @throws SQLException if an object that implements the
1016             * <code>Clob</code> interface can not be constructed, this method is 
1017             * called on a closed connection or a database access error occurs.
1018             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1019             * this data type
1020             *
1021             * @since 1.6
1022             */
1023            Clob createClob() throws SQLException;
1024
1025            /**
1026             * Constructs an object that implements the <code>Blob</code> interface. The object
1027             * returned initially contains no data.  The <code>setBinaryStream</code> and
1028             * <code>setBytes</code> methods of the <code>Blob</code> interface may be used to add data to
1029             * the <code>Blob</code>.
1030             * @return  An object that implements the <code>Blob</code> interface
1031             * @throws SQLException if an object that implements the
1032             * <code>Blob</code> interface can not be constructed, this method is 
1033             * called on a closed connection or a database access error occurs.
1034             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1035             * this data type
1036             *
1037             * @since 1.6
1038             */
1039            Blob createBlob() throws SQLException;
1040
1041            /**
1042             * Constructs an object that implements the <code>NClob</code> interface. The object
1043             * returned initially contains no data.  The <code>setAsciiStream</code>,
1044             * <code>setCharacterStream</code> and <code>setString</code> methods of the <code>NClob</code> interface may
1045             * be used to add data to the <code>NClob</code>.
1046             * @return An object that implements the <code>NClob</code> interface
1047             * @throws SQLException if an object that implements the
1048             * <code>NClob</code> interface can not be constructed, this method is 
1049             * called on a closed connection or a database access error occurs.
1050             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1051             * this data type
1052             *
1053             * @since 1.6
1054             */
1055            NClob createNClob() throws SQLException;
1056
1057            /**
1058             * Constructs an object that implements the <code>SQLXML</code> interface. The object
1059             * returned initially contains no data. The <code>createXmlStreamWriter</code> object and
1060             * <code>setString</code> method of the <code>SQLXML</code> interface may be used to add data to the <code>SQLXML</code>
1061             * object.
1062             * @return An object that implements the <code>SQLXML</code> interface
1063             * @throws SQLException if an object that implements the <code>SQLXML</code> interface can not
1064             * be constructed, this method is 
1065             * called on a closed connection or a database access error occurs.
1066             * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1067             * this data type
1068             * @since 1.6
1069             */
1070            SQLXML createSQLXML() throws SQLException;
1071
1072            /**
1073             * Returns true if the connection has not been closed and is still valid.  
1074             * The driver shall submit a query on the connection or use some other 
1075             * mechanism that positively verifies the connection is still valid when 
1076             * this method is called.
1077             * <p>
1078             * The query submitted by the driver to validate the connection shall be 
1079             * executed in the context of the current transaction.
1080             * 
1081             * @param timeout -		The time in seconds to wait for the database operation 
1082             * 						used to validate the connection to complete.  If 
1083             * 						the timeout period expires before the operation 
1084             * 						completes, this method returns false.  A value of 
1085             * 						0 indicates a timeout is not applied to the 
1086             * 						database operation.
1087             * <p>
1088             * @return true if the connection is valid, false otherwise
1089             * @exception SQLException if the value supplied for <code>timeout</code> 
1090             * is less then 0
1091             * @since 1.6
1092             * <p>
1093             * @see java.sql.DatabaseMetaData#getClientInfoProperties
1094             */
1095            boolean isValid(int timeout) throws SQLException;
1096
1097            /**
1098             * Sets the value of the client info property specified by name to the 
1099             * value specified by value.  
1100             * <p>
1101             * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code> 
1102             * method to determine the client info properties supported by the driver 
1103             * and the maximum length that may be specified for each property.
1104             * <p>
1105             * The driver stores the value specified in a suitable location in the 
1106             * database.  For example in a special register, session parameter, or 
1107             * system table column.  For efficiency the driver may defer setting the 
1108             * value in the database until the next time a statement is executed or 
1109             * prepared.  Other than storing the client information in the appropriate 
1110             * place in the database, these methods shall not alter the behavior of 
1111             * the connection in anyway.  The values supplied to these methods are 
1112             * used for accounting, diagnostics and debugging purposes only.
1113             * <p>
1114             * The driver shall generate a warning if the client info name specified 
1115             * is not recognized by the driver.
1116             * <p>
1117             * If the value specified to this method is greater than the maximum 
1118             * length for the property the driver may either truncate the value and 
1119             * generate a warning or generate a <code>SQLClientInfoException</code>.  If the driver 
1120             * generates a <code>SQLClientInfoException</code>, the value specified was not set on the 
1121             * connection.
1122             * <p>
1123             * The following are standard client info properties.  Drivers are not 
1124             * required to support these properties however if the driver supports a 
1125             * client info property that can be described by one of the standard 
1126             * properties, the standard property name should be used.
1127             * <p>
1128             * <ul>
1129             * <li>ApplicationName	-	The name of the application currently utilizing 
1130             * 							the connection</li>
1131             * <li>ClientUser		-	The name of the user that the application using 
1132             * 							the connection is performing work for.  This may 
1133             * 							not be the same as the user name that was used 
1134             * 							in establishing the connection.</li>
1135             * <li>ClientHostname	-	The hostname of the computer the application 
1136             * 							using the connection is running on.</li>
1137             * </ul>
1138             * <p>
1139             * @param name		The name of the client info property to set 
1140             * @param value		The value to set the client info property to.  If the 
1141             * 					value is null, the current value of the specified
1142             * 					property is cleared.
1143             * <p>
1144             * @throws	SQLClientInfoException if the database server returns an error while 
1145             * 			setting the client info value on the database server or this method 
1146             * is called on a closed connection
1147             * <p>
1148             * @since 1.6	
1149             */
1150            void setClientInfo(String name, String value)
1151                    throws SQLClientInfoException;
1152
1153            /**
1154             * Sets the value of the connection's client info properties.  The 
1155             * <code>Properties</code> object contains the names and values of the client info 
1156             * properties to be set.  The set of client info properties contained in 
1157             * the properties list replaces the current set of client info properties 
1158             * on the connection.  If a property that is currently set on the 
1159             * connection is not present in the properties list, that property is 
1160             * cleared.  Specifying an empty properties list will clear all of the 
1161             * properties on the connection.  See <code>setClientInfo (String, String)</code> for 
1162             * more information.
1163             * <p>  
1164             * If an error occurs in setting any of the client info properties, a 
1165             * <code>SQLClientInfoException</code> is thrown. The <code>SQLClientInfoException</code>
1166             * contains information indicating which client info properties were not set. 
1167             * The state of the client information is unknown because 
1168             * some databases do not allow multiple client info properties to be set 
1169             * atomically.  For those databases, one or more properties may have been 
1170             * set before the error occurred.
1171             * <p>
1172             * 
1173             * @param properties		the list of client info properties to set
1174             * <p>
1175             * @see java.sql.Connection#setClientInfo(String, String) setClientInfo(String, String)
1176             * @since 1.6
1177             * <p>
1178             * @throws SQLClientInfoException if the database server returns an error while 
1179             * 			setting the clientInfo values on the database server or this method 
1180             * is called on a closed connection 
1181             * <p>
1182             */
1183            void setClientInfo(Properties properties)
1184                    throws SQLClientInfoException;
1185
1186            /**
1187             * Returns the value of the client info property specified by name.  This 
1188             * method may return null if the specified client info property has not 
1189             * been set and does not have a default value.  This method will also 
1190             * return null if the specified client info property name is not supported 
1191             * by the driver.
1192             * <p>
1193             * Applications may use the <code>DatabaseMetaData.getClientInfoProperties</code>
1194             * method to determine the client info properties supported by the driver.
1195             * <p>
1196             * @param name		The name of the client info property to retrieve
1197             * <p>
1198             * @return 			The value of the client info property specified
1199             * <p>
1200             * @throws SQLException		if the database server returns an error when 
1201             * 							fetching the client info value from the database 
1202             *or this method is called on a closed connection
1203             * <p>
1204             * @since 1.6
1205             * <p>
1206             * @see java.sql.DatabaseMetaData#getClientInfoProperties
1207             */
1208            String getClientInfo(String name) throws SQLException;
1209
1210            /**
1211             * Returns a list containing the name and current value of each client info 
1212             * property supported by the driver.  The value of a client info property 
1213             * may be null if the property has not been set and does not have a 
1214             * default value.
1215             * <p>
1216             * @return	A <code>Properties</code> object that contains the name and current value of 
1217             * 			each of the client info properties supported by the driver.  
1218             * <p>
1219             * @throws 	SQLException if the database server returns an error when 
1220             * 			fetching the client info values from the database
1221             * or this method is called on a closed connection
1222             * <p>
1223             * @since 1.6
1224             */
1225            Properties getClientInfo() throws SQLException;
1226
1227            /**
1228             * Factory method for creating Array objects.
1229             *<p>
1230             * <b>Note: </b>When <code>createArrayOf</code> is used to create an array object 
1231             * that maps to a primitive data type, then it is implementation-defined 
1232             * whether the <code>Array</code> object is an array of that primitive 
1233             * data type or an array of <code>Object</code>.
1234             * <p>
1235             * <b>Note: </b>The JDBC driver is responsible for mapping the elements 
1236             * <code>Object</code> array to the default JDBC SQL type defined in 
1237             * java.sql.Types for the given class of <code>Object</code>. The default 
1238             * mapping is specified in Appendix B of the JDBC specification.  If the
1239             * resulting JDBC type is not the appropriate type for the given typeName then 
1240             * it is implementation defined whether an <code>SQLException</code> is 
1241             * thrown or the driver supports the resulting conversion.
1242             *
1243             * @param typeName the SQL name of the type the elements of the array map to. The typeName is a
1244             * database-specific name which may be the name of a built-in type, a user-defined type or a standard  SQL type supported by this database. This
1245             *  is the value returned by <code>Array.getBaseTypeName</code>
1246             * @param elements the elements that populate the returned object
1247             * @return an Array object whose elements map to the specified SQL type
1248             * @throws SQLException if a database error occurs, the JDBC type is not
1249             *  appropriate for the typeName and the conversion is not supported, the typeName is null or this method is called on a closed connection
1250             * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this data type
1251             * @since 1.6
1252             */
1253            Array createArrayOf(String typeName, Object[] elements)
1254                    throws SQLException;
1255
1256            /**
1257             * Factory method for creating Struct objects.
1258             *
1259             * @param typeName the SQL type name of the SQL structured type that this <code>Struct</code> 
1260             * object maps to. The typeName is the name of  a user-defined type that
1261             * has been defined for this database. It is the value returned by
1262             * <code>Struct.getSQLTypeName</code>.
1263            
1264             * @param attributes the attributes that populate the returned object
1265             *  @return a Struct object that maps to the given SQL type and is populated with the given attributes
1266             * @throws SQLException if a database error occurs, the typeName is null or this method is called on a closed connection
1267             * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this data type
1268             * @since 1.6
1269             */
1270            Struct createStruct(String typeName, Object[] attributes)
1271                    throws SQLException;
1272        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.