Use Derby in a J2EE Server environment

Set up Derby as a Resource Manager in a J2EE app server

IBM ® Cloudscape ™ is a freely available repackaging of the Apache Derby relational database manager. J2EE ™ Servers are middleware software based on Sun's Java Enterprise Edition (J2EE) specification that bundle a number of Java Service technologies into an integrated system. Most J2EE applications require that a JDBC-compliant database be integrated with the Server to store information. This article shows how to best fit IBM Cloudscape or Derby into a J2EE environment and has been updated to feature WebSphere® Application Server Community Edition as an example.


Stanley Bradbury (, Community Coordinator - Cloudscape, IBM, Software Group

Stanley Bradbury is currently working as Community Coordinator with the Cloudscape group at IBM. Before this he provided third level support to Cloudscape customers (2001 to 2005). Prior to working with Cloudscape he managed databases for companies in the Biotech, Manufacturing and Internet Security Service industries. He is a graduate of the University of California at Berkeley and enjoys spending time with his family.

15 June 2006 (First published 29 September 2005)

Also available in


Application Servers (also called app servers) are gaining popularity as a way to provide information and services to people at different locations without regard to the type of computer they are using. Typically the app server sits between a database or other information store (called the back end) and an end-user / customer (called the client) creating what is termed a "three-tier architecture." This article discusses setting up Derby as the back end for a system using an Application Server that is compliant with Sun's Java Enterprise Edition (J2EE) specification. In the configuration described here, the database management system (DBMS) may also be referred to by the term Resource Manager. An example of defining a WebSphere Application Server Community Edition database pool for a Derby database is provided.

IBM Cloudscape or Derby naming in this article

The IBM Cloudscape database engine is the Apache Derby database engine. IBM Cloudscape is built from the unaltered codeline downloaded from Apache. There is some confusion on this point so I wrote this article listing the short names of both products together at all times. As one reviewer put it, "Reading the phrase 'Cloudscape or Derby' over and over becomes tedious." So I adopted the convention of using the short name 'Derby' throughout, unless the discussion is specific to IBM Cloudscape. The article reads more smoothly as a result.

Most app servers today are based on the J2EE specification though others types exist. The popularity of the J2EE based systems stems from them being non-proprietary. They have been readily adopted by both the open source and open architecture communities. These versatile Servers inherit the Java capability to "run anywhere". Because the Apache Derby engine is also implemented in Java, it integrates cleanly and will run unaltered anywhere a J2EE Server will run.

If you have experience with Application Servers, you may want to skip to the next paragraph. Otherwise, this paragraph will present a simplified conceptualization of an app server system to help with understanding the remainder of the article. For the sake of getting a handle on the subject, you can think of the J2EE Application Server as the software-in-the-middle that "runs" one or more useful Java-based applications. It brings together (bundles) the technologies needed not only to support the application but also to allow people connected to a network to safely use the application(s). The app server manages the middle-tier components that perform most of the heavy lifting. The client tier is typically a person using a Web browser to "talk" to the middle-tier. Behind and protected by the middle-tier is a business system, typically containing databases, called the back end or more recently the Enterprise Information System (EIS) tier. The applications that the Client runs within the app server can be written using a number of Application Programming Interfaces (APIs), the most common being Java (J2SE) routines, Java Server Pages (JSPs), and Servlets. A database defined to the app server environment can be accessed by applications regardless of the API used. Figure 1 shows a simplified view of the three tiers and some of their components. This article focuses on the middle tier and the EIS tier.

Figure 1. Three-tier architecture

The Derby difference

Most J2EE applications need to store data, and the most common method used to manage data is with a JDBC-compliant database. Any database with a JDBC driver interface can be integrated with the Server to create what J2EE terms a "resource manager" (RM). The Derby engine is ideally suited to the role of resource manager. It is designed to be a relational database component of a larger system, which is what is meant by the term "embedded database" commonly used to describe Derby. When implemented (embedded) in a J2EE Server, it becomes one more tool in a system of specialized components available to applications implemented (deployed) in the Server.

The J2EE Server provides for network communications and security that can be configured to the needs of the system. The Derby engine does not duplicate these functions but readily takes advantage of these services in a Server environment. Much of the code of many database system binaries provides for system security and networking that is redundant in a J2EE system. The Derby footprint remains small because the libraries do not contain this code. When embedded in a J2EE Server, a fully functional JDBC-compliant resource manager is installed by adding a single 2 MB jarfile to the system.

Derby and J2EE

The following list highlights some of the key benefits of using Derby. See the "Tech Overview" referenced in the Resources section of this document for more complete information.

  • Derby is a full-featured relational database with capabilities rivaling large enterprise databases. Do not be fooled by its small size (2 MB) and cost ($0).
  • Derby is fully transactional and can participate in global (distributed) transactions when used with the JTA transaction manager of the J2EE Server.
  • A Derby database system (binaries and database) can be copied to any platform with a J2SE JVM and run without performing a rebuild or other alterations.
  • A Derby database system in its default configuration requires no separate administration. The engine runs within the J2EE Server JVM process, becoming an integrated part of the system.

One of the first decisions to be made when designing an application that uses a database is how to access the data. J2SE provides the following two methods of accessing a relational database that has a JDBC-compliant driver:

  1. Using the JDBC service provider interface (SPI) . This means the application uses the JDBC DataSource interface to establish connections to the database. This is the preferred access method for a J2EE application for several reasons:
    • It allows program code to be totally database independent. Driver information, database location, and configuration parameters are stored by the J2EE Server.
    • It allows the use of connection sharing (a.k.a., pools). The J2EE Server connection manager effectively manages connections to greatly improve performance and scalability.
    • It enables the database to be used by Enterprise JavaBeans (EJB) to implement business logic as part of the J2EE Server. Implementing an EJB tier, though not required, lays the foundation for creating a highly scalable, distributed application architecture.
  2. Directly from the application code . This means that the application uses the JDBC DriverManager class to establish the database connection. This is how stand-alone (non-server-based) database applications are usually coded. The application is self-contained and does not rely on information or services from the app server. Nor will the application benefit from the portability and scalability benefits provided by the app server JDBC Service Provider.

A major benefit of using a J2EE app server is how it simplifies the use of the JDBC SPI for database access. Most business programmers cannot justify the time it takes to write their own datasource and connection pool code plus implement a naming server so the JDBC SPI can be used. It is much more effective to set up an Application Server environment instead.

Derby as a Resource Manager

This section shows how to set up Derby as a J2EE Resource Manager using the JDBC service provider interface (SPI). Besides the benefits listed above, using the JDBC SPI to support the Derby embedded driver will avoid potential problems arising from the security and isolation practices implemented within the app server engine (see the The Resource Manager within the Server section for more information). The general steps taken to setup and use a database as a managed resource are:

  1. Prepare the database:
    • Install the RDBMS. For Derby this means adding derby.jar into the Server directory tree.
    • Start the RDBMS, if needed. With Derby the engine starts automatically when the Server loads the JDBC driver.
    • Create the application database. This is often done using an file containing SQL commands that is processed by the database's command line tool (for example: IJ).
  2. Define and deploy the datasource that will be used by applications to access the database. Most J2EE Servers will automatically do the following at this point:
    • Register the object name with a name server. This name is used in applications in place of any database-specific information in order to establish a connection to the database.
    • Set up a connection pool. The pool is totally transparent to the application but provides improved performance and scalability.
  3. Start the datasource/connector or configure the Server to start it automatically.
  4. Code your application using the JDBC DataSource interface for connections (or use container-managed persistence (i.e. EJBs), but that is another topic).

The step "Define and deploy the datasource" is where the RDBMS and database-specific information needed to establish a connection is supplied. The basic information needed to complete this step is:

  • the location and name of the JDBC driver library (for example: derby.jar)
  • the JDBC driver class name (for example: org.apache.derby.jdbc.EmbeddedDriver)
  • the database connection URL (for example: jdbc:derby:JPetstoreDB)
  • parameter codes (optional in most cases)

The process by which the datasource information is captured and the datasource deployed vary with each J2EE Server. Many systems have a console application to simplify defining and deploying the datasource. The following section shows how to set up a datasource using the IBM WebSphere Application Server Community Edition Administrative console. Cookbook instructions for setting up Derby as a Resource Manager in other servers is also available online. See the respective links referencing IBM WebSphere, Apache Geronimo and Tomcat in the Resources section below.

Set up a Derby Resource Manager with WebSphere Application Server Community Edition

IBM WebSphere Application Server Community Edition (WAS CE) is a free lightweight J2EE application server built on Apache Geronimo. WAS CE contains an administrative console application that greatly simplifies the deployment and management of Java applications in J2EE environment (see the IBM WebSphere Application Server Community Edition link in the Resources section below for information on obtaining and using WAS CE). The following steps outline creating a datasource for a Derby database called JPetstoreDB. For this example the complete database has been copied into the WAS CE subdirectory ...var/derby . This implementation uses the distribution of Derby that comes bundled with WAS CE (found in ...repository/org.apache.derby/jars ). The Derby jarfiles distributed with WAS CE are renamed to maven-recognizable format (the version number and distributor name have been appended to each) so the derby.jar file is named in the WAS CE version installation.

  1. Start WAS CE and access the Administrative console (default URL: https://localhost:8443/console). A username and password is required, the default signon account created by the WAS CE installation is: system / manager.
  2. From the initial Welcome screen click on the Database Pools link in the Console Navigation pane at the left (Figure 2).
    Figure 2. WAS CE Console Navigation pane
    Console Navigation Pane
  1. In the Database Pools window begin creation of the pool by clicking on the Using the Geronimo database pool wizard link (Figure 3).
    Figure 3. WAS CE Database Pools pane
    Data Pools Pane
  1. Enter the database pool name JPetstoreDB . In the Database Type drop down list select Derby embedded (Step 1). Click Next .
    Step 1. Select Name and Database
    Name and Database
  1. Validate that the value in the JDBC Driver Class field is org.apache.derby.jdbc.EmbeddedDriver , correct the value if needed. In the Driver JAR drop down list select org.apache.derby/derby/ . Enter the DB name JPetstoreDB in the Database field. (Step 2). Click Next .
    Step 2. Select Driver, JAR, Parameters
    JDBC Driver Info
  1. Validate that the value in the JDBC Connection URL is jdbc:derby:JPetstoreDB , correct the value if needed (Step 3). Click Test Connection .
    Step 3. Final Pool Configuration
  1. Confirm that the connection was successful by checking the Test Result field. Click Deploy to save the pool definition.
    Step 4. Test Connection
  1. The Data Pools Main menu will be displayed listing the newly created JPetStoreDB pool.

That's all there is to it. Now an application deployed on the Server can access the database by referencing the Database Pool name without regard to the actual DBMS being used. Click on the Usage link for the Pool for specific information on using the database pool JPetstoreDB from a J2EE application.

The Resource Manager within the server

Deploying multiple applications that use Derby

Derby is designed so that the database engine (derby.jar) can be easily bundled with the application package and becomes just another jarfile to be installed as part of the application. This makes installation a one-step process and causes no problems in a stand-alone application environment. In a Server environment, however, where the database engine is embedded as described in this article, problems can arise (and have) from deploying multiple versions of Derby. A cardinal rule of using embedded Derby is "Never load classes from multiple copies of derby.jar into the same JVM" .

To avoid problems when multiple applications that supply derby.jar need to be deployed, use the sysinfo command ( ) to determine which is the newer version of Derby and specify that jarfile for all Derby pools and datasources. Derby's soft upgrade feature makes databases created by older versions compatible with the newer releases. Never have multiple copies of derby.jar in your Server system.

When configured as described above, the Derby database engine blurs the distinction between the Server tier and the EIS tier. Unlike most other RDBMSs, it is a Java program running within the app server JVM (embedded) and not a separate process running in its own address space. Because of this, it is susceptible to internal implementation details of the app server, in particular the implementation of multiple classloaders. App servers use multiple classloaders to provide the isolation needed to run many applications simultaneously without the applications "stepping" on one and other. The Derby system can encounter problems when its classes are loaded by a classloader created to support an individual application instance rather than all application instances. It is even possible that the database engine classes will be spread between multiple classloaders. This will cause the database engine to hang or fail in unexpected ways. Because the database is a shared resource, it needs to be loaded higher in the classloader hierarchy and applications should not load Derby classes in other classloaders.

Classloaders and classloader hierarchies are complicated topics and have more detail than can be covered here (for more information on this subject, follow the "J2EE Class Loading Demystified" link in the Resources section below). It is important to note, however, that how classloaders are used differs between app servers so though an application that loads the Derby driver directly might work well deployed in one Server, the same application might fail when deployed on a different app server. Establishing database connections through the service provider interface insures the application is portable across App Sever environments, regardless of how the classloader hierarchy is managed.

If your application architecture prevents you from using the service provider interface or if you need to distribute the database processing load to another machine, you can use Derby with the Network Server. The Derby Network Server runs Derby in a process separate from the J2EE Server. The Network Server adds some complexity to the system because it needs to be started separately and both authentication and a set of security policies implemented (things the J2EE server often handles). Using the Derby Network Server also requires the use of different JAR files and database connection URL syntax not covered here. Embedded in the Derby Network Server the Derby engine is running in a standard client-server architecture like most other database systems.


There are numerous J2EE Application Servers available and each differentiates itself by bundling "their own" set of Java technology products and services. To see what is available, check out the link to the "Application Server Matrix" in the Resources section below. Each Server provides a simplified interface for using the various technologies in concert with each other. Most provide for the creation of datasources and connection pools in a manner similar to what is described here.

Another very important feature found in most J2EE app servers is the support of server-side processing through at least Servlets and Java Server Pages (JSPs). Other services and technologies that may be found in a J2EE Server bundle include EJBs, Connectors, JMS, JTA, etc. As new technologies and standards are created, these too will be incorporated into Application Servers. The technology is so vast and growing so rapidly that it is no wonder many people get lost when first introduced to J2EE. Like all other complex systems, it is best to get experience with J2EE one piece at a time. Integrating a database as described here is one of the more fundamental pieces to the J2EE architecture.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Information management on developerWorks

Zone=Information Management
ArticleTitle=Use Derby in a J2EE Server environment