JDBC Applications and the Cloudscape Technology
Page 3 of 5

Cloudscape Basics

This section discusses the basics of the Cloudscape technology. It covers the following topics:

Cloudscape JDBC Driver

Cloudscape comes with a local JDBC driver. Applications use JDBC to interact with a database. Applications must load the driver in order to work with the database.

In an embedded environment, loading the driver also starts Cloudscape. In a client/server environment, starting the server framework starts the local JDBC driver and Cloudscape. The application starts only the client JDBC driver, which handles sending the information back and forth over the network. Applications running in embedded mode use a different driver from that used by applications running in client/server mode.

In a Java application, you typically load the driver with the static Class.forName method or with the jdbc.drivers system property. For example:

Class.forName("COM.cloudscape.core.JDBCDriver").newInstance();

For detailed information about loading the Cloudscape JDBC driver, see java.sql.Driver in the Cloudscape Reference Manual. See also COM.cloudscape.util.DriverUtil.

Cloudscape JDBC Database Connection URL

A Java application using the JDBC API establishes a connection to a database by obtaining a Connection object. The standard way to obtain a Connection object is to call the method DriverManager.getConnection, which takes a String containing a database connection URL (uniform resource locator). A JDBC database connection URL provides a way of identifying a database. It also allows you to perform a number of high-level tasks, such as creating a database or shutting down the system.

An application in an embedded environment uses a different database connection URL from that used by applications in a client/server environment.

However, all versions of the database connection URL (which you can use for tasks besides connecting to a database) have common features:

  • you can specify the name of the database you want to connect to
  • you can specify a number of attributes and values that allow you to accomplish tasks. 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 synchronization attributes and values, see the Cloudscape Synchronization Guide.

For syntax of the database connection URL, see Cloudscape Database Connection URL Syntax in the Cloudscape Reference Manual.

An example use of the database connection URL:

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

NOTE: In most cases, use the database connection URL within your application as an argument to DriverManager.getConnection. However, in a few rare cases, you can use the database connection URL and the attributes you want as an argument to DriverManager.getConnection within an SQL-J statement. See Shutting Down the System. For example:

-- shuts down the current database
CALL (CLASS java.sql.DriverManager).getConnection(
    'jdbc:cloudscape:;current=true;shutdown=true')

Cloudscape System

A Cloudscape database exists within a system.

A Cloudscape system is a single instance of Cloudscape and the environment in which it runs. It consists of a system directory, zero or more databases, and a system-wide configuration. The system directory contains any persistent system-wide configuration parameters, or properties, specific to that system in a properties file called cloudscape.properties (see cloudscape.properties). This file is not automatically created; you must create it yourself.

It also usually contains an information log about activity in the most recent session of the Cloudscape system.

The Cloudscape system is not persistent; you must specify the location of the system directory at every startup.

However, the system--as well as its directory, which you name--is an essential part of a running database or databases. Understanding the Cloudscape system is essential to successful development and deployment of Cloudscape applications.

Figure 2-1 Cloudscape databases live in a system, which includes system-wide properties, an error log, and one or more databases.

The system directory can also contain an error log file called cloudscape.LOG (see The Information (Error) Log).

Each database within that system is contained in a subdirectory, which has the same name as the database (see A Cloudscape Database).

You can use a property (see cloudscape.service in Tuning Cloudscape) to include databases in other directories or in subdirectories of the system directory in the current system when you start it up.

In addition, if you connect to a database outside the current system, it automatically becomes part of the current system.

One Cloudscape per System

You could potentially have two instances of Cloudscape running on the same machine at the same time, but each instance must run in a different system; two separate instances of Cloudscape should not access databases within the same system. For example, in an embedded environment, an application that accesses Cloudscape databases starts up the local JDBC driver, which starts up an instance of Cloudscape. In an embedded system, do not run both ij and Cloudview (or two ijs, or two Cloudviews, or any two applications) in the same system or on the same database at the same time; severe database corruption can result. See Double-Booting System Behavior.

In a client/server environment, you do not have to worry about two client applications corrupting a database. In a client/server environment, client applications start up the remote JDBC driver and connect to an already running server. The server framework is designed to allow multiple applications to connect to the same database.

Booting

The default configuration for Cloudscape is that Cloudscape boots a database when an application first makes a connection to it. When Cloudscape boots a database, it checks to see if recovery needs to be run on the database, so in some unusual cases booting may take some time.

You can also configure your system to automatically boot all databases in the system when it starts up; see cloudscape.system.bootAll in Tuning Cloudscape. That is the recommended configuration when you use Cloudscape in a client/server environment. Because of the time needed to boot a database, the number of databases in the system directory affects startup performance if you use that configuration.

Once a database has been booted within a Cloudscape system, it remains active until the Cloudscape system has been shut down or until you shut down the database individually.

When Cloudscape boots a database, it prints a message in the information log:

Wed May 20 14:31:38 PDT 1998:
Booting Cloudscape Version 2.0.0 instance 80000000-00d0-8bdf-d115-000a0a0b2d00 on database at directory C:\cloudscape\demo\databases\toursDB

The number of databases running in a Cloudscape system is limited only by the amount of memory available in the JVM.

Shutting Down the System

In an embedded environment, when an application shuts down, it should first shut down Cloudscape.

If the application that started the embedded Cloudscape quits but leaves the JVM running, Cloudscape continues to run and is available for database connections.

In an embedded system, the application shuts down Cloudscape by issuing the following JDBC call:

DriverManager.getConnection("jdbc:cloudscape:;shutdown=true");

To shut down the system within an SQL-J statement, you can use the following:

CALL (CLASS java.sql.DriverManager).getConnection(
    'jdbc:cloudscape:;shutdown=true')

Shutdown commands always raise SQLExceptions. See Shutting Down Cloudscape or an Individual Database.

When Cloudscape runs as a database server, it typically runs continuously. Use only the prescribed utility for shutting it down. See the Cloudscape Server and Administration Guide for more details.

When a Cloudscape system shuts down, a message goes to the information log:

Wed May 20 14:31:54 PDT 1998:
Shutting down Cloudscape instance 80000001-00d0-8bdf-d115-000a0a0b2d00

Typically, an application using an embedded Cloudscape engine shuts down Cloudscape just before shutting itself down. However, an application can shut down Cloudscape and later restart it in the same JVM session. To restart Cloudscape successfully, the JVM needs to unload COM.cloudscape.core.JDBCDriver, so that it can reload it when it restarts Cloudscape. (Loading the local driver starts Cloudscape.)

You cannot explicitly request that the JVM unload a class, but you can ensure that the JDBCDriver class is unloaded by using a System.gc() to force it to garbage collect classes that are no longer needed. Running with -nogc or -noclassgc definitely prevents the class from being unloaded and makes you unable to restart Cloudscape in the same JVM.

It is also possible to shut down a single database instead of the entire Cloudscape system. See Shutting Down Cloudscape or an Individual Database. You can reboot a database in the same Cloudscape session after shutting it down.

Defining the System Directory

You define the system directory when Cloudscape starts up by specifying a Java system property called cloudscape.system.home. If you do not specify the system directory when starting up Cloudscape, the current directory becomes the system directory. (For information on setting this and other properties, see Tuning Cloudscape.)

NOTE: Cloudscape recommends that you always explicitly specify the system directory when starting up Cloudscape.

Cloudscape uses the cloudscape.system.home property to determine which directory is its system directory--and thus what databases are in its system, where to create new databases, and what configuration parameters to use.

If you specify a system directory at startup that does not exist, Cloudscape creates this new directory--and thus a new system with no databases--automatically.

The Information (Error) Log

Once you create or connect to a database within a system, Cloudscape begins outputting information and error messages, if any. Typically, Cloudscape writes this information to a log called cloudscape.LOG in the system directory, although you can also have Cloudscape send messages to a stream, using a property. You can also configure whether Cloudscape writes over or appends to the log with the cloudscape.infolog.append property. (For information on setting this and other properties, see Tuning Cloudscape.)

cloudscape.properties

The text file cloudscape.properties contains the definition of properties, or configuration parameters valid for the entire system. This file is not automatically created; if you wish to set Cloudscape properties with this file, you need to create it yourself. The file should be in the format created by the java.util.Properties.save method. A sample cloudscape.properties file is provided in /demo/programs/tours/scripts. For more information about properties, see Tuning Cloudscape.

Double-Booting System Behavior

Cloudscape attempts to prevent two instances of Cloudscape from booting the same database by using a file called db.lck inside the database directory (see The Database Directory).

On some platforms, Cloudscape can successfully prevent a second instance of Cloudscape from booting the database, and thus prevents corruption. If this is the case, you will see an SQLException like the following:

