Package org.hsqldb.jdbc

Examples of org.hsqldb.jdbc.jdbcConnection

The {@link org.hsqldb.server.WebServer WebServer} database connection <url>takes one of two following forms:

  1. 'jdbc:hsqldb:http://host[:port][/<alias>][<key-value-pairs>]'
  2. 'jdbc:hsqldb:https://host[:port][/<alias>][<key-value-pairs>]' (with TLS).

In both network server database connection <url> forms, the optional <alias> component is used to identify one of possibly several database instances available at the indicated host and port. If the <alias> component is omitted, then a connection is made to the network server's default database instance, if such an instance is available.

For more information on server configuration regarding mounting multiple databases and assigning them <alias> values, please read the Java API documentation for {@link org.hsqldb.server.Server Server} and relatedchapters in the general documentation, especially the Advanced Users Guide.

Transient, In-Process Database Connections:

The 100% in-memory (transient, in-process) database connection <url> takes one of the two following forms:

  1. 'jdbc:hsqldb:.[<key-value-pairs>]' (the legacy form, extended)
  2. 'jdbc:hsqldb:mem:<alias>[<key-value-pairs>]' (the new form)

The driver converts the supplied <alias> component to Local.ENGLISH lower case and uses the resulting character sequence as the key used to look up a mem: protocol database instance amongst the collection of all such instances already in existence within the current class loading context in the current JVM. If no such instance exists, one may be automatically created and mapped to the <alias>, as governed by the 'ifexists=true|false' connection property.

The rationale for converting the supplied <alias> component to lower case is to provide consistency with the behavior of res: protocol database connection <url>s, explained further on in this overview.

Persistent, In-Process Database Connections:

The standalone (persistent, in-process) database connection <url> takes one of the three following forms:

  1. 'jdbc:hsqldb:<path>[<key-value-pairs>]' (the legacy form, extended)
  2. 'jdbc:hsqldb:file:<path>[<key-value-pairs>]' (same semantics as the legacy form)
  3. 'jdbc:hsqldb:res:<path>[<key-value-pairs>]' (new form with 'files_in_jar' semantics)

For the persistent, in-process database connection <url>, the <path> component is the path prefix common to all of the files that compose the database.

From 1.7.2, although other files may be involved (such as transient working files and/or TEXT table CSV data source files), the essential set that may, at any particular point in time, compose an HSQLDB database is:

For example: 'jdbc:hsqldb:file:test' connects to a database composed of some subset of the files listed above, where the expansion of <path> is 'test' prefixed with the canonical path of the JVM's effective working directory at the time the designated database is first opened in-process.

Be careful to note that this canonical expansion of <path> is cached by the driver until JVM exit. So, although legacy JVMs tend to fix the reported effective working directory at the one noted upon JVM startup, there is no guarantee that modern JVMs will continue to uphold this behaviour. What this means is there is effectively no guarantee into the future that a relative file: protocol database connection <url> will connect to the same database instance for the life of the JVM. To avoid any future ambigutity issues, it is probably a best practice for clients to attempt to pre-canonicalize the <path> component of file: protocol database connection* <url>s.

Under Windows TM , 'jdbc:hsqldb:file:c:\databases\test' connects to a database located on drive 'C:' in the directory 'databases', composed of some subset of the files: 

 C:\ +--databases\ +--test.properties +--test.script +--test.log +--test.data +--test.backup +--test.lck
Under most variations of UNIX, 'jdbc:hsqldb:file:/databases/test' connects to a database located in the directory 'databases' directly under root, once again composed of some subset of the files: 

 +--databases +--test.properties +--test.script +--test.log +--test.data +--test.backup +--test.lck
Some Guidelines:

  1. Both relative and absolute database file paths are supported.

  2. Relative database file paths can be specified in a platform independent manner as: '[dir1/dir2/.../dirn/]<file-name-prefix>'.

  3. Specification of absolute file paths is operating-system specific.
    Please read your OS file system documentation.

  4. Specification of network mounts may be operating-system specific.
    Please read your OS file system documentation.

  5. Special care may be needed w.r.t. file path specifications containing whitespace, mixed-case, special characters and/or reserved file names.
    Please read your OS file system documentation.

