Cloudscape Basics and the Sample Database
Page 5 of 6

Working with Connections

Once an application has loaded the Cloudscape JDBC driver, the application can connect to an existing database or create a new database. All of the application's interactions are then handled through the JDBC API, the classes and methods of java.sql.

Applications connect to databases (and create them, if they do not exist) with the java.sql.DriverManager.getConnection method. Applications specify a database connection URL as a String parameter to this method. Calling this method with the appropriate URL string returns a connection to a database.

Cloudscape's database connection URL consists of four parts, as shown in Figure 2-4.

Figure 2-4 Syntax of the Cloudscape database connection URL

The first two never change; the third part (which is optional) indicates the name of the database you want to connect to. The fourth part consists of zero or more attributes. An attribute is how we will specify that we want to create a new database (instead of connecting to an existing one).

In this section, we will create a database called HelloWorldDB. Creating this database requires a database connection URL as shown in Figure 2-5.

Figure 2-5 This Cloudscape database connection URL creates a new database called HelloWorldDB.

Get a Connection: Create a Database

In this project, you will run a Java program that creates a new database.

  1. Open CreateWorldDB.java, which includes the new code shown in Figure 2-6.

Figure 2-6 This Cloudscape database connection URL creates a new database called HelloWorldDB.

  1. Return to your open command window and compile the file:

    javac CreateWorldDB.java

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

    java -Dcloudscape.system.home= your_tutorial_system CreateWorldDB

    Quiz: What would happen if you forgot to set cloudscape.system.home?

    Answer: Cloudscape would build the database in the current directory.

  3. If it runs successfully, you should see the following output:

    Loaded the cloudscape JDBC driver. Hello, World!

    Created and connected to database HelloWorldDB

Shut Down Cloudscape

As you saw, starting up Cloudscape was a separate step from getting a connection to a database. Shutting down Cloudscape is likewise a separate step.

It is important to shut down Cloudscape when the application is through interacting with embedded Cloudscape, because the shutdown command ensures that all changes are written from the database log (a temporary holding place for transactions) to the actual database. If you do not shut down Cloudscape, the next time it starts up, it takes the time to run recovery on the databases in the system. Recovery means restoring a database to its last committed state after a system failure (or stopping the application without a shutdown command) based on information stored in a special area called the database log.

In this task, you will delete HelloWorldDB, edit the CreateWorldDB program to include disconnect and shutdown commands, and rerun the program.

  1. Delete the HelloWorldDB directory in the your_tutorial_system directory. (Use operating system commands).
  2. Edit the CreateWorldDB.java file by adding the following code:

    conn.close();

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

    NOTE: These two lines go at the end of the try block, right before the curly brace, and right after the following line (line 13):

    System.out.println(
        "Created and connected to database HelloWorldDB");

  3. Return to your open command window and recompile.
  4. Run the program:

    java -Dcloudscape.system.home= your_tutorial_system
        CreateWorldDB

    This time, if the program runs successfully, it will display an error message as follows:

    Loaded the cloudscape JDBC driver. Hello, World!

    Created and Connected to the HelloWorldDB database

    exception thrown

    SQL Exception: CloudscapeSystemShutdown

    at COM.cloudscape.$18.$893.$1187(Unknown Source)

    at COM.cloudscape.$18.$893.$1187(Unknown Source)

    at COM.cloudscape.$18.$893.$1153(Unknown Source)

    at COM.cloudscape.$18.$1068.connect(Unknown Source)

    at java.sql.DriverManager.getConnection(DriverManager.java:91)

    at java.sql.DriverManager.getConnection(DriverManager.java:149)

    at CreateWorldDB.main(CreateWorldDB.java:15)

    The output shows an error because successful shutdown commands generate an SQLException. In Lesson 5, "Cloudscape Database Applications", you will learn how to catch this particular exception to avoid printing an error message.

Examine the System Directory and Information Log

Your application has now created and interacted with a Cloudscape database.

Examine the contents of your system directory. The directory should now include:

  • The information log, cloudscape.LOG

    Open up this file and examine the contents. It should contain text similar the following:

    Sun Oct 04 13:28:00 PDT 1998:

    Booting Cloudscape version 3.6: instance 80000000-00d3-4d2c-ca4d-000a0a0b4300

    on database at directory D:\my_system_directory\HelloWorldDB

    Sun Oct 04 13:28:07 PDT 1998:

    Shutting down cloudscape instance 80000000-00d3-4d2c-ca4d-000a0a0b4300

    As you can see, the log shows more than just errors--it shows information about system booting and shutdown.

  • A directory called HelloWorldDB (this is where Cloudscape stores the data, folks!)

    Open up this directory and look at what's inside; it contains two subdirectories and two files. You can learn more about what those are in the Cloudscape documentation set.