IBM Cloudscape: Understanding Java class path

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Introductory

Jean Anderson (jander@us.ibm.com), Cloudscape Community Architect, IBM
Susan Cline (clines@us.ibm.com), Cloudscape Community Developer, IBM

15 Sep 2004

IBM® Cloudscape™ is the commercial version of Derby, which is a small-footprint Java™ database that doesn't require any installation or administration. However, since it is implemented entirely in Java, understanding the Java class path is the key to a trouble free -- and not a troublesome! -- installation. This article explains what Java class path is, how to set it for different versions of Cloudscape and Derby, and how to troubleshoot any problems that might occur.

IBM Cloudscape & Derby

IBM contributed a copy of IBM Cloudscape 10.0 to the Apache Software Foundation in August 2004, which the ASF accepted into the incubator as Derby. Moving forward, Derby is the base relational database management system (RDBMS) engine, and IBM Cloudscape is the commercial product that distributes Derby with additional features for developers, such as the sample databases, examples, and scripts mentioned in this technical article.

Back to top

Java class path

The Java class path tells the java interpreter and the javac compiler where to find the classes they need to execute or import. Classes (those *.class files you might have noticed) can be stored in directories or in jar files, or in a combination of both, but the Java compiler or interpreter won't be able to find them unless they are somewhere in your class path.

Multiple entries in the class path are separated by a semicolon on Windows® (;) and by a colon on UNIX® (:). In the example below, the class path includes two Derby jar files (derby.jar and derbytools.jar), and a directory location (myDevDir) that stores *.class files:

Windows class path:
C:\Derby\lib\derby.jar;C:\Derby\lib\derbytools.jar;C:\myPath\myDevDir

UNIX class path:
/Derby/lib/derby.jar:/Derby/lib/derbytools.jar:/myPath/myDevDir

The rest of the examples in this technical article use Windows syntax. So, if you are on a UNIX machine, please adjust the syntax accordingly.

Back to top

Derby class path

The Derby class path lets you store jar files in the database itself.

In Derby, the sqlj.install_jar() procedure installs a jar file into the database and the SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY procedure sets the derby.database.classpath property. Derby first looks in your Java class path for a class, then it looks in the database class path.

We mention Derby class path to make you aware of the capability, but the rest of this article focuses on the Java class path.

Back to top

Setting Java class path

There are three ways to set the Java class path:

• Permanently by setting the CLASSPATH environment variable at the system level.
• Temporarily by setting the CLASSPATH environment variable in a command window or shell.
• At runtime by specifying the class path each time you start your Java application and the JVM.

Examples for setting class path each way are in the sections below and assume you have installed the IBM Cloudscape 10.0 distribution and set the CLOUDSCAPE_INSTALL environment variable to the root location for that installation; for example:

C:\>set CLOUDSCAPE_INSTALL=C:\Derby

If you have installed just the base Derby software, not the IBM Cloudscape 10.0 distribution, this technical article will still have good tips for you, but you won't have the sample programs that are referenced. For readability in this technical article, commands are often broken across several lines. Also, remember that the Java class path is composed of one or more entries, separated by a semicolon on Windows (;) and by a colon on UNIX (:). The examples show Windows syntax, which you must adjust for UNIX.

Setting class path permanently

Figure 1 sets the Windows environment variable permanently, using the Control Panel's System Settings to add a new variable called CLASSPATH.

A UNIX user can set the class path permanently by adding the CLASSPATH variable to his or her .profile or .cshrc file.

Setting class path temporarily

The SimpleApp client class is included in the IBM Cloudscape 10.0 software distribution in %CLOUDSCAPE_INSTALL%\demo\programs\simple. The %CLOUDSCAPE%\lib\derby.jar file is required to run this class in embedded mode. Listing 1 shows how to temporarily set CLASSPATH in a Windows command window to include derby.jar and the current working directory before running SimpleApp.