Note: Versions of HSQLDB previous to 1.7.0 did not support creating directories along the file path specified in the persistent, in-process mode database connection <url> form, in the case that they did not already exist. Starting with HSQLDB 1.7.0, directories will be created if they do not already exist., but only if HSQLDB is built under a version of the compiler greater than JDK 1.1.x.

res: protocol Connections:

The 'jdbc:hsqldb:res:<path>' database connection <url> has different semantics than the 'jdbc:hsqldb:file:<path>' form. The semantics are similar to those of a 'files_readonly' database, but with some additional points to consider.

Specifically, the '<path>' component of a res: protocol database connection <url> is first converted to lower case with Locale.ENGLISH and only then used to obtain resource URL objects, which in turn are used to read the database files as resources on the class path.

Due to lower case conversion by the driver, res: '<path>' components never find jar resources stored with Locale.ENGLISH mixed case paths. The rationale for converting to lower case is that not all pkzip implementations guarantee path case is preserved when archiving resources, and conversion to lower case seems to be the most common occurrence (although there is also no actual guarantee that the conversion is Locale.ENGLISH).

More importantly, res: '<path>' components must point only to resources contained in one or more jars on the class path. That is, only resources having the jar sub-protocol are considered valid.

This restriction is enforced to avoid the unfortunate situation in which, because res: database instances do not create a <path>.lck file (they are strictly files-read-only) and because the <path> components of res: and file: database URIs are not checked for file system equivalence, it is possible for the same database files to be accessed concurrently by both file: and res: database instances. That is, without this restriction, it is possible that <path>.data and <path>.properties file content may be written by a file: database instance without the knowlege or cooperation of a res: database instance open on the same files, potentially resulting in unexpected database errors, inconsistent operation and/or data corruption.

In short, a res: type database connection <url> is designed specifically to connect to a 'files_in_jar' mode database instance, which in turn is designed specifically to operate under Java WebStartTM and Java AppletTMconfigurations, where co-locating the database files in the jars that make up the WebStart application or Applet avoids the need for special security configuration or code signing.

Note: 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 (and hence how relative path specifications are resolved) under 'files_in_jar' semantics, the <path> component of the res: database connection <url> is always taken to be relative to the default package and resource URL resolution is always performed using the ClassLoader that loads the org.hsqldb.persist.Logger class. That is, if the <path> component does not start with '/', then'/' is prepended when obtaining the resource URLs used to read the database files, and only the effective class path of org.hsqldb.persist.Logger's ClassLoader is searched.

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.

JRE 1.1.x Notes:

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.

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 Java Runtime EnvironmentTM. However, in addition to this technique requiring explicit casts to the org.hsqldb.jdbc.* classes, some of the method calls also require int values that are defined only in the JDBC 2 or greater version of the {@link java.sql.ResultSet ResultSet} interface. For thisreason, when the product is compiled under JDK 1.1.x, these values are defined in {@link JDBCResultSet JDBCResultSet}.

In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the JDBC 2+ ResultSet values can be achieved by referring to them in parameter specifications and return value comparisons, respectively, as follows: 

 JDBCResultSet.FETCH_FORWARD JDBCResultSet.TYPE_FORWARD_ONLY JDBCResultSet.TYPE_SCROLL_INSENSITIVE JDBCResultSet.CONCUR_READ_ONLY // etc.
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.

JDBC 4.0 Notes:

Starting with JDBC 4.0 (JDK 1.6), the DriverManager methods getConnection and getDrivers have been enhanced to support the Java Standard Edition Service Provider mechanism. When built under a Java runtime that supports JDBC 4.0, HSQLDB distribution jars containing the Driver implementatiton also include the file META-INF/services/java.sql.Driver. This file contains the fully qualified class name ('org.hsqldb.jdbc.JDBCDriver') of the HSQLDB implementation of java.sql.Driver.

Hence, under JDBC 4.0 or greater, applications no longer need to explictly load the HSQLDB JDBC driver using Class.forName(). Of course, existing programs which do load JDBC drivers using Class.forName() will continue to work without modification.

(fredt@users)
(boucherb@users)

@author Campbell Boucher-Burnett (boucherb@users dot sourceforge.net) @author Fred Toussi (fredt@users dot sourceforge.net) @version 2.0 @revised JDK 1.6, HSQLDB 2.0 @see JDBCDriver @see JDBCStatement @see JDBCParameterMetaData @see JDBCCallableStatement @see JDBCResultSet @see JDBCDatabaseMetaData @see java.sql.DriverManager#getConnection @see java.sql.Statement @see java.sql.ResultSet @see java.sql.DatabaseMetaData

