Apache Derby Fortune Server Tutorial

Apache Derby, an Apache DB project, is a relational database implemented in Java. Its footprint is so small you can embed it in any Java-based solution -- with no requirement for database installation and administration. This makes Derby easy to develop on, easy to run, and easy to deploy.

The Apache Derby Fortune Server, referred to as simply "Fortune Server" throughout most of this tutorial, stores fortunes in a Derby database and dispenses them like the UNIX fortune command does. But its real mission in cyber-life is to be a novice tutorial that teaches the basics of Derby and shows a couple ways to integrate it with other Apache products, all within Derby's easy-to-use embedded environment.

This tutorial is intended for novices who have had at least light exposure to SQL, Java and Web applications, but are new to Derby. All source code used in the tutorial is either simple or "fill in the blank", so lack of experience in any of these areas should not be a barrier.

The tutorial is organized into the sections below:

• The Introduction describes the functionality of the Apache Derby Fortune Server.
• The Getting Started section introduces basic Derby concepts, then walks through installing, configuring, and running the Fortune Server. If you just want to install and run the Fortune Server, and avoid implementation details entirely, this section is for you.
• The SQL section provides nitty gritty details about the Fortune Server database and shows how to work with databases using ij, the Derby SQL scripting tool.
• The Java/JDBC section describes the Fortune Server components that are implemented in Java and/or JDBC. It covers a few basics, then shows how to implement JDBC code that fetches data from and inserts data into a Derby database. It also shows how to implement SQL functions in Java that execute code in other software, including:
  • How to create a SQL function that generates a random number using the Jakarta Mathematics Library.
  • How to create a SQL function that performs regular expression searches using Jakarta Regexp.
• The Tomcat section shows a way to embed Derby in Jakarta Tomcat and provides a couple web applications that query the Derby database.

• Download the Apache Derby Fortune Server distribution [tar.gz] [zip]. Extract it, then open Fortune/doc/index.html with your web browser. That opens a local copy of this page. A good place to start is the Introduction, which describes the functionality of the Fortune Server.

• Download and install Jakarta Tomcat 5.0.28 from http://jakarta.apache.org/tomcat.

Jean Anderson (jta@bristowhill.com) developed this tutorial. Email her any problems or post them to the Derby user mail list (http://db.apache.org/derby/derby_mail.html).

The Fortune Server embeds Derby in Tomcat by using the "casual" scenario from Lance Bader's IBM developerWorks article titled "Integrating Cloudscape and Tomcat: A cookbook for adding the database manager into the servlet container", which is available at http://www.ibm.com/developerworks/db2/library/techarticle/dm-0408bader. Bader's article was developed on Cloudscape 5.1. Susan Cline (slc@MeepZor.Com) helped Jean update it to work with Derby. Susan also contributed the FortuneServer and FortuneServer2 JavaServer Pages.

Apache Forrest was used for generating the web-based materials.

Changes to the Fortune Server Tutorial are summarized in the table below.