apache > db
Apache Derby Fortune Server Tutorial
 
Font size:      

Quick Start

This section assumes that you already know Derby and understand what its embedded mode is, and that you already know how to install and configure Tomcat. If you don't know Derby and Tomcat, then you might consider starting with the Novice Start section instead.

Install JDK

Derby requires JDK version 1.3 or higher. The Fortune Server was developed using JDK 1.4.

Install the JDK, if you haven't already. No specific vendor implementation is required. Java's reference implementation is at http://java.sun.com/j2se/.

Install Fortune Server

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. These instructions assume you will copy those files into FORTUNE_HOME/lib.

Configure

Examples in this section use UNIX Korn shell syntax. Set FORTUNE_HOME to the location where you installed the Fortune Server software; for example, the way the author sets it is shown below:

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

Set CLASSPATH to include all the jar files in FORTUNE_HOME/lib. For readability in print format, the example below is split across multiple lines:

$ 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

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

$ java org.apache.derby.tools.sysinfo

If you get an error instead of what looks like valid version information, double check your class path.

Also make sure you can run ij. FORTUNE_HOME is the Derby system directory and the Fortune Server database name is fortunes, so you should be able to start up and connect as shown below:

$ java -Dderby.system.home=$FORTUNE_HOME org.apache.derby.tools.ij
ij version 10.0 (C) Copyright IBM Corp. 1997, 2004.
ij> connect 'jdbc:derby:fortunes';
ij> select count(*) from fortunes;
1
-----------
13685
     
1 row selected

Verify with the SQL statements shown below that Derby can find the Jakarta Math and Regexp libraries:

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

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

Quit out of ij before configuring Tomcat for Derby -- remember that a Derby database can be accessed by only one JVM and we want that to be the Tomcat JVM for the next section. (If you're wondering what on earth that preceding sentence meant, see the description of Derby's embedded architecture in the Novice Start Introduction).

Install Tomcat

Download

The Fortune Server was developed using Tomcat 5.0.28 and its uses Tomcat in its standalone mode.

If you don't already have Tomcat installed, download it from http://jakarta.apache.org/tomcat and install it according to their instructions.

Configure

Set CATALINA_HOME to the root location of your Tomcat installation:

$ CATALINA_HOME=/home/jta/Jakarta/jakarta-tomcat-5.0.28
$ export CATALINA_HOME

If you just installed Tomcat, verify it works. Start it up and open http://localhost:8080 with your browser. If you don't see the Tomcat welcome page, resolve that problem before proceeding.

Once you have Tomcat successfully up and verified working, shut it down to configure for Derby.

There are several steps to configuring Tomcat for Derby.

Step 1: Install Fortune Server Jar Files

Copy all Fortune Server jar files to CATALINA_HOME/common/lib:

$ cp $FORTUNE_HOME/lib/* $CATALINA_HOME/common/lib

Step 2: Install Fortune Server LifecycleEvent Interface

The LifecycleEvent interface initializes Derby for the Tomcat JVM when Tomcat starts up and shuts Derby down when Tomcat is shut down (and this is explained in the Tomcat section at the end of this tutorial). Create the $CATALINA_HOME/server/classes/examples/tutorial/derby directory hierarchy, then copy the LifecycleEvent interface into it:

$ cp $FORTUNE_HOME/java/examples/tutorial/derby/ServerLifecycleListener.class \
     $CATALINA_HOME/server/classes/examples/tutorial/derby

Add the entry shown below to CATALINA_HOME/conf/server.xml to register the event handler:

<Listener className="examples.tutorial.derby.ServerLifecycleListener"
     debug="0" />

Step 3: Install Fortune Server Web Applications

Copy the Tomcat web applications and unjar them:

$ cp $FORTUNE_HOME/java/ClientApps/FS_webapps.jar $CATALINA_HOME/webapps
$ cd $CATALINA_HOME/webapps
$ jar xvf FS_webapps.jar

You'll see two new subdirectories: FortuneQuery and FortuneServer.

Test

Start the Tomcat server and open http://localhost:8080/FortuneQuery/ with your browser. Your browser should display a page that looks like Figure 2.

Figure 2: FortuneQuery Web Application

Figure 2: FortuneQuery Web Application

Enter the JDBC connection URL in the box labeled "JDBC URL". The database name should be the complete path: FORTUNE_HOME + fortunes. For example, the author's complete connection URL is shown below:

jdbc:derby:/home/jta/demo/Fortune/fortunes

Enter a SQL statement, but don't terminate the SQL statement with a semicolon like you do for ij. Finally, click on the Execute SQL button. You should see results something like those shown in Figure 3.

Figure 3: FortuneQuery Results

Figure 3: FortuneQuery Results

If the FortuneQuery web application succeeded, you're ready to get the FortuneServer web application working. Replace the JDBC connection URL in CATALINA_HOME/webapps/FortuneServer/FortuneServer.jsp with your JDBC connection URL.

You need to change the current setting shown below:

String varJdbcUrl = "jdbc:derby:/home/jta/demo/Fortune/fortunes";

Change it to your URL:

String varJdbcUrl = "jdbc:derby:your_FORTUNE_HOME_path/fortunes";

Now open http://localhost:8080/FortuneServer with your browser. You should see an initial page that looks like Figure 4.

Figure 4: FortuneServer Query

Figure 4: FortuneServer Query

Go ahead and click on the Fetch Fortune button. This will verify that the connection to the database works.