apache > db
Apache Derby Fortune Server Tutorial
 
Font size:      

Install Fortune Server

In this section you'll configure the Fortune Server software and verify it works. It assumes that you already installed JDK Version 1.3 or higher.

Fortune Server Software Distribution

When you downloaded and extracted the Fortune Server software it created a directory hierarchy under Fortune. We'll refer to the full path to this directory as FORTUNE_HOME. It contains the subdirectories listed below:

Directory Description
doc This documentation.
fortunes The Derby 'fortunes' database all ready to go. Don't directly modify any files in this directory.
lib jar files used by the fortunes database
java Source code and built classes.
data Source cookie files.
sql SQL scripts for creating the 'fortunes' database.

For convenience, the Fortune Server software includes jar files for Derby, Jakarta Regexp, and Jakarta Math. You can also download the most current releases from the Apache web site and use those instead. If you do that, be sure to copy those files into FORTUNE_HOME/lib.

Configure

Set FORTUNE_HOME

Setting the FORTUNE_HOME variable makes it easier to talk about locations relative to your installation directory. You don't have to actually set this variable if you don't want to, but mentally replace the document references with the location on your system where you installed the Fortune Server software.

Windows: Set FORTUNE_HOME

C:\> set FORTUNE_HOME=c:\demos\Fortune

UNIX Korn Shell: Set FORTUNE_HOME

$ FORTUNE_HOME=/home/jta/demo/Fortune
$ export FORTUNE_HOME

Set CLASSPATH

The Java class path tells the Java compiler and interpreter where to find classes. It can be defined several ways, including via the CLASSPATH environment variable described in this section.

Setting up to use Derby is just a matter of setting the CLASSPATH variable to include the Derby jar files. derby.jar is the main jar file that includes the Derby database engine and the embedded JDBC driver. We'll also include derbytools.jar in the CLASSPATH because it includes ij, the SQL scripting tool, and sysinfo, which reports system information. Finally, we need to include the Jakarta Math and Regexp jar files.

Use the FORTUNE_HOME variable you set in the previous step to set CLASSPATH. Note that Windows CLASSPATH entries are separated by a semicolon(;) while UNIX entries are separated by a colon (:). The examples below split the command across several lines for readability, but you should join them back up.

Windows: Set CLASSPATH

C:\> set CLASSPATH=%FORTUNE_HOME%\lib\derby.jar;
    %FORTUNE_HOME%\lib\derbytools.jar;
    %FORTUNE_HOME%\lib\commons-math-1.0-RC1.jar;
    %FORTUNE_HOME%\lib\jakarta-regexp-1.3.jar;%CLASSPATH%

UNIX Korn Shell: Set CLASSPATH

$ CLASSPATH=$FORTUNE_HOME/lib/derby.jar:
    $FORTUNE_HOME/lib/derbytools.jar: 
    $FORTUNE_HOME/lib/commons-math-1.0-RC1.jar:
    $FORTUNE_HOME/lib/jakarta-regexp-1.3.jar:$CLASSPATH
$ export CLASSPATH

Test

Output system information with 'sysinfo'

Run the sysinfo command, as shown below, to output Derby system information:

$ java org.apache.derby.tools.sysinfo
------------------ Java Information ------------------
Java Version:    1.4.2_04
Java Vendor:     Sun Microsystems Inc.
Java home:       /opt/sun-jdk-1.4.2.04/jre
Java classpath:  /home/jta/demo/Fortune/lib/derby.jar:/home/jta/demo/Fortune/lib
/derbytools.jar:/home/jta/demo/Fortune/lib/jakarta-regexp-1.3.jar:/home/jta/demo
/Fortune/lib/commons-math-1.0-RC1.jar:.
OS name:         Linux
OS architecture: i386
OS version:      2.6.7-gentoo-r11
Java user name:  jta
Java user home:  /home/jta
Java user dir:   /home/jta/demo/Fortune
--------- Derby Information --------
[/home/jta/demo/Fortune/lib/derby.jar] 10.0.2.0 - (30301)
[/home/jta/demo/Fortune/lib/derbytools.jar] 10.0.2.0 - (30301)
------------------------------------------------------
----------------- Locale Information -----------------
------------------------------------------------------

The output on your system, of course, will be different than the output shown above, but it should reflect the location of jar files on your machine and there shouldn't be any errors. If you instead see an error like the one shown below, it means your class path is not correctly set:

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

Double check each entry in your class path to verify that the jar file is where you see it is. The example below uses the ls command to verify the location of the jar files:

$ echo $CLASSPATH
/home/jta/demo/Fortune/lib/derby.jar:/home/jta/demo/Fortune/lib/derbytools.jar:
/home/jta/demo/Fortune/lib/commons-math-1.0-RC1.jar:/home/jta/demo/Fortune/lib/
jakarta-regexp-1.3.jar:.
$ ls -l /home/jta/demo/Fortune/lib/derby.jar
-r--r--r-- 1 jta 2243527 Oct 24 11:29 /home/jta/demo/Fortune/lib/derby.jar

Connect to 'fortunes' database with 'ij'

If the sysinfo command worked in the previous section, you're ready to run ij. For now simply enter the commands as shown. You'll find out more about ij in the SQL section.

The fortunes database is in the FORTUNE_HOME directory, which makes the FORTUNE_HOME directory our Derby system directory [1]. Start up ij as shown below.

Windows: Start ij

C:\> java -Dderby.system.home=%FORTUNE_HOME% org.apache.derby.tools.ij
ij>

UNIX Korn Shell: Start ij

$ java -Dderby.system.home=$FORTUNE_HOME org.apache.derby.tools.ij
ij>

If this command succeeded, you should have that ij> prompt. If you didn't get that prompt but got an error instead, double check your class path.

If ij started correctly, go ahead and connect to the fortunes database as shown below:

ij> connect 'jdbc:derby:fortunes';

Notice that commands in ij are terminated with a semicolon (;). Now execute a SQL statement that returns the number of rows in the fortunes table:

ij> select count(*) from fortunes;
1
-----------
13685
     
1 row selected

Voila! Connecting and doing a query verifies several things:

  • The Java interpreter found derbytools.jar.
  • The Java interpreter found derby.jar.
  • Derby found the fortunes database.

Now do two more queries. The first query executes the tutRand SQL function with the SQL VALUES[2] statement, which verifies that Derby can find the Jakarta Math jar. Incidentally, you probably won't get the value shown below because tutRand returns a random integer. The second query executes the tutMatch SQL function and verifies that Derby can find the Jakarta Regexp jar file.

ij> values tutRand(1,500);
1
-----------
123
     
1 row selected

ij> values tutMatch('abc', 'a');
1
-----------
1
     
1 row selected

Congratulations! You're all done verifying that the database side of the Fortune Server is setup and ready to go. Quit out of ij as shown below:

ij> disconnect;
ij> quit;

By the way, if you don't execute that disconnect command, don't worry. Nothing bad will happen. It's alright to just quit out of ij.

End Notes

[1]: Derby System Home

The Derby system home is the directory where Derby starts up. The databases that belong to the Derby system are all in this subdirectory. If you don't specify derby.system.home, Derby uses the current directory. The tutorial examples show explicitly setting derby.system.home. You can also simply cd into the FORTUNE_HOME directory.

[2]: "VALUES" SQL Statement

The VALUES SQL statement simply executes a SQL expression. This page uses it to execute the tutRand and tutMatch SQL functions. Note that SQL commands are case-insensitive, so you can use VALUES, or values, VaLuEs or whatever combination of upper- and lower-case that you prefer.