Cloudscape Database Applications
Page 4 of 5

Handling SQLExceptions

HelloWorldApp lacks two basic steps to make it a real embedded Cloudscape application: SQLException handling and shutting down Cloudscape. As you learned in Lesson 2, "Cloudscape Basics and the Sample Database", it is important for an application to shut down Cloudscape before exiting the JVM so that Cloudscape can issue a checkpoint.

Quiz: Do Cloudscape client/server applications shut down Cloudscape?

Answer: No. A server by definition runs continuously. Client applications connecting to a server should end by disconnecting only, not by shutting down.

Methods that access a Cloudscape database can throw SQLExceptions if something goes wrong during database access. Applications should handle SQLExceptions to get the details. For example, if the SQL-J statement specifies columns that do not exist, an SQLException is thrown.

Figure 5-6 How HelloWorldApp needs to be modified

The catch block of HelloWorldApp should treat exceptions in a more sophisticated manner and thus make HelloWorldApp a real Cloudscape application.

HelloWorldExc is a duplicate of HelloWorldApp, except that it makes the additions we identified in Figure 5-6:

  • It processes SQLExceptions.
  • It introduces a mistake in the SQL-J statement so that when you run it, the program displays error information from the SQLException.
  • It shuts down Cloudscape properly.

Change the logSeverityLevel Property

You have already been working with one Cloudscape property, which is a configuration parameter for a Cloudscape database or application session. You have been setting the cloudscape.system.home property as a command-line option to the JVM every time you have run an application.

You can also set a property in a file called cloudscape.properties. This file is not included with the product; you must create it and edit it yourself. This file is one of the files from the /demo/programs/tours/scripts directory that you copied into your home or working directory.

In this task you will set the value of the cloudscape.stream.error.logSeverityLevel property so that you can see all errors written to the information log, regardless of their severity.

  1. Copy the cloudscape.properties file into the your_tutorial_system directory.
  2. Open the cloudscape.properties file in the your_tutorial_system directory.

    The file already sets one property:

    cloudscape.infolog.append=true

    This setting means that every time Cloudscape starts up, it appends to the information log (cloudscape.LOG) instead of overwriting it.

  3. Set the value of cloudscape.stream.error.logSeverityLevel to 0 by adding the following line at the end of the file:

    cloudscape.stream.error.logSeverityLevel=0

  4. Add a carriage return after the line, and save the file.

    This value means that Cloudscape will write errors of any severity level to the log. The error in HelloWorldExc is of a minor severity and so would not be written to the log using the default value for this property.

Compile, Run, and Examine HelloWorldExc

  1. Return to your open command window, set to the your_tutorial_home directory.
  2. Compile the HelloWorldExc.java file.

    The errors in the SQL-J statement are not detected by the compiler (the error will be detected by Cloudscape at runtime), so it should compile correctly.

  3. Run the program from the your_tutorial_home directory:

    java -Dcloudscape.system.home= your_tutorial_system
        HelloWorldExc

    The program displays information about the error as it runs. Some of this information may also be written to the information log.

    Quiz: Do you remember where the information log is? (See Examine the System Directory and Information Log.)

  4. Open and examine the HelloWorldExc.java source file.

    To shut down Cloudscape, the program includes the shutdown command in a separate try block.

    Quiz: You issue the shutdown command as an attribute to a database connection URL in a call to the DriverManager.getConnection method. What else can you do with this method?

    Answer: Connect to databases and create new ones.

A successful shutdown command always raises an SQLException in Cloudscape. This may seem counterintuitive, but it does this to let you know that no connection is available. The catch block checks that the SQLException was issued correctly but does not process it.

Figure 5-7 Catching the SQLException

The main catch block catches exceptions, as shown in Figure 5-8. If an exception is an instance of an SQLException, it processes the exception to display information about it.

Figure 5-8 Processing SQLExceptions.

SQLExceptions return information about the SQLState and the ErrorCode. SQLStates are standard, ISO-defined codes describing the nature of the error. ErrorCodes are vendor-specific codes. In Cloudscape, these codes describe the severity of the error.

In addition, the JDBC specification states that a single error can generate more than one SQLException; an SQLException object can be "chained." Use a loop and the getNextException method to process all SQLExceptions in the chain.

Cloudscape SQLExceptions use SQLState class codes starting with X. Cloudscape returns standard SQLState values or exceptions where appropriate.

Closing Statements and ResultSets

HelloWorldExc explicitly closes Connections, Statements, and ResultSets when they are no longer needed. Connections to Cloudscape are resources external to an application, and the garbage collector may not close them automatically.