ERROR XJ040: Failed to start database 'toursDB', see the next exception for details.
ERROR XSDB6: Another instance of Cloudscape may have already booted the database C:\databases\toursDB.

The error is also written to the information log.

On other platforms, Cloudscape issues a warning message if an instance of Cloudscape attempts to boot a database that may already have a running instance of Cloudscape attached to it. However, it does not prevent the second instance from booting, and thus potentially corrupting, the database. (You can change this behavior with the property cloudscape.database.forceDatabaseLock.)

If a warning message has been issued, corruption may already have occurred.

NOTE: When you are using Cloudview, error messages appear in the console or operating system window from which Cloudview was started.

The warning message looks like this:

WARNING: Cloudscape (instance 80000000-00d2-3265-de92-000a0a0a0200) is attempting to boot the database /export/home/sky/wombat even though Cloudscape (instance 80000000-00d2-3265-8abf-000a0a0a0200) may still be active. Only one instance of Cloudscape
should boot a database at a time. Severe and non-recoverable corruption can result and may have already occurred.

The warning is also written to the information log.

This warning is primarily a Technical Support aid to determine the cause of corruption. However, if you see this warning, your best choice is to close the connection and exit the JVM. This minimizes the risk of a corruption. Close all instances of Cloudscape, then restart one instance of Cloudscape and shut down the database properly so that the db.lck file can be removed. The warning message continues to appear until a proper shutdown of the Cloudscape system can delete the db.lck file.

When developing applications, you may want to configure Cloudscape to append to the log. Doing so will help you detect when you have inadvertently started more than one instance of Cloudscape in the same system. For example, when the cloudscape.infolog.append property is set to true for a system, booting two instances of Cloudscape in the same system produces the following in the log:

Thu Aug 06 09:42:51 PDT 1998:
Booting Cloudscape instance 80000000-00d2-1c87-7586-000a0a0b1300 on database at directory C:\tutorial_system\toursDB
------------------------------------------------------------
Thu Aug 06 09:42:59 PDT 1998:
Booting Cloudscape instance 80000000-00d2-1c87-9143-000a0a0b1300 on database at directory C:\tutorial_system\HelloWorldDB

NOTE: Cloudscape allows you to boot databases that are not in the system directory. While this may seem more convenient, it may cause more problems with double-booting.

Recommended Practice

When developing Cloudscape applications, create a single directory to hold your database or databases. Name this directory something like cloudscape_system or database_directory. Doing so will help you remember that:

  • All databases exist within a system.
  • System-wide properties affect the entire system, and persistent system-wide properties live in the system directory.
  • You can boot all the databases in the system, and the boot-up times of all databases affect the performance of the system.
  • You can preboot databases only if they are within the system. (Databases do not necessarily have to live inside the system directory, but keeping your databases there is the recommended practice.)
  • Once you connect to a database, it is part of the current system (and thus inherits all system-wide properties).
  • Only one instance of Cloudscape can run in a system at a single time, and only one instance of Cloudscape should boot a database at one time (keeping databases in the system directory makes it less likely that you would use more than one instance of Cloudscape).
  • To back up a database or databases, back up the entire system.
  • The error log lives inside the system directory.

A Cloudscape Database

A Cloudscape database contains dictionary objects such as tables, columns, indexes, and jar files. A Cloudscape database also stores its own configuration information.

The Database Directory

A Cloudscape database is stored in files that live in a directory of the same name as the database. Database directories typically live in system directories (see Cloudscape System).

A database directory contains the following, as shown in Figure 2-2:

  • log directory

    Contains files that make up the database log, used internally for data recovery (not the same thing as the information log).

  • seg0 directory

    Contains one file for each user table, system table, and index (known as conglomerates), plus one file for internal tables.

  • service.properties file

    A text file with internal configuration information.

  • tmp directory

    (May or may not exist.) A temporary directory used by Cloudscape for large sorts and deferred updates and deletes. Sorts are used by a variety of SQL-J statements. For databases on read-only media, you may need to set a property to change the location of this directory. See Creating Cloudscape Databases for Read-Only Use.

  • jar directory

    (May or may not exist.) A directory in which jar files are stored when you use database class loading.

  • cloudscape.db file

    Provided for file finders.

Read-only database directories can be archived (and compressed, if desired) into jar or zip files. For more information, see Accessing a Read-Only Database in a Zip/Jar.

Figure 2-2 Cloudscape database directories contain files and directories used by the software.

