Introduction

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.

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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 derby-10.1.2.ibm.jar in the WAS CE version 1.0.1.1 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
   
   
   

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

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

4. 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/10.1.2.ibm/jar . Enter the DB name JPetstoreDB in the Database field. (Step 2). Click Next .
   
   Step 2. Select Driver, JAR, Parameters
   
   
   

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

6. Confirm that the connection was successful by checking the Test Result field. Click Deploy to save the pool definition.
   
   Step 4. Test Connection
   
   
   

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

Back to top

The Resource Manager within the server

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.

Back to top

Summary

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.

Resources

Learn

• IBM Cloudscape Technical Resource Center
  
  
• Cloudscape Version 10: A technical overview
  
  
• Use IBM Cloudscape with WebSphere Application Server Community Edition : Define the Cloudscape Resource Manager manually
  
  
• IBM WebSphere Developer Technical Journal: Get started with WebSphere Application Server Community Edition
  
  
• Using Derby and WebSphere : Using Apache Derby with iBATIS JPetStore 4 on the WebSphere Server ® .
  
  
• Using Derby and Geronimo : Using Apache Derby with iBATIS JPetStore 4 running on the Geronimo J2EE server
  
  
• Integrate Cloudscape Version 10 or Derby with Tomcat :A cookbook for adding the relational database manager into the servlet container
  
  
• Using IBM Cloudscape 10 with WebSphere 6
  
  
• J2EE Class Loading Demystified
  
  
• The Application Server Matrix
  
  
• The J2EE 1.4 tutorial
  
  

Get products and technologies

• Get IBM Cloudscape
  
  
• Get IBM WebSphere Application Server Community Edition
  
  

Discuss

• Participate in the discussion forum.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• The Derby difference
• Derby and J2EE
• Derby as a Resource Manager
• Set up a Derby Resource Manager with WebSphere Application Server Community Edition
• The Resource Manager within the server
• Summary
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into Information Management on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers