JDBC Applications and the Cloudscape Technology,
Page 4 of 4


[top]
[prev]
[next]
Documentation Top
Global Index
Reference Manual
TOC Index
Grammar index
Developer's Guide
TOC Index
Tuning Cloudscape
TOC Index

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.

Standard 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:

  • Specify the jdbc.drivers system property, which allows users to customize the JDBC drivers used by their applications. For example:
java -Djdbc.drivers=COM.cloudscape.core.JDBCDriver applicationClass
  • Load the class directly from Java code using the static method Class.forName. For example:
Class.forName("COM.cloudscape.core.JDBCDriver").newInstance();

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”.

[top]
[prev]
[next]


Cloudscape Version 3.0
For technical support, go to: www.cloudscape.com and click Support.
Copyright © 1998 and 1999 Cloudscape, Inc. All rights reserved.