Cloudscape Basics and the Sample Database
Page 4 of 6

Getting an Application to Start Up Cloudscape

A Cloudscape application is a Java application that interacts with Cloudscape using the standard JDBC API (application programming interface). The JDBC API is part of the JDK and is not provided by Cloudscape. It consists of the java.sql package, which is a set of classes and interfaces that make it possible to access databases from a Java application.

In order to interact with Cloudscape, an application must first start up the Cloudscape JDBC driver. A JDBC driver is an application that implements the JDBC interface and is loaded by the JDBC driver manager. The name of embedded Cloudscape's JDBC driver is COM.cloudscape.core.JDBCDriver.

The method you use to start up the driver is not actually part of the java.sql package; it is the only method for interacting with Cloudscape that is not part of that package. To start up Cloudscape and make it available for connections, you pass the name of the JDBC driver to the Class.forName method, which you will do in the following example.

Test the Class Path Script

Cloudscape provides a utility to test whether your class path is correct for a particular environment. In this tutorial, you work mostly in an embedded environment. Therefore you can run the utility with the following arguments:

  • embedded
  • sampleApp (to test for the sample application classes)

To run the utility:

  1. Open a command window and change directories to your_tutorial_home.
  2. Run your setclasspath script (see Running the Script).
  3. Run the utility:

    java COM.cloudscape.tools.sysinfo -cp embedded sampleApp

    If all the needed libraries are present in the class path, the utility displays a message indicating success. If any of the needed libraries are missing, it displays a message indicating what is missing.

Creating, Compiling, and Running HelloWorld

  1. Open the .java file called HelloWorld.java in your_tutorial_home directory (which you should have copied over from scripts). This file is the HelloWorld application, which you will compile and run. Figure 2-3 shows the file.

Figure 2-3 The HelloWorld application

The HelloWorld application attempts to load the Cloudscape JDBC driver. If it succeeds, it prints a message. If it fails, it prints an error message.

  1. Open a command window and change directories to your_tutorial_home.
  2. Run your setclasspath script (see Running the Script).
  3. Compile the program. The following program uses the JVM included with the standard JDK:

    javac HelloWorld.java

  4. Run the program, using the -D parameter to set cloudscape.system.home:

    java -Dcloudscape.system.home= your_tutorial_system HelloWorld

    For example, if your tutorial system directory is d:\mysystem, you would invoke the program like this:

    java -Dcloudscape.system.home=d:\mysystem HelloWorld

    Java class names are case sensitive.

    If the program successfully loads the Cloudscape JDBC driver, it prints the following message:

    Loaded the cloudscape JDBC driver. Hello, World!

    If the program prints out the error message instead, check your class path. Reread Getting Acquainted with Class Path if you got your class path wrong.

  5. Keep the command window open for the rest of this lesson.

Experiment: Try to Get an Error

As an experiment, deliberately try to get an error with this program. Here are some possibilities:

  • Deliberately omit the main Cloudscape engine library from yourClassPath.

    The JVM will not be able to find Cloudscape.

    Be sure to restore it after trying this!

  • Change slightly the text of the Cloudscape JDBC driver name (COM.cloudscape.core.JDBCDriver) in HelloWorld.java, then recompile the program.

    The JVM will not be able to find the Cloudscape driver class.

  • Move the main Cloudscape engine library from its current location.

    The JVM will not be able to find Cloudscape because its location is not in the class path.

    Be sure to move it back after trying this!

All three possibilities will cause the program to fail because the JVM will not be able to find the Cloudscape JDBC driver.