Derby for Dummies

If you are looking for a lightweight database that starts along with Tomcat, then Derby could be a good choice. The following is how to run an instance of Derby on Tomcat. This is based on the casual scenary of the article Integrate Derby with Tomcat by Lance Bader.

Derby basics

If we read a litle about Derby we know that Derby can be used in two ways: as a embedded database, that is, Derby as part of our application and we start and stop it from the code application itself. For example, to start Derby in embedded way we just need to load the Derby driver:

Connection cnx = DriverManager.getConnection("jdbc:derby:my-db;create=true");

the above starts the Derby engine. To shutdown the engine we issue "jdbc:derby:;shutdown=true". The embedded way only supports one connection at a time, we will get an ugly exception if try to get another connection when there is already one connection running, something like this:

ERROR XJ040: Failed to start database 'my-db', see the next exception for details. ERROR XSDB6: Another instance of Derby may have already booted the database \my-db.

If we want to use Derby in a embedded way, we only need to put Derby engine derby.jar in the CLASSPATH.

The second way to use Derby is on client/server mode, this allow us to open as many connections as we want. This way uses the library derbynet.jar to wrap the Derby engine derby.jar so it is able to listen for tcp connections on a specific port. In order to do this is necesary to create an instance of org.apache.derby.drda.NetworkServerControl and call its method start() to start a threat which listens for connections on a tcp port, usually 1527. Next and example of how to do this:

NetworkServerControl server = new NetworkServerControl(InetAddress.getByName("0.0.0.0"), 1527); server.start(new PrintWriter(System.out));

to shutdown the server call the method server.shutdown().

In order to connect to this Derby mode we issue

...getConnection("jdbc:derby://localhost:1527/my-db;create=true");

or we can give the complete path to the database in this way

...getConnection("jdbc:derby://localhost:1527//home/user/my-db;create=true");

also, put the library derbyclient.jar on the CLASSPATH in order to the above code works.

Derby Libraries

The next chart belong to the article Introdução ao Derby

Command Line interface

Remember to use single quotes from ij tool.

Wiring Derby and Tomcat

Lets start for the easiest part, download Derby libraries and put them on Tomcat. We want that Derby be loaded when Tomcat service start so we have three posibles directories where put Derby libraries:

- tomcat-home/common/lib
- tomcat-home/shared/lib
- tomcat-home/server/lib

The libraries located on common/ and shared/ are accesibles for all the aplications running on Tomcat. For instance, if we put derby.jar on tomcat-home/common/lib/, this is like we had Derby on web-app/WEB-INF/lib/derby.jar, that is, locally to our web application web-app. On the other hand, the directory server/ is reserved to Tomcat specific libraries, i picked this direcory just for fun. We want Derby on client/server mode, so we need that somehow Tomcat calls org.apache.derby.drda.NetworkServerControl's start() and shutdown() for us, that is, start and shutdown Derby server. One way to do this is implementing the interface org.apache.catalina.LifecycleListener. Now lets say that we have a class com.my.packege.DerbyLifecycleListener who does that. We have to put this class on tomcat-home/server/classes/ or we can create a jar file and put it on tomcat-home/server/lib/

Next we have to wire this class with Tomcat, this is done setting tomcat-home/conf/server.xml on the listeners section like this:

<Listener className="org.apache.catalina.core.Apr..."/>
<Listener className="org.apache.catalina.mbeans...."/>
<Listener className="org.apache.catalina.mbeans..."/>
<Listener className="org.apache.catalina.store..."/>
<Listener className="com.my.packege.DerbyLifecycleListener"/>

Tomcat will load DerbyLifecycleListener every time it boots up so Derby engine will be listen for connections. Of course the libraries derbynet.jar and derby.jar must be on tomcat-home/server/lib so DerbyLifecycleListener load them.