JDBC Applications and the Cloudscape Technology
Page 4 of 5

Cloudscape Embedded Basics

This section explains how to use and configure Cloudscape in an embedded environment. Included in the installation is a sample application program, /demo/programs/simple, which illustrates how to run Cloudscape embedded in the calling program.

It includes the following topics:

Embedded Cloudscape JDBC Driver

The Cloudscape driver class name for the embedded environment is COM.cloudscape.core.JDBCDriver. In a Java application, you typically load the driver with the static Class.forName method or with the jdbc.drivers system property. For more information, see Starting Cloudscape as an Embedded Database.

For detailed information about loading the Cloudscape JDBC driver, see java.sql.Driver in the Cloudscape Reference Manual.

Embedded Cloudscape JDBC Database Connection URL

This section discusses the database connection URL for working in an embedded environment. In addition, in a client/server environment, the JDBC server framework essentially "translates" a client database connection URL into this standard (embedded) database connection URL. For example, when Cloudscape is running in the Cloudconnector environment, a client application might use the following database connection URL:

jdbc:cloudscape:weblogic://godfrey:7001/toursDB;create=true

Cloudconnector passes the following standard database connection URL to Cloudscape:

jdbc:cloudscape:toursDB;create=true

For that reason, this section provides useful information for all environments.

The standard Cloudscape JDBC database connection URL (which you can use for tasks besides connecting to a database) is

jdbc:cloudscape:[subsubprotocol:][databaseName]
[;attribute=value]*

In JDBC lingo, cloudscape is the subprotocol for connecting to a Cloudscape database. The subprotocol is always cloudscape and does not vary.

Subsubprotocol, which is not typically specified, determines how Cloudscape looks for a database: in a directory, in a class path, or in a jar file. It is used only in rare instances, usually for read-only databases. Subsubprotocol is one of the following:

    • directory
      The default. Specify this explicitly only to distinguish a database that may be ambiguous with one on the class path.
    • classpath
      Databases are treated as read-only databases, and all databaseNames must begin with at least a slash, because you specify them "relative" to the class path directory. See From the Class Path.
    • jar
      Databases are treated as read-only databases. databaseNames may require a leading slash, because you specify them "relative" to the jar file. See From a Jar or Zip File.

      jar requires an additional element immediately before the database name:

      (pathToArchive)

      pathToArchive is the path to the jar or zip file that holds the database.

For examples of using this syntax, see Accessing a Read-Only Database in a Zip/Jar.

You typically pass the database connection URL as an argument to the JDBC DriverManager.getConnection method call. For example:

DriverManager.getConnection(
    "jdbc:cloudscape:toursDB;autocommit=false");

You can specify attributes and attribute values to a database connection URL. For more information about what you can specify with the Cloudscape database connection URL, see Examples. For detailed reference about attributes and values, see Cloudscape Database Connection URL Syntax in the Cloudscape Reference Manual.

For information about the client/server version of the database connection URL, see the Cloudscape Server and Administration Guide.

Starting Cloudscape as an Embedded Database

To start Cloudscape, you start the Cloudscape JDBC driver. Starting the Cloudscape driver starts up the complete Cloudscape system within the current JVM.

For example, when using the JBDC driver manager directly within Java code, you typically start a JDBC driver in one of two ways:

For more details, see java.sql.Driver in the Cloudscape Reference Manual.

Once the Cloudscape JDBC driver class has been loaded, you can connect to any Cloudscape database by passing the embedded database connection URL with the appropriate attributes to the DriverManager.getConnection method (see Accessing an Existing Database).

For example:

Connection conn = DriverManager.getConnection(
    "jdbc:cloudscape:toursDB;autocommit=false");

For more information about connecting to a database, see Connections.

Working with Database Threads in an Embedded Environment

Do not use sleep and interrupt calls to notify threads that are accessing a database, because Cloudscape will catch the interrupt call and close the connection to the database. Use wait and notify calls instead.

This won't happen in a client/server environment, but if you want your application to work in either environment it is good practice to follow this rule.

There are special considerations when working with more than one database thread in an application. See Working with Multiple Connections to a Single Database and Working with Multiple Threads Sharing a Single Connection.