Introduction
Goals
This Novice Getting Started section introduces the Derby relational database and its embedded architecture, which is what the Fortune Server uses. It walks you through installing the Fortune Server software, setting your environment up, and configuring Tomcat to access Derby. The Fortune Server distribution includes everything already built and ready to go, so you run the Fortune Server to verify everything works properly.
So, after successfully completing the Getting Started section, the Fortune Server will be up and running. Later sections dive down into how to create the Fortune Server.
But first we'll introduce some basic Derby Concepts.
Derby Concepts
Derby is a relational database, and to be quite honest there are quite a few of those out there these days, so you might wonder why you should care. But Derby's claim to fame is its pure Java implementation, ease of use, small footprint, and zero administration.
Relational Database
Derby is a complete relational database engine with all the features you expect, including transaction management, concurrency control, recovery, backup and restore. It is SQL 92 compliant (with some SQL 99 features), so it supports tables, indexes, views, triggers, stored procedures, SQL functions, temp tables, primary/foreign keys and check constraints. Performance features include cost-based optimization, data caching, statement caching, and a write ahead log. And, of course, it supports multiple databases per system.
This tutorial exercises just a few of Derby's relational capabilities. For example, it shows how to create tables with keys and check constraints and it shows how to execute SQL statements. For complete information about Derby's SQL features, see the Derby Reference Manual.
Java Implementation
Derby is implemented completely in Java, which means you can develop on one platform then deploy to any platform with a JVM of 1.3 or higher -- database and all. The small footprint of the database "engine", which is encapsulated in the derby.jar file and includes the embedded JDBC driver, lets you embed it right into a Java application, making it disappear completely from sight. Applications can silently deploy derby.jar and their database(s), removing the requirement to separately install, configure, and manage a database.
This tutorial exercises some JDBC capabilities. For example, it shows how to insert fortunes into a Derby database and it shows how to fetch data back. For complete information about developing JDBC applications for Derby, see the Derby Developer's Guide.
Embedded Architecture
When using Derby in its embedded mode, the application boots the database and shuts it down. There are no separate database processes to start up and shut down.
The Fortune Server, which is depicted in Figure 5, uses Derby in its embedded mode.
Figure 5: Fortune Server Software Architecture

Tomcat is the main, visible application behind the Fortune Server. Derby is just a jar file that supports the operations that the Tomcat application performs; and the fortunes database is stored on disk under a subdirectory hierarchy named fortunes. When Tomcat starts up, it loads the Derby embedded JDBC driver, which starts Derby. When Tomcat shuts down, it explicitly shuts Derby down. (You'll see how Tomcat does this later.)
Derby runs in Tomcat's JVM. There are no additional database processes, so Derby is completely invisible to end users when running in this embedded mode.
However, there is one drawback to embedded mode and that is a database can only be accessed by one JVM. So, while Tomcat is up and connected to the fortunes database, applications can only connect to the fortunes database via that Tomcat process. You can't connect to the fortunes database from an application running in a different JVM. A common mistake is to attempt to connect to a database while an embedded application is running from another application, such as ij, the SQL scripting utility. To satisfy that desire to execute ad hoc queries, the Fortune Server includes a web application to do that through Tomcat.
Network Server Architecture
Derby also supports a traditional client/server configuration when it is embedded in a server framework that accepts and processes network communications. Advantages include:
- Ability for applications from more than one JVM to access a database.
- Support for other languages, such as ODBC.
The Derby Network Server provides such a server framework using the Distributed Database Architecture (DRDA) network protocol to receive requests from and send replies to client. Since it talks DRDA, clients that connect to it must also use that protocol. The IBM DB2 Universal JDBC driver and the IBM DB2 Application Development and Run-Time Client Version 8.2 support Derby databases for JDBC and ODBC. Both are available for free download from IBM developerWorks, but we hope that open source components will emerge soon in the Derby community.
We mention the Network Server for completeness, but this tutorial focuses exclusively on Derby's embedded mode. If you want to know more about the Network Server, see the Derby Server and Administration Guide.