Level: Intermediate Stanley Bradbury (bradbury@us.ibm.com), Community Coordinator - Cloudscape, IBM
29 Sep 2005
Updated 15 Jun 2006 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.
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.
 |
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:
-
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.
-
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:
- 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).
-
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.
-
Start the datasource/connector or configure the Server to start it
automatically.
-
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
derby-10.1.2.ibm.jar
in the WAS CE version 1.0.1.1 installation.
-
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.
-
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
-
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
-
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
-
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
-
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
-
Confirm that the connection was successful by checking the
Test Result
field. Click
Deploy
to save the pool definition.
Step 4. Test Connection
-
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
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
|
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 (
org.apache.derby.tools.sysinfo
) 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.
|
|
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.
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
Get products and technologies
Discuss
About the author | | | 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. |
Rate this page
| 
