Deploying Cloudscape Applications
Page 3 of 4

Creating Cloudscape Databases for Read-Only Use

You can create Cloudscape databases for use on read-only media such as CD-ROMs. Cloudscape databases in zip or jar files are also read-only databases. Typically, read-only databases are deployed with an application in an embedded environment.

Creating and Preparing the Database for Read-Only Use

To create databases for use on read-only media:

  1. Create and populate the database on read-write media.
  2. If the database contains stored prepared statements, make sure that they are all valid and will not need recompilation.

    You can recompile invalid statements with the following statement:

    ALTER STATEMENT RECOMPILE INVALID

  3. Commit all transactions and shut down Cloudscape in the prescribed manner (see Shutting Down Cloudscape or an Individual Database).

    If you do not shut down Cloudscape in the prescribed manner, Cloudscape will need to perform recovery the next time the system boots. Cloudscape cannot perform recovery on read-only media.

  4. Delete the tmp directory if one was created within your database directory. If you include this directory, Cloudscape will attempt to delete it and will return errors when attempting to boot a database on read-only media.
  5. For the read-only database, set the property cloudscape.storage.tempDirectory to a writable location. Cloudscape needs to write to temporary files for large sorts required by such SQL-J statements as ORDER BY, UNION, DISTINCT, GROUP BY, and AGGREGATE. For more information about this property, see cloudscape.storage.tempDirectory in the Tuning Cloudscape. For example:

    cloudscape.storage.tempDirectory=c:/temp/mytemp

    Be sure to set this property such that it is deployed with the database. For more information, see Embedded Systems and Properties.

  6. Configure the database to send error messages to a writable file or to an output stream. For information, see the cloudscape.stream.xxx properties in Tuning Cloudscape.

    cloudscape.stream.error.file=c:/temp/mylog.LOG

    Be sure to set this property such that it is deployed with the database. For more information, see Embedded Systems and Properties.

Deploying the Database on the Read-Only Media

  1. Move the database directory to the read-only media, including the necessary subdirectory directories (log and seg0) and the file service.properties.
  2. Use the database as usual, with the following exception:

    You will not be able to insert or update any data in the database or create or drop dictionary objects.

Transferring Read-Only Databases to Archive (Jar or Zip) Files

Once a database has been created in Cloudscape, it can be stored in a jar or zip file and continue to be accessed by Cloudscape in read-only mode. This allows a read-only database to be distributed as a single file instead of as multiple files within a directory and to be compressed. In fact, a jar or zip file can contain any number of Cloudscape databases and can also contain other information not related to Cloudscape, such as application data or code.

You cannot store the cloudscape.properties file in a jar or zip file.

To create a jar or zip file containing one or more Cloudscape databases:

  1. Follow the instructions for creating a database for use on read-only media. See Creating and Preparing the Database for Read-Only Use.
  2. From the directory that contains the database folder, archive the database directory and its contents. For example, for the database sales that lives in the system directory C:\london, issue the command from london. Do not issue the command from inside the database directory itself.

    For example, archive the database folder and its contents using Javasoft's JAR program from the JDK. You can use any zip or jar tool to generate the archive.

    This command archives the database directory sales and its contents into a compressed jar file called dbs.jar.

    cd C:\london
    jar cMf C:\dbs.jar sales

    You can add multiple databases with jar. For example, this command puts the sales databases and the boiledfood database (in the subdirectory products) into the archive.

    cd C:\london
    jar cMf C:\dbs.jar sales products\boiledfood

    The relative paths of the database in the jar need not match their original relative paths. You can do this by allowing your archive tool to change the path, or by moving the original databases before archiving them.

    The archive can be compressed or uncompressed, or individual databases can be uncompressed or compressed if your archive tool allows it. Compressed databases take up a smaller amount of space on disk, depending on the data loaded, but are slower to access.

    Once the database is archived into the jar or zip file, it has no relationship to the original database. The original database can continue to be modified if desired.

Accessing a Read-Only Database in a Zip/Jar

To access a database in a zip/jar, you specify jar in the subsubprotocol:

jdbc:cloudscape:jar:(pathToArchive)databasePathWithinArchive

The pathToArchive is the absolute path to the archive file. The databasePathWithinArchive is the relative path to the database within the archive. For example:

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

If you have trouble finding a database within an archive, check the contents of the archive using your archive tool. The databasePathWithinArchive must match the one in the archive. You may find that the path in the archive has a leading slash, and thus the URL would be:

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

Databases in a jar or zip file are always opened read-only and there is currently no support to allow updates of any type.

Databases in a jar or zip file are not booted automatically when Cloudscape is started, unless they are explicitly listed as cloudscape.service properties.

Accessing Databases-in-a-Jar in the Class Path

Once an archive containing one or more Cloudscape databases has been created it can be placed in the class path. This allows access to a database from within an application without the application's knowing the path of the archive. When jar or zip files are part of the class path, you do not have to specify the jar subsubprotocol to connect to them.

To access a database in a zip or jar file in the class path:

  1. Set the class path to include the jar or zip file before starting up Cloudscape:

    CLASSPATH="C:\dbs.jar;%CLASSPATH%"

  2. Connect to a database within the jar or zip file with one of the following database connection URLs:

    jdbc:cloudscape:/databasePathWithinArchive

    (standard syntax)

    jdbc:cloudscape:classpath:/databasePathWithinArchive

    (syntax with subsubprotocol)

For example:

jdbc:cloudscape:/products/boiledfood
jdbc:cloudscape:classpath:/products/boiledfood

When Path Is Ambiguous with Databases in File System

Use the basic database connection URL syntax only if the database path specified does not also point to a Cloudscape database in the file system. If this is the case, the connection attempt may fail or connect to the wrong database. Use the form of the syntax with the subsubprotocol to distinguish between the databases.

For example:

jdbc:cloudscape:classpath:/products/boiledfood

When Path Is Ambiguous Because of Databases in Class Path

To connect to a database in the file system when the database connection URL that you would use would be ambiguous with a database in the class path, use the following form of the database connection URL:

jdbc:cloudscape:directory:databasePathInFileSystem

For example,

jdbc:cloudscape:directory:/products/boiledfood

Apart from the database connection URL, databases in archives in the class path behave just like databases in archives accessed through the file system. However, databases in archives are read-only.

Read-Only Databases and Upgrading

Upgrading requires that databases be on read-write media. Both major and minor revisions of Cloudscape--such as those between version 2 and 3 and those between 1 and 2--involve upgrading databases. Maintenance revisions--such as those between 1.5.1 and 1.5.2--also involve an upgrade step: Stored prepared statements are recompiled.

To upgrade, transfer the database to read-write media, connect with the new version of Cloudscape, then retransfer to read-only media.

NOTE: To avoid upgrade problems, distribute the version of the Cloudscape software appropriate for the database on the read-only media along with the application and the database.

Databases on Read-Only Media and DatabaseMetaData

Databases on read-only media return true for DatabaseMetaData.isReadOnly.