public Class JDBCConnection

• <path>.properties
• <path>.script
• <path>.log
• <path>.data
• <path>.backup
• <path>.lck

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 ambiguity 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, '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

+--databases
   +--test.properties
   +--test.script
   +--test.log
   +--test.data
   +--test.backup
   +--test.lck

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.

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 knowledge 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 WebStart and Java Applet configurations, 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.

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. HSQLDB distribution jars containing the Driver implementation 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 explicitly 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.