Cloudscape imposes relatively few limitations on the number and size of databases and database objects. Table 2-1, "Size Limits to Cloudscape Database Objects" lists some size limitations of Cloudscape databases and database objects.

Table 2-1 Size Limits to Cloudscape Database Objects

Type of Object

Limit

tables per database

Some operating systems impose a limit to the number of files allowed in a single directory.

indexes per table

no limit

columns per table

rows per table

no limit

size of table

no limit

Some operating systems impose a limit on the size of a single file.

size of row

no limit--rows can span pages

Creating, Dropping, and Backing Up Databases

You create new databases and access existing ones by specifying attributes to the Cloudscape database connection URL (see Examples).

There is no drop database command. To drop a database, delete the database directory with operating system commands. The database must not be booted when you remove a database. You can get a list of booted databases with getPropertyInfo (see Offering Connection Choices to the User).

To back up a database, you can use the online backup utility. For information on using this utility, see the Cloudscape Server and Administration Guide.

A simpler way to back up a Cloudscape database is simply to use operating system tools to copy the database directory. Simply shut down Cloudscape, then back up databases in the context of their system. That is, back up the entire system directory in order to back up:

  • the database directory
  • persistent system-wide configuration properties (cloudscape.properties)

You can use compression tools such as pkzip, which may be necessary to reduce database size for backup storage.

To back up a single database when there is more than one database in the system directory, create a new "system" folder. Copy the database folder and the cloudscape.properties files to the new folder. Then back up that folder.

Single Database Shutdown

An application can shut down a single database within a Cloudscape system and leave the rest of the system running. See Shutting Down Cloudscape or an Individual Database.

Storage and Recovery

A Cloudscape database provides persistent storage and recovery. Cloudscape ensures that all committed transactions are durable, even if the system fails, through the use of a database log. Whereas inserts, updates, and deletions may be cached before being written to disk, log entries tracking all those changes are never cached but always written to disk. If the system fails unexpectedly, when Cloudscape next starts up it can use the log to perform recovery, recovering the "lost" transactions from the log and rolling back uncommitted transactions. Recovery ensures that all committed transactions at the time the system failed are applied to the database, and all transactions that were active are rolled back. Thus the databases are left in a consistent, valid state.

In normal operation, Cloudscape keeps the log small through periodic checkpoints. Checkpointing marks the portions of the log that are no longer useful, writes changed pages to disk, then truncates the log.

Cloudscape checkpoints the log as it fills. It also checkpoints the log when a shutdown command is issued; see Shutting Down Cloudscape or an Individual Database. Shutting down the JVM in which Cloudscape is running without issuing the proper shutdown command is equivalent to a system failure from Cloudscape's point of view.

Booting a database means that Cloudscape checks to see if recovery needs to be run on a database. Recovery can be costly, so using the proper shutdown command improves connection or startup performance.

Log on Separate Device

You can put a database's log on a separate device when you create it. (This is useful for improving performance, not for improved recovery.) For more information, see the Cloudscape Server and Administration Guide.

Database Pages

Cloudscape tables and indexes, known as conglomerates, consist of two or more pages. A page is a unit of storage whose size is configurable on a system-wide, database-wide, or conglomerate-specific basis. By default, a conglomerate grows one page at a time until eight pages of user data (or nine pages of total disk use, which includes one page of internal information) have been allocated. (You can configure this behavior; see cloudscape.storage.initialPages in Tuning Cloudscape.). After that, it grows eight pages at a time.

The size of a row or column is not limited by the page size. Rows or columns that are longer than the table's page size are automatically wrapped to overflow pages.

Database-Wide Properties

You can set many Cloudscape properties as database-level properties. When set in this way, they are stored in the database and "travel" with the database unless overridden by a system property. For more information, see Database-Wide Properties in Tuning Cloudscape.

NOTE: Cloudscape recommends that you work with database-level properties wherever possible.

Version 3 Database Limitations

Cloudscape databases version 3.0 or higher have these limitations:

  • Indexes are not supported for long rows.

    This means that if the length of the key columns in an index is larger than half the page size of the index, creating an index on those key columns for the table fails. For existing indexes, an insert of new rows for which the key columns are larger than half of the index page size causes the insert to fail.

