jdbcconnection.java

纯Java的数据库

 * and/or data corruption. <p>
 *
 * In short, a <b>res:</b> type database connection <b>&lt;url&gt;</b> is
 * designed specifically to connect to a <b>'files_in_jar'</b> mode database
 * instance, which in turn is designed specifically to operate under
 * <em>Java WebStart</em><sup><font size="-2">TM</font></sup> and
 * <em>Java Applet</em><sup><font size="-2">TM</font></sup>configurations,
 * where co-locating the database files in the jars that make up the
 * <em>WebStart</em> application or Applet avoids the need for special security
 * configuration or code signing. <p>
 *
 * <b>Note:</b> Since it is difficult and often nearly impossible to determine
 * or control at runtime from where all classes are being loaded or which class
 * loader is doing the loading under <b>'files_in_jar'</b> semantics, the
 * <b>&lt;path&gt;</b> component of the res: database connection
 * <b>&lt;url&gt;</b> is always taken to be relative to the default package.
 * That is, if the <b>&lt;path&gt;</b> component does not start with '/', then
 * '/' is prepended when obtaining the resource URLs used to read the database
 * files. <p>
 *
 * <hr>
 *
 * For more information about HSQLDB file structure, various database modes
 * and other attributes such as those controlled through the HSQLDB properties
 * files, please read the general documentation, especially the Advanced Users
 * Guide. <p>
 *
 * <hr>
 *
 * <b>JRE 1.1.x Notes:</b> <p>
 *
 * In general, JDBC 2 support requires Java 1.2 and above, and JDBC3 requires
 * Java 1.4 and above. In HSQLDB, support for methods introduced in different
 * versions of JDBC depends on the JDK version used for compiling and building
 * HSQLDB.<p>
 *
 * Since 1.7.0, it is possible to build the product so that
 * all JDBC 2 methods can be called while executing under the version 1.1.x
 * <em>Java Runtime Environment</em><sup><font size="-2">TM</font></sup>.
 * However, in addition to this technique requiring explicit casts to the
 * org.hsqldb.jdbcXXX classes, some of the method calls also require
 * <code>int</code> values that are defined only in the JDBC 2 or greater
 * version of
 * <a href="http://java.sun.com/j2se/1.4/docs/api/java/sql/ResultSet.html">
 * <code>ResultSet</code></a> interface.  For this reason, when the
 * product is compiled under JDK 1.1.x, these values are defined
 * in {@link org.hsqldb.jdbc.jdbcResultSet jdbcResultSet}. <p>
 *
 * In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the
 * JDBC2-only <code>ResultSet</code> values can be achieved by referring
 * to them in parameter specifications and return value comparisons,
 * respectively, as follows: <p>
 *
 * <pre class="JavaCodeExample">
 * jdbcResultSet.FETCH_FORWARD
 * jdbcResultSet.TYPE_FORWARD_ONLY
 * jdbcResultSet.TYPE_SCROLL_INSENSITIVE
 * jdbcResultSet.CONCUR_READ_ONLY
 * // etc.
 * </pre>
 *
 * However, please note that code written to use HSQLDB JDBC 2 features under
 * JDK 1.1.x will not be compatible for use with other JDBC 2 drivers. Please
 * also note that this feature is offered solely as a convenience to developers
 * who must work under JDK 1.1.x due to operating constraints, yet wish to
 * use some of the more advanced features available under the JDBC 2
 * specification. <p>
 *
 * <hr>
 *
 * (fredt@users)<br>
 * (boucherb@users)<p>
 *
 * </div> <!-- end release-specific documentation -->
 * @author boucherb@users
 * @author fredt@users
 * @version 1.7.2
 * @see org.hsqldb.jdbcDriver
 * @see jdbcStatement
 * @see jdbcPreparedStatement
 * @see jdbcCallableStatement
 * @see jdbcResultSet
 * @see jdbcDatabaseMetaData
 */
public class jdbcConnection implements Connection {

// ---------------------------- Common Attributes --------------------------

    /**
     * Properties for the connection
     *
     */
    HsqlProperties connProperties;

    /**
     * This connection's interface to the corresponding Session
     * object in the database engine.
     */
    SessionInterface sessionProxy;

    /**
     * Is this an internal connection?
     */
    boolean isInternal;

    /** Is this connection to a network server instance. */
    protected boolean isNetConn;

    /**
     * Is this connection closed?
     */
    boolean isClosed;

    /** The first warning in the chain. Null if there are no warnings. */
    private SQLWarning rootWarning;

    /** Synchronizes concurrent modification of the warning chain */
    private Object rootWarning_mutex = new Object();

    /**
     * The set of open Statement objects returned by this Connection from
     * calls to createStatement, prepareCall and prepareStatement. This is
     * used solely for closing the statements when this Connection is closed.
     */
    /*
    private org.hsqldb.lib.HashSet statementSet =
        new org.hsqldb.lib.HashSet();
     */

// ----------------------------------- JDBC 1 -------------------------------

    /**
     * <!-- start generic documentation -->
     * Creates a <code>Statement</code>
     * object for sending SQL statements to the database. SQL
     * statements without parameters are normally executed using
     * <code>Statement</code> objects. If the same SQL statement is
     * executed many times, it may be more efficient to use a
     * <code>PreparedStatement</code> object.<p>
     *
     * Result sets created using the returned <code>Statement</code>
     * object will by default be type <code>TYPE_FORWARD_ONLY</code>
     * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <div class="ReleaseSpecificDocumentation">
     * <h3>HSQLDB-Specific Information:</h3> <p>
     *
     * Starting with HSQLDB 1.7.2, support for precompilation at the engine level
     * has been implemented, so it is now much more efficient and performant
     * to use a <code>PreparedStatement</code> object if the same SQL statement
     * is executed many times. <p>
     *
     * Up to 1.6.1, HSQLDB supported <code>TYPE_FORWARD_ONLY</code> -
     * <code>CONCUR_READ_ONLY</code> results only, so <code>ResultSet</code>
     * objects created using the returned <code>Statement</code>
     * object would <I>always</I> be type <code>TYPE_FORWARD_ONLY</code>
     * with <code>CONCUR_READ_ONLY</code> concurrency. <p>
     *
     * Starting with 1.7.0, HSQLDB also supports
     * <code>TYPE_SCROLL_INSENSITIVE</code> results. <p>
     *
     * <b>Notes:</b> <p>
     *
     * Up to 1.6.1, calling this method returned <code>null</code> if the
     * connection was already closed. This was possibly counter-intuitive
     * to the expectation that an exception would be thrown for
     * closed connections. Starting with 1.7.0. the behaviour is to throw a
     * <code>SQLException</code> if the connection is closed. <p>
     *
     * </div> <!-- end release-specific documentation -->
     *
     * @return a new default Statement object
     * @throws SQLException if a database access error occurs<p>
     * @see #createStatement(int,int)
     * @see #createStatement(int,int,int)
     */
    public synchronized Statement createStatement() throws SQLException {

        checkClosed();

        Statement stmt = new jdbcStatement(this,
                                           jdbcResultSet.TYPE_FORWARD_ONLY);

        return stmt;
    }

    /**
     * <!-- start generic documentation -->
     * Creates a <code>PreparedStatement</code>
     * object for sending parameterized SQL statements to the
     * database. <p>
     *
     * A SQL statement with or without IN parameters can be
     * pre-compiled and stored in a <code>PreparedStatement</code>
     * object. This object can then be used to efficiently execute
     * this statement multiple times. <p>
     *
     * <B>Note:</B> This method is optimized for handling parametric
     * SQL statements that benefit from precompilation. If the driver
     * supports precompilation, the method <code>prepareStatement</code>
     * will send the statement to the database for precompilation.
     * Some drivers may not support precompilation. In this case, the
     * statement may not be sent to the database until the
     * <code>PreparedStatement</code> object is executed. This has no
     * direct effect on users; however, it does affect which methods
     * throw certain <code>SQLException</code> objects.<p>
     *
     * Result sets created using the returned <code>PreparedStatement</code>
     * object will by default be type <code>TYPE_FORWARD_ONLY</code>
     * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <div class="ReleaseSpecificDocumentation">
     * <h3>HSQLDB-Specific Information:</h3> <p>
     *
     * Starting with HSQLDB 1.7.2, support for precompilation at the engine level
     * has been implemented, so it is now much more efficient and performant
     * to use a <code>PreparedStatement</code> object if the same SQL statement
     * is executed many times. <p>
     *
     * Starting with 1.7.2, the support for and behaviour of
     * PreparedStatment has changed.  Please read the introductory section
     * of the documentation for org.hsqldb.jdbc.jdbcPreparedStatement. <P>
     *
     * </div> <!-- end release-specific documentation -->
     *
     * @param sql an SQL statement that may contain one or more '?'
     *    IN parameter placeholders
     * @return a new default <code>PreparedStatement</code> object
     *    containing the pre-compiled SQL statement
     * @exception SQLException if a database access error occurs <p>
     * @see #prepareStatement(String,int,int)
     */
    public synchronized PreparedStatement prepareStatement(String sql)
    throws SQLException {

        PreparedStatement stmt;

        checkClosed();

        try {
            stmt = new jdbcPreparedStatement(this, sql,
                                             jdbcResultSet.TYPE_FORWARD_ONLY);

            return stmt;
        } catch (HsqlException e) {
            throw Util.sqlException(e);
        }
    }

    /**
     * <!-- start generic documentation -->
     * Creates a <code>CallableStatement</code>
     * object for calling database stored procedures. The
     * <code>CallableStatement</code> object provides methods for setting up
     * its IN and OUT  parameters, and methods for executing the call to a
     * stored procedure. <p>
     *
     * <b>Note:</b> This method is optimized for handling stored
     * procedure call statements. Some drivers may send the call
     * statement to the database when the method <code>prepareCall</code>
     * is done; others may wait until the <code>CallableStatement</code>
     * object is executed. This has no direct effect on users;
     * however, it does affect which method throws certain
     * SQLExceptions. <p>
     *
     * Result sets created using the returned <code>CallableStatement</code>
     * object will by default be type <code>TYPE_FORWARD_ONLY</code>
     * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.<p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <div class="ReleaseSpecificDocumentation">
     * <h3>HSQLDB-Specific Information:</h3> <p>
     *
     * Starting with 1.7.2, the support for and behaviour of
     * CallableStatement has changed.  Please read the introductory section
     * of the documentation for org.hsqldb.jdbc.jdbcCallableStatement.
     *
     * </div> <!-- end release-specific documentation -->
     *
     * @param sql a String object that is the SQL statement to be
     *  sent to the database; may contain one or more ?
     *  parameters. <p>
     *
     *  <B>Note:</B> Typically the SQL statement is a JDBC
     *  function call escape string.
     * @return a new default <code>CallableStatement</code> object
     *  containing the pre-compiled SQL statement
     * @exception SQLException if a database access error occurs <p>
     * @see #prepareCall(String,int,int)
     */
    public synchronized CallableStatement prepareCall(String sql)
    throws SQLException {

        CallableStatement stmt;

        checkClosed();

        try {
            stmt = new jdbcCallableStatement(this, sql,
                                             jdbcResultSet.TYPE_FORWARD_ONLY);

            return stmt;
        } catch (HsqlException e) {
            throw Util.sqlException(e);
        }
    }

    /**
     * <!-- start generic documentation -->
     * Converts the given SQL statement
     * into the system's native SQL grammar. A driver may convert the
     * JDBC SQL grammar into its system's native SQL grammar prior to
     * sending it. This method returns the native form of the
     * statement that the driver would have sent. <p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <div class="ReleaseSpecificDocumentation">
     * <h3>HSQLDB-Specific Information:</h3> <p>
     *
     * Up to and including 1.7.2, HSQLDB converts the JDBC SQL
     * grammar into the system's native SQL grammar prior to sending
     * it, if escape processing is set true; this method returns the
     * native form of the statement that the driver would send in place
     * of client-specified JDBC SQL grammar. <p>
     *
     * Before 1.7.2, escape processing was incomplete and
     * also broken in terms of support for nested escapes. <p>
     *
     * Starting with 1.7.2, escape processing is complete and handles nesting