137
138
139
140
141
142
143
144
145
146
147
        } catch (InstantiationException e) {
            throw new SQLException("Error opening connection: "
                                   + e.getMessage());
        }

        JDBCConnection connection =
            (JDBCConnection) DriverManager.getConnection(url, connProperties);

        // Comment out before public release:
/*
        System.err.print("New phys:  " + connection);
View Full Code Here
147
148
149
150
151
152
153
154
155
156
        } catch (InstantiationException e) {
            throw new SQLException("Error opening connection: "
                                   + e.getMessage());
        }

        JDBCConnection connection =
            (JDBCConnection) DriverManager.getConnection(url, connProperties);

        return createPooledConnection(connection);
    }
View Full Code Here
147
148
149
150
151
152
153
154
155
156
        } catch (InstantiationException e) {
            throw new SQLException("Error opening connection: "
                                   + e.getMessage());
        }

        JDBCConnection connection =
            (JDBCConnection) DriverManager.getConnection(url, connProperties);

        return createPooledConnection(connection);
    }
View Full Code Here
817
818
819
820
821
822
823
824
825
826
     * @return  internal connection.
     */
    JDBCConnection getInternalConnection() {

        if (intConnection == null) {
            intConnection = new JDBCConnection(this);
        }

        return intConnection;
    }
View Full Code Here
68
69
70
71
72
73
74
75
76
77
//#endif JAVA6
{

    public PooledConnection getPooledConnection() throws SQLException {

        JDBCConnection connection =
            (JDBCConnection) JDBCDriver.getConnection(url, connectionProps);

        return new JDBCPooledConnection(connection);
    }
View Full Code Here
82
83
84
85
86
87
88
89
90
91
        Properties props = new Properties();

        props.setProperty("user", user);
        props.setProperty("password", password);

        JDBCConnection connection =
            (JDBCConnection) JDBCDriver.getConnection(url, props);

        return new JDBCPooledConnection(connection);
    }
View Full Code Here
74
75
76
77
78
79
80
81
82
            throw new SQLException("Connection in use");
        }

        isInUse = true;

        userConnection = new JDBCConnection(connection, this);

        return userConnection;
    }
View Full Code Here
95
96
97
98
99
100
101
102
103
104
105
        System.err.print("Executing " + getClass().getName()
                         + ".getXAConnection()...");
*/

        // Use JDBCDriver directly so there is no need to regiser with DriverManager
        JDBCConnection connection =
            (JDBCConnection) JDBCDriver.getConnection(url, connectionProps);
        JDBCXAConnection xaConnection = new JDBCXAConnection(this, connection);

        return xaConnection;
    }
View Full Code Here
847
848
849
850
851
852
853
854
855
856
857
     * @return  internal connection.
     */
    JDBCConnection getInternalConnection() {

        if (intConnection == null) {
            intConnection = new JDBCConnection(this);
        }

        JDBCDriver.driverInstance.threadConnection.set(intConnection);

        return intConnection;
View Full Code Here
67
68
69
70
71
72
73
74
75
76
//#endif JAVA6
{

    public PooledConnection getPooledConnection() throws SQLException {

        JDBCConnection connection =
            (JDBCConnection) JDBCDriver.getConnection(url, connectionProps);

        return new JDBCPooledConnection(connection);
    }
View Full Code Here
TOP

Related Classes of org.hsqldb.jdbc.jdbcConnection

  • org.apache.ibatis.jdbc.PooledDataSourceTest
  • org.hsqldb.ClientConnection
  • org.hsqldb.ClientConnectionHTTP
  • org.hsqldb.HSQLClientConnection
  • org.hsqldb.HTTPClientConnection
  • org.hsqldb.jdbc.pool.JDBCConnectionPoolDataSource
  • org.hsqldb.jdbc.pool.JDBCPooledConnection
  • org.hsqldb.jdbc.pool.JDBCPooledDataSource
  • org.hsqldb.jdbc.pool.JDBCXADataSource
  • org.hsqldb.jdbcDriver
    • Copyright © 2018 www.massapicom. All rights reserved.
    All source code are property of their respective owners. Java is a trademark of Sun Microsystems, Inc and owned by ORACLE Inc. Contact coftware#gmail.com.