NOTE: Indexing on long columns is a bad idea in any case. Create indexes on small columns that provide a quick look-up to larger, unwieldy data in the row. Indexing on long columns does not provide the performance improvements that indexes usually provide. For information about indexes, see Tuning Cloudscape. However, it is possible to tune the page size of indexes to allow for larger rows, if you wish.

  • The system shuts down if the database log cannot allocate more disk space.

    There will be a "LogFull" error in cloudscape.LOG or some sort of IOException if it runs out of space in places other than the log, or nothing if the system has no more disk space to append to cloudscape.LOG.

Connecting to Databases

You connect to a database using a form of the Cloudscape database connection URL as an argument to the DriverManager.getConnection call (see Cloudscape JDBC Database Connection URL). You specify a path to the database within this database connection URL.

  • Standard Connections--Connecting to Databases in the File System

    The standard way to access databases is in the file system by specifying the path to the database, either absolute or relative to the system directory. In a client/server environment, this path is always the server's path.

  • Special Database Access

    It is also possible to connect to databases in the class path or in an archive file (and even to an archive file in the class path). (In a client/server environment, this refers to the server's class path). Connections of this kind are always read-only.

  • Examples

The examples in this section use the syntax of the database connection URL for use in an embedded environment. This information also applies to the client database connection URL in a client/server environment. For reference information about client database connection URLs, see java.sql.Connection in the Cloudscape Reference Manual.

Standard Connections--Connecting to Databases in the File System

Within the System

By default, you can connect to databases within the current system directory (see Defining the System Directory). To connect to databases within the current system, just specify the database name on the database connection URL. For example, if your system directory contains a database called myDB, you can connect to that database with the following database connection URL:

jdbc:cloudscape:myDB

The full call within a Java program would be:

Connection conn = DriverManager.getConnection("jdbc:cloudscape:myDB");

Outside the System Directory

You can also connect to databases in other directories (including subdirectories of the system directory) by specifying a relative or absolute path name to identify the database. The way you specify an absolute path is defined by the host operating system (see java.io.File.isAbsolute). You must specify a path for a database in a directory other than the system directory even if you have defined the cloudscape.service property to have Cloudscape boot the database automatically (see cloudscape.service in Tuning Cloudscape).

Using the database connection URL as described here, you can connect to databases in more than one directory at a time.

Two examples:

jdbc:cloudscape:../otherDirectory/myDB
jdbc:cloudscape:c:/otherDirectory/myDB

NOTE: Once connected to, such a database becomes a part of the Cloudscape system, even though it is not in the system directory. This means that it takes on the system-wide properties of the system and that no other instance of Cloudscape should access that database, among other things. Cloudscape recommends that you connect to databases only in the system directory. See Recommended Practice for suggestions about working with a Cloudscape system.

Conventions for Specifying the Database Path

When accessing databases from the file system (instead of from class path or a jar file), any path that is not absolute is interpreted as relative to the system directory.

The path must do one of the following:

  • refer to a previously created Cloudscape database
  • specify the create=true attribute

The path separator in the database connection URL is / (forward slash), as in the standard file:// URL protocol.

You can specify only databases that are local to the machine on which the JVM is running. NFS file systems on UNIX and remote shared files on Windows
(//machine/directory) are not guaranteed to work.

If two different database name values, relative or absolute, refer to the same actual directory, they are considered equivalent. This means that connections to a database through its absolute path and its relative path are connections to the same database. Within Cloudscape, the name of the database is defined by the canonical path of its directory from java.io.File.getCanonicalPath.

Cloudscape automatically creates any intermediate directory that does not already exist when creating a new database. If it cannot create the intermediate directory, the database creation fails.

If the path to the database is ambiguous, i.e., potentially the same as that to a database that is available on the class path (see Special Database Access), use the directory: subsubprotocol to specify the one in the file system. For example:

jdbc:cloudscape:directory:myDB

Special Database Access

You can also access databases from the class path or from a jar file (in the class path or not) as read-only databases.

From the Class Path

In most cases, you access databases from the file system as described above. However, it is also possible to access databases from the user's class path. The databases can be archived into a jar or zip file or left as is.

NOTE: All such databases are treated as read-only databases.

To access an unarchived database from the class path, specify the name of the database relative to the directory in the class path. (Even a database directly under such a directory would require a forward slash, to show that it is relative to that directory.) You can use the class path subprotocol (see Embedded Cloudscape JDBC Database Connection URL) if such a database is ambiguous with one in the directory system.

For example, for a database called toursDB in C:\cloudscape\demo\databases, you could put the C:\cloudscape\demo\databases directory in the user's class path and access toursDB like this:

jdbc:cloudscape:/toursDB

The forward slash is required before toursDB to indicate that it is relative to C:\cloudscape\demo\databases directory.

If only C:\cloudscape were in the class path, you could access toursDB (read-only) like this:

jdbc:cloudscape:/demo/databases/toursDB

From a Jar or Zip File

It is possible to access databases from a jar file. The jar file can be, but does not have to be, on the user's class path.

NOTE: All such databases are read-only.

For example, suppose you have archived the database jarDB1 into a file called jar1.jar. This archive is in the class path before you start up Cloudscape. You can access jarDB1 with the following database connection URL

jdbc:cloudscape:/jarDB1

To access a database in a jar file that is not on the user's class path, use the jar subprotocol.

For example, suppose you have archived the database jarDB2 into a file called jar2.jar. This archive is not in the class path. You can access jarDB2 by specifying the path to the jar file along with the jar subsubprotocol, like this:

jdbc:cloudscape:jar:(c:/cloudscape/lib/jar2.jar)jarDB2

For complete instructions and examples of accessing databases in jar files, see Accessing a Read-Only Database in a Zip/Jar.

Examples

Here are more example database connection URLs:

  • jdbc:cloudscape:db1

    Open a connection to the database db1. db1 is a directory located in the system directory.

  • jdbc:cloudscape:london/sales

    Open a connection to the database london/sales. london is a subdirectory of the system directory, and sales is a subdirectory of the directory london.

  • jdbc:cloudscape:/reference/phrases/french

    Open a connection to the database /reference/phrases/french.

    On a UNIX system, this would be the path of the directory. On a Windows system, the path would be C:\reference\phrases\french if the current drive were C. If a jar file storing databases were in the user's class path, this could also be a path within the jar file.

  • jdbc:cloudscape:a:/demo/toursDB

    Open a connection to the database stored in the directory \demo\toursDB on drive A (usually the floppy drive) on a Windows system.

  • jdbc:cloudscape:c:/databases/salesdb
    jdbc:cloudscape:salesdb

    These two database connection URLs connect to the same database, salesdb, on a Windows platform if the system directory of the Cloudscape system is C:\databases.

  • jdbc:cloudscape:support/bugsdb;create=true

    Create the database support/bugsdb in the system directory, automatically creating the intermediate directory support if it does not exist.

  • jdbc:cloudscape:toursDB;shutdown=true

    Shut down the toursDB database.

  • jdbc:cloudscape:/myDB

    Access myDB (which is directly in a directory in the class path) as a read-only database.

  • jdbc:cloudscape:classpath:/myDB

    Access myDB (which is directly in a directory in the class path) as a read-only database. The reason for using the subsubprotocol is that it may happen to have the same path as a database in the directory structure.

  • jdbc:cloudscape:jar:(C:/dbs.jar)products/boiledfood

    Access the read-only database boiledfood in the products directory from the jar file C:/dbs.jar.

  • jdbc:cloudscape:directory:myDB

    Access myDB, which is in the system directory. The reason for using the directory: subsubprotocol is that it may happen to have the same path as a database in the class path.

Working with the Database Connection URL Attributes

You specify pairs of attributes and values on the Cloudscape database connection URL (see Cloudscape JDBC Database Connection URL). The examples in this section use the syntax of the database connection URL for use in an embedded environment. You can also specify these same attributes and values on the client database connection URL if you are using Cloudscape as a database server. For more information, see the Cloudscape Server and Administration Guide.

You can also set these attributes by passing a Properties object along with a database connection URL to DriverManager.getConnection when obtaining a connection; see Specifying Attributes in a Properties Object.

For detailed information about the database connection URL syntax and attributes, see Cloudscape Database Connection URL Syntax in the Cloudscape Reference Manual.

You can specify the following attributes:

  • synchronization attributes

    See the Cloudscape Synchronization Guide.

Shutting Down Cloudscape or an Individual Database

Applications in an embedded environment shut down the Cloudscape system by specifying the shutdown=true attribute in the database connection URL. To shut down the system, you do not specify a database name, and you must not specify any other attribute.

jdbc:cloudscape:;  shutdown=true

A successful shutdown always results in an SQLException to indicate that Cloudscape has shut down and that there is no other exception.

NOTE: Cloudconnector is shut down with a utility. See the Cloudscape Server and Administration Guide.

You can also shut down an individual database if you specify the databaseName. You can shut down the database of the current connection if you specify the current=true attribute instead of a database name (within an SQL-J statement).

// shutting down a database from your application
DriverManager.getConnection(
    'jdbc:cloudscape:toursDB;
shutdown=true');

-- shutting down the current database using SQL
CALL (CLASS java.sql.DriverManager).getConnection(
    'jdbc:cloudscape:;current=true;shutdown=true')

NOTE: Any request to the DriverManager with a shutdown=true attribute raises an exception, so expect this behavior when shutting down.

Creating and Accessing a Database

You create a standard (non-synchronization) database by supplying a new database name with the database connection URL and specifying create=true. Cloudscape creates a new database inside a new subdirectory in the system directory with the same name as the new database. If you specify a partial path, it is relative to the system directory. You can also specify an absolute path.

jdbc:cloudscape:databaseName;  create=true

For more details about create=true, see create=true in the Cloudscape Reference Manual.

For more information on creating synchronization databases, see the Cloudscape Synchronization Guide.

Accessing an Existing Database

You access an existing database by specifying it in the Cloudscape database connection URL in one of the following:

  • the subprotocol to jdbc:cloudscape:
  • the databaseName attribute

The database must exist (see also Standard Connections--Connecting to Databases in the File System).

As the Subprotocol

jdbc:cloudscape:databaseName

Using the databaseName Attribute

jdbc:cloudscape:;databaseName=databaseName

You can use autocommit=false with this attribute. For more details, see (no attributes) and databaseName=nameofDatabase in the Cloudscape Reference Manual.

You can access read-only databases in jar or zip files by specifying jar as the subsubprotocol, like this:

jdbc:cloudscape:jar:(pathToArchive)databasePathWithinArchive

Or, if the jar or zip file has been included in the class path, like this:

jdbc:cloudscape:/databasePathWithinArchive

Turning Off Auto-Commit

You can turn off auto-commit with autocommit=false. For information about auto-commit, see Using Auto-Commit.

jdbc:cloudscape:databaseName;  autocommit=false

Getting a Nested Connection

When you are executing a method within SQL-J, that method may need to reuse the current connection to the database in order to execute more SQL-J statements. Such a connection is called a nested connection. One way for a method to get a nested connection is to issue a connection request with current=true as an attribute to the database connection URL.

jdbc:cloudscape:;  current=true

If you combine this attribute with any other attributes, they are ignored (except for shutdown). For more details, see current=true in the Cloudscape Reference Manual.

Providing a User Name and Password

When user authentication is enabled, an application must provide a user name and password. One way to do this is to use database connection URL attributes (see user=userName and password=userPassword).

jdbc:cloudscape:toursDB;user=jill;password=toFetchAPail

For more information, see Working with User Authentication.

Encrypting a Database When You Create It

If your environment is configured properly, you can created your database as an encrypted database (one in which the database is encrypted on disk). To do this, you use the dataEncryption=true attribute to turn on encryption and the bootPassword=key attribute to specify a key for the encryption. You can also specify an encryption provider and encryption algorithm other than the defaults with the encryptionProvider=providerName and encryptionAlgorithm=algorithm attributes For more information about data encryption, see Encrypting Databases on Disk.

jdbc:cloudscape:encryptedDB;create=true;bootPassword=cloudscape

Booting an Encrypted Database

You must specify the encryption key with the bootPassword=key attribute for an encrypted database when you boot it (which is the first time you connect to it within a JVM session or after shutting it down within the same JVM session). For more information about data encryption, see Encrypting Databases on Disk.

jdbc:cloudscape:encryptedDB;bootPassword=clo760uds2caPe

Upgrading a Database

To upgrade a database, use the upgrade=true attribute the first time you connect to it. See Upgrades for more information. The attribute is ignored if no upgrade is needed.

Specifying Attributes in a Properties Object

Instead of specifying attributes on the database connection URL, you can specify attributes as properties in a Properties object that you pass as a second argument to the DriverManager.getConnection method. For example, to set the autocommit attribute to false, you could set the autocommit property to false instead, as in the following example:

Class.forName("COM.cloudscape.core.JDBCDriver").newInstance();
Properties p = new Properties();
p.put("autocommit", "false");
Connection conn = DriverManager.getConnection(
    "jdbc:cloudscape:mynewDB", p);

NOTE: This method works only for database connection URL attributes, not for Cloudscape properties.