C:\>set CLASSPATH=%CLOUDSCAPE_INSTALL%\lib\derby.jar;.
C:\>cd %CLOUDSCAPE_INSTALL%\demo\programs\simple
C:\Derby\demo\programs\simple>java SimpleApp
SimpleApp starting in embedded mode.
Loaded the appropriate driver.
Connected to and created database derbyDB
Created table derbyDB
Inserted 1956 Webster
Inserted 1910 Union
Updated 1956 Webster to 180 Grand
Updated 180 Grand to 300 Lakeshore
Verified the rows
Dropped table derbyDB
Closed result set and statement
Committed transaction and closed connection
Database shut down normally
SimpleApp finished 

If you set the class path temporarily, each time you open a new command window you need to set it again.

Setting class path at runtime

Listing 2 shows how to use the -cp option to specify the class path at runtime, which is when the application is launched and the JVM is started.

C:\Derby\demo\programs\simple>java -cp 
         %CLOUDSCAPE_INSTALL%\lib\derby.jar; SimpleApp
SimpleApp starting in embedded mode.
Loaded the appropriate driver.
Connected to and created database derbyDB
Created table derbyDB
Inserted 1956 Webster
Inserted 1910 Union
Updated 1956 Webster to 180 Grand
Updated 180 Grand to 300 Lakeshore
Verified the rows
Dropped table derbyDB
Closed result set and statement
Committed transaction and closed connection
Database shut down normally
SimpleApp finished 

Back to top

An 'ij' example

Now let's look at a complete example that shows how to set your class path to run ij, the Derby SQL scripting tool. Listing 3 sets the CLASSPATH environment variable to the bare minimum required by Derby to run ij.

C:\>set CLOUDSCAPE_INSTALL=C:\Derby
C:\>set CLASSPATH=%CLOUDSCAPE_INSTALL%\lib\derby.jar;
     %CLOUDSCAPE_INSTALL%\lib\derbytools.jar
C:\>echo %CLASSPATH%
C:\Derby\lib\derby.jar;C:\Derby\lib\derbytools.jar

If CLASSPATH is set correctly and the software really is installed in C:\Derby, the command shown in Listing 4 reports useful version information:

C:\>java org.apache.derby.tools.sysinfo
------------------ Java Information ------------------
Java Version:    1.4.2_05
Java Vendor:     Sun Microsystems Inc.
Java home:       C:\Program Files\Java\j2re1.4.2_05
Java classpath:  C:\Derby\lib\derby.jar;C:\Derby\lib\derbytools.jar
OS name:         Windows XP
OS architecture: x86
OS version:      5.1
Java user name:  jander
Java user home:  C:\Documents and Settings\Administrator
Java user dir:   C:\
--------- Derby Information --------
[C:\Derby\lib\derby.jar] 10.0.2.0 - (30301)
[C:\Derby\lib\derbytools.jar] 10.0.2.0 - (30301)
------------------------------------------------------
----------------- Locale Information -----------------
------------------------------------------------------

And with the Java class path set correctly, we should be able to successfully start ij, as shown below:

C:\>java org.apache.derby.tools.ij
ij version 10.0 (C) Copyright IBM Corp. 1997, 2004.
ij> 

However, if the class path is set incorrectly, the command that should output version information instead outputs a frustrating NoClassDefFoundError error:

C:\>java org.apache.derby.tools.sysinfo
Exception in thread "main" java.lang.NoClassDefFoundError: 
               org/apache/derby/tools/sysinfo

The ClassNotFoundException and NoClassDefFoundError errors are common when the class path is not set properly. The first means the class itself can't be found. The second means the class was found, but a class that it imports wasn't. For more information, see the section titled Common Class Path Errors.

Back to top

Derby / Cloudscape library and package names

The names of various objects -- such as libraries, packages, drivers, and tools -- change between product releases. Table 1 below summarizes Derby and Cloudscape names for several versions. For complete information about names, consult the documentation in your software distribution.

Table 1. Derby/Cloudscape libraries and packages

Listings 1 and 2 showed how to run the %CLOUDSCAPE_INSTALL%\demo\programs\simple\SimpleApp in embedded mode. Embedded mode is very simple and only requires including derby.jar in the class path.

You can also run the SimpleApp example in network server mode. To start the network server, include the libraries listed below in your class path:

• derby.jar
• derbynet.jar

Next, to run SimpleApp in network server mode, include the libraries listed below in your class path:

• derbytools.jar (optional, for example to use 'ij')
• db2jcc.jar
• db2jcc_license_c.jar

Back to top

Troubleshooting problems

Common class path errors

There are two major types of class path problems. The first occurs when a Java class you are trying to use is not found in the class path, so it throws a java.lang.ClassNotFoundException exception. The second problem occurs when the class you are trying to use is found, but one of the classes it imports is not found. In this case, at compile time the imported classes were present, but at run time the imported class was not part of the class path. This will throw a java.lang.NoClassDefFoundError exception. Another way to think of the NoClassDefFoundError is to say that the searched-for class definition existed when the currently executing class was compiled, but the definition can no longer be found at runtime.

How can you fix this? Check your class path and verify that the libraries really are where you think they are. For example, on Windows use this command to output your class path:

C:\>echo %CLASSPATH%
C:\Derby\lib\derby.jar;C:\Derby\lib\derbytools.jar

Look at each entry in the CLASSPATH variable and check with the dir (Windows) or ls (UNIX) command to see if those files exist.

If you don't know which jar file the class is in you can check with this command:

jar -tvf cs.jar | more

That produces a lot of output. If you are using Linux or Unix, or UNIX utilities on Windows, you can use grep to filter out for the class you're looking for. For example, the command below looks for the org.apache.derby.tools.sysinfo class:

C:\Derby\lib>jar tvf derby.jar | grep -i org.apache.derby.tools.sysinfo
  1550 Thu Aug 12 14:04:16 PDT 2004 org/apache/derby/tools/sysinfo.class

Another way to search for a class using the sysinfo utility is described in the next section.

Verify you have everything you really need

Derby includes a sysinfo tool with a -cp option that verifies the class path. For complete information, see the Tools and Utilities Guide in your software distribution.

Used without additional arguments, the -cp option tests for all Derby libraries, outputting the libraries it can find as well as the ones it cannot, as shown below:

C:\>java org.apache.derby.tools.sysinfo -cp
Testing for presence of all Derby-related libraries; typically, 
only some are needed.  For a list of possible arguments, type 
java org.apache.derby.tools.sysinfo -cp args

FOUND IN CLASS PATH:

   Derby embedded engine library (derby.jar)


   Derby tools library (derbytools.jar)


NOT FOUND IN CLASS PATH:

   Derby Network Server library (derbynet.jar)
    (org.apache.derby.drda.NetworkServerControl not found.)


   Cloudscape Client libraries (db2jcc.jar)
    (com.ibm.db2.jcc.DB2Driver not found.)

Optional arguments to the -cp option include:

• embedded
• tools
• sampleApp
• anyClass.class

The example below looks for the SimpleApp class in the class path:

C:\Derby\demo\programs\simple>java org.apache.derby.tools.sysinfo 
    -cp SimpleApp.class

FOUND IN CLASS PATH:


NOT FOUND IN CLASS PATH:

   user-specified class (SimpleApp)
    (SimpleApp not found.)

Remember to include your current working directory in your path if you want to run a class in it:

C:\Derby\demo\programs\simple>set CLASSPATH=%CLASSPATH%;.

C:\Derby\demo\programs\simple>echo %CLASSPATH%
C:\Derby\lib\derby.jar;C:\Derby\lib\derbytools.jar;.

C:\Derby\demo\programs\simple>java org.apache.derby.tools.sysinfo 
     -cp SimpleApp.class

FOUND IN CLASS PATH:

   user-specified class (SimpleApp)


SUCCESS: All Derby related classes found in class path.

Finally, to test your class path for Cloudscape 5.1, use the 5.1 package name instead, for example:

java com.ibm.db2j.tools.sysinfo -cp 

About the authors

		Jean Anderson and Susan Cline work together to develop technical content for Cloudscape developers and users.

		'

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top