apache > db

- Home
- Apache Derby

Font size:

# Install Tomcat

- Download
- Configure and Test: Just Tomcat
  - Set CATALINA_HOME
  - Test Tomcat by itself
- Configure and Test: Tomcat + Derby
  - Step 1: Install Fortune Server Jar Files
  - Step 2: Install Fortune Server LifecycleEvent Interface
  - Step 3: Install Fortune Server Web Applications
- Test
  - FortuneQuery
  - FortuneServer
  - Try to connect with 'ij'

In this section you'll download the Tomcat software if you haven't already, install it, configure it, and verify the Derby Fortune Server web application works. You won't understand how it works under the hood -- that will be covered in later sections. This section assumes that you already installed JDK Version 1.3 or higher and the Fortune Server.

## Download

Tomcat provides the servlet/JavaServer Pages interface for the Fortune Server web application. The Fortune Server was developed using Tomcat 5.0.28 and its uses Tomcat in its standalone mode.

This section walks you through setting up Tomcat for the Fortune Server, but it only provides enough information to run the Fortune Server applications. The section on Derby and Tomcat explains details.

Download Jakarta Tomcat from http://jakarta.apache.org/tomcat and install it according to their instructions.

## Configure and Test: Just Tomcat

### Set CATALINA_HOME

The instructions for Derby include references to CATALINA_HOME, the root location of your Tomcat installation. So, if you haven't done so already, set it now.

Windows: Set CATALINA_HOME

    C:\> set CATALINA_HOME=C:\tomcat\jakarta-tomcat-5.0.28

UNIX Korn Shell: Set CATALINA_HOME

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

### Test Tomcat by itself

Startup up Tomcat:

Windows: Start Tomcat (in a console window)

    %CATALINA_HOME%\bin\startup.bat

UNIX: Start Tomcat

    $CATALINA_HOME/bin/startup.sh

Open http://localhost:8080 with your browser. You should see a welcome page that says "If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!"

If you don't see that page, you need to resolve that problem before proceeding.

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

Windows: Stop Tomcat (in a console window)

    %CATALINA_HOME%\bin\shutdown.bat

UNIX: Stop Tomcat

    $CATALINA_HOME/bin/shutdown.sh

## Configure and Test: Tomcat + Derby

### Step 1: Install Fortune Server Jar Files

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

Windows: Copy Fortune Server jar files

    C:\> copy %FORTUNE_HOME%\lib\* %CATALINA_HOME%\common\lib

UNIX Korn Shell: Copy Fortune Server jar files

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

### Step 2: Install Fortune Server LifecycleEvent Interface

Implementing the Tomcat LifecycleEvent interface lets us initialize Derby for the Tomcat JVM when Tomcat starts up and it also cleanly shuts Derby down when Tomcat is shut down. The specifics of how this works is covered in the section on Derby and Tomcat. For now, just copy the files as shown below. (The Windows command shows the copy command on three separate lines, but enter them on just one line.)

Windows: Install LifecycleEvent Interface

    C:\> mkdir %CATALINA_HOME%\server\classes\examples
    C:\> mkdir %CATALINA_HOME%\server\classes\examples\tutorial
    C:\> mkdir %CATALINA_HOME%\server\classes\examples\tutorial\derby
    C:\> copy
         %FORTUNE_HOME%\java\examples\tutorial\derby\ServerLifecycleListener.class
         %CATALINA_HOME%\server\classes\examples\tutorial\derby

UNIX: Install LifecycleEvent Interface

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

Next, register the event handler by adding the Derby entry shown below to CATALINA_HOME/conf/server.xml:

    <Server port="8005" shutdown="SHUTDOWN" debug="0">

       <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener"
            debug="0"/>
       <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"
            debug="0"/>

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

If you encounter problems, compare your server.xml file to FORTUNE_HOME/java/jta_server.xml, which is a copy of the author's server.xml.

### Step 3: Install Fortune Server Web Applications

Copy the Tomcat web applications from FORTUNE_HOME/java/ClientApps to CATALINA_HOME/webapps and unjar them.

Windows: Copy Web Applications

    C:\> copy %FORTUNE_HOME%\java\ClientApps\FS_webapps.jar %CATALINA_HOME%\webapps
    C:\> cd %CATALINA_HOME%\webapps
    C:\> jar xvf FS_webapps.jar

UNIX: Copy Web Applications

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

Extracting the FS_webapps.jar file creates two subdirectories: FortuneQuery and FortuneServer.

## Test

### FortuneQuery

The FortuneQuery web application lets you connect to a Derby database and execute an ad hoc SQL statement.

First, start Tomcat.

Next, open http://localhost:8080/FortuneQuery/ with your browser. Your browser should display a page that looks like Figure 6.

Figure 6: FortuneQuery Web Application

Enter the JDBC connection URL in the box labeled "JDBC URL". It will be described in more detail later, but briefly it contains three parts separated by semicolons. The first two specify the protocol and driver and the third specifies the database name:

    jdbc:derby:database_name

The first two never change, enter them as shown; however, the database name requires explanation. The Install Fortune Server section on connecting with ij showed how to use the FORTUNE_HOME environment variable to specify the Derby system directory. We can't use that environment variable when we fill in that box on this form; instead we need to fully expand it and include the database name. So, if my FORTUNE_HOME environment variable is set to /home/jta/demo/Fortune, then the database name for my connection URL is /home/jta/demo/Fortune/fortunes. And my complete connection URL is shown below:

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

I'll enter that string in the JDBC URL box. I'll also enter a SQL statement, but I won't terminate the SQL statement with a semicolon like I did for ij. Finally, click on the Execute SQL button, and the results are shown in Figure 7.

Figure 7: FortuneQuery Results

Go ahead and add a semicolon to the end of that query and click on the Execute SQL button again to see what the error looks like.

### FortuneServer

If you successfully completed the FortuneQuery section, then you are in an excellent position to get the FortuneServer web application working because it requires you to modify CATALINA_HOME/webapps/FortuneServer/FortuneServer.jsp to set the JDBC connection URL you figured out in the previous section.

Change this line in that file:

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

To:

    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 8.

Figure 8: FortuneServer Query

Go ahead and click on the Fetch Fortune button. This will verify that the connection to the database works. You'll see a random result, though probably not the same fortune that is output in Figure 9.

Figure 9: FortuneServer Results

### Try to connect with 'ij'

While your Tomcat server is up, applications can only connect to the fortunes database through this Tomcat instance. Go ahead and try to connect using ij just to see what that error looks like:

    $ 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';
    ERROR XJ040: Failed to start database 'fortunes', see the next exception
      for details.
    ERROR XSDB6: Another instance of Cloudscape may have already booted the
      database /home/jta/demo/Fortune/fortunes.

If you want to run an ad hoc SQL query while your Tomcat server is up, remember to use the FortuneQuery web application instead of ij.