jdbcconnection.java

一个用java写的开源的数据库系统

     * object's database and JDBC resources immediately instead of
     * waiting for them to be automatically released.<p>
     *
     * Calling the method <code>close</code> on a <code>Connection</code>
     * object that is already closed is a no-op. <p>
     *
     * <B>Note:</B> A <code>Connection</code> object is automatically
     * closed when it is garbage collected. Certain fatal errors also
     * close a <code>Connection</code> object. <p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <span class="ReleaseSpecificDocumentation">
     * <b>HSQLDB-Specific Information:</b> <p>
     *
     * In a future release, <code>INTERNAL</code> <code>Connection</code>
     * objects may not be closable from JDBC client code, and disconnect
     * statements issued on <code>INTERNAL</code> <code>Connection</code>
     * objects may be ignored. <p>
     *
     * For HSQLDB developers not involved with writing database
     * internals, this change will only apply to connections obtained
     * automatically from the database as the first parameter to
     * stored procedures and SQL functions. This is mainly an issue
     * to developers writing custom SQL function and stored procedure
     * libraries for HSQLDB. As we anticipate this change, it is
     * recommended that SQL function and stored procedure code avoid
     * depending on closing or issuing a disconnect on a connection
     * obtained in this manner. <p>
     *
     * </span> <!-- end release-specific documentation -->
     *
     * @exception SQLException if a database access error occurs
     */
    public void close() throws SQLException {

        if (Trace.TRACE) {
            Trace.trace();
        }

        if (iType == INTERNAL) {
            return;
        }

        if (bClosed) {
            return;
        }

        // FIXME:
        // closeStandalone() should only get called for STANDALONE
        // calling close on an internal connection should do nothing
        // Internal connections should not execute DISCONNECT or set
        // bClosed true
        // Only one instance of internal connection should exist for
        // each Session, and it should be open for the life of
        // its Session
        // boucherb@users 20020409
// fredt - patch 1.7.1 - implemented the above
        if (iType == STANDALONE) {
            closeStandalone();
        } else {
            execute("DISCONNECT");
        }

        bClosed = true;
    }

    /**
     *  Tests to see if a Connection is closed.
     *
     * @return  true if the connection is closed; false if it's still
     *      open
     */
    public boolean isClosed() {

        if (Trace.TRACE) {
            Trace.trace();
        }

        return bClosed;
    }

    /**
     * <!-- start generic documentation -->
     * Gets the metadata regarding this connection's database.
     * A Connection's database is able to  provide information describing
     * its tables, its supported SQL grammar, its stored procedures,
     * the capabilities of this connection, and so on. This information
     * is made available through a <code>DatabaseMetaData</code> object. <p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <span class="ReleaseSpecificDocumentation">
     * <b>HSQLDB-Specific Information:</b> <p>
     *
     * Up to and including 1.7.1, HSQLDB does not provide accurate
     * results for the full range of <code>DatabaseMetaData</code>
     * methods returning <code>ResultSet</code>. Some of these
     * methods may always return empty result sets, even though they
     * should contain information. Other methods may not accurately
     * reflect all of the MetaData for the category they report on.
     * Also, some methods may ignore the filters provided as
     * parameters, returning an unfiltered result each time. <p>
     *
     * As of version 1.7.1, the only completely accurate
     * <code>DatabaseMetaData</code>
     * methods returning <code>ResultSet</code> are {@link
     * jdbcDatabaseMetaData#getTables getTables},
     * {@link jdbcDatabaseMetaData#getColumns getColumns},
     * {@link jdbcDatabaseMetaData#getColumns getPrimaryKeys},
     * and {@link jdbcDatabaseMetaData#getIndexInfo getIndexInfo}.
     * Also, the
     * majority of methods returning <code>ResultSet</code> throw a
     * <code>SQLException</code> when accessed by a non-admin user.
     * In order to provide non-admin users access to these methods,
     * an admin user must explicitly grant SELECT to such users or to
     * the PUBLIC user on each HSQLDB system table corresponding to a
     * DatabaseMetaData method that returns <code>ResultSet</code>.
     * For example, to provide access to {@link
     * jdbcDatabaseMetaData#getTables getTables} to all users, the
     * following must be issued by an admin user:<p>
     *
     * <code class = "JavaCodeExample">
     * GRANT SELECT ON SYSTEM_TABLES TO PUBLIC
     * </code> <p>
     *
     * Care should be taken when making such grants, however, since
     * HSQLDB makes no attempt to filter such information, based on
     * the grants of the accessing user. That is, in the example
     * above, getTables will return information about all tables
     * (except system tables, which are never listed in MetaData),
     * regardless of whether the calling user has any rights on any
     * of the tables. <p>
     *
     * HSQLDB 1.7.1 will provide the option of installing a full and
     * accurate <code>DatabaseMetaData</code> implementation that is
     * accessible to all database users, regardless of admin status.
     * In that implementation, <code>DatabaseMetaData</code> methods
     * returning <code>ResultSet</code> will yield results that have
     * been automatically pre-filtered to omit entries to which the
     * connected user has not been granted access, regardless of the
     * filter parameters specified to those methods. That is,
     * supplied filter parameters will only further restrict results
     * that already comply with the security set up by
     * administration, and will never give greater access than has
     * been granted. Also in that implementation, full MetaData will
     * be reported to all users about all system tables, unless
     * SELECT on any system table providing <code>DatabaseMetaData</code>
     * is specifically revoked from PUBLIC and not explicitly granted
     * to each user. <p>
     *
     * </span> <!-- end release-specific documentation -->
     *
     * @return a DatabaseMetaData object for this Connection
     * @see jdbcDatabaseMetaData
     */
    public DatabaseMetaData getMetaData() {

        if (Trace.TRACE) {
            Trace.trace();
        }

        return new jdbcDatabaseMetaData(this);
    }

    /**
     * <!-- start generic documentation -->
     * Puts this connection in read-only mode as a hint to enable
     * database optimizations. <p>
     *
     * <B>Note:</B> This method should not be called while in the
     * middle of a transaction. <p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <span class="ReleaseSpecificDocumentation">
     * <b>HSQLDB-Specific Information:</b> <p>
     *
     * Up to and including 1.7.1, HSQLDB will commit the current
     * transaction automatically when this method is called. <p>
     *
     * Additionally, HSQLDB provides a way to put a whole database in
     * read-only mode. This is done by manually adding the line
     * 'readonly=true' to the database's .properties file while the
     * database is offline. Upon restart, all connections will be
     * readonly, since the entire database will be readonly. To take
     * a database out of readonly mode, simply take the database
     * offline and remove the line 'readonly=true' from the
     * database's .properties file. Upon restart, the database will
     * be in regular (read-write) mode. <p>
     *
     * When a database is put in readonly mode, its files are opened
     * in readonly mode, making it possible to create CDROM-based
     * readonly databases. To create a CDROM-based readonly database
     * that has CACHED tables and whose .data file is suspected of
     * being highly fragmented, it is recommended that the database
     * first be SHUTDOWN COMPACTed, taken off-line, restarted,
     * SHUTDOWN and taken off-line again before copying the database
     * files to CDROM. This will reduce the space required and may
     * improve access times against the .data file which holds the
     * CACHED table data. <p>
     *
     * </span> <!-- end release-specific documentation -->
     *
     * @param readonly The new readOnly value
     * @exception SQLException if a database access error occurs
     */
    public void setReadOnly(boolean readonly) throws SQLException {
        execute("SET READONLY " + (readonly ? "TRUE"
                                            : "FALSE"));
    }

    /**
     *  Tests to see if the connection is in read-only mode.
     *
     * @return  true if connection is read-only and false otherwise
     * @exception  SQLException if a database access error occurs
     */
    public boolean isReadOnly() throws SQLException {

        String s = "SELECT * FROM SYSTEM_CONNECTIONINFO WHERE KEY='READONLY'";
        ResultSet r = execute(s);

        r.next();

        return r.getString(2).equals("TRUE");
    }

    /**
     * <!-- start generic documentation -->
     * Sets a catalog name in order to
     * select a subspace of this Connection's database in which to
     * work. <p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <span class="ReleaseSpecificDocumentation">
     * <b>HSQLDB-Specific Information:</b> <p>
     *
     * HSQLDB does not yet support catalogs and simply ignores this
     * request. <p>
     * </span>
     * <!-- end release-specific documentation -->
     *
     * @param catalog the name of a catalog (subspace in this
     *     Connection object's database) in which to work (Ignored)
     * @throws SQLException if a database access error occurs <p>
     */
    public void setCatalog(String catalog) throws SQLException {

        if (Trace.TRACE) {
            Trace.trace(catalog);
        }
    }

    /**
     * <!-- start generic documentation -->
     * Returns the Connection's current catalog name. <p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <span class="ReleaseSpecificDocumentation">
     * <b>HSQLDB-Specific Information:</b> <p>
     *
     * HSQLDB does not yet support catalogs and always returns null.
     * <p>
     *
     * </span> <!-- end release-specific documentation -->
     *
     * @return the current catalog name or null <p>
     *
     *     For HSQLDB, this is always null.
     * @exception SQLException Description of the Exception
     */
    public String getCatalog() throws SQLException {

        if (Trace.TRACE) {
            Trace.trace();
        }

        checkClosed();

        return null;
    }

    /**
     * <!-- start generic documentation -->
     * Attempts to change the transaction isolation level for this
     * <code>Connection</code> object to the one given. The constants
     * defined in the interface <code>Connection</code> are the
     * possible transaction isolation levels. <p>
     *
     * <B>Note:</B> If this method is called during a transaction,
     * the result is implementation-defined. <p>
     *
     * <!-- end generic documentation -->
     * <!-- start release-specific documentation -->
     * <span class="ReleaseSpecificDocumentation">
     * <b>HSQLDB-Specific Information:</b> <p>
     *
     * Up to and including 1.7.1, HSQLDB supports only
     * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>. <p>
     *
     * </span> <!-- end release-specific documentation -->
     *
     * @param level one of the following <code>Connection</code>
     *     constants: <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>
     *     , <code>Connection.TRANSACTION_READ_COMMITTED</code>,
     *     <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
     *     <code>Connection.TRANSACTION_SERIALIZABLE</code>. (Note
     *     that <code>Connection.TRANSACTION_NONE</code> cannot be
     *     used because it specifies that transactions are not
     *     supported.)
     * @exception SQLException if a database access error occurs or
     *     the given parameter is not one of the <code>Connection</code>
     *     constants <p>
     * @see jdbcDatabaseMetaData#supportsTransactionIsolationLevel
     * @see #getTransactionIsolation
     */
    public void setTransactionIsolation(int level) throws SQLException {

        if (Trace.TRACE) {
            Trace.trace(level);
        }

        if (level != Connection.TRANSACTION_READ_UNCOMMITTED) {
            throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED);
        }

        checkClosed();
    }