Creating and using a Derby datasource in JBoss 4.2.3.GA on Java 5

Spent a good part of today digging through various mailing list and JIRA posts just to get this to work so I figured I’d post about it for other people who might run into the same problems.

The difference between theory and practice…

Google for “jboss derby” and the first link should be SetUpADerbyDatasource [DOC-12234] over at

That is basically the same file under

Ji-Woong Choi was kind enough to point out some things that were missing, and to cut a long story short I’ll just post the (supposedly) working derby-ds.xml right here:

<?xml version="1.0" encoding="UTF-8"?>

<!-- The Derby embedded database JCA connection factory config
$Id: derby-ds.xml,v 2004/11/03 13:28:39 loubyansky Exp $ -->


      <!-- The jndi name of the DataSource, it is prefixed with java:/ -->
      <!-- Datasources are not available outside the virtual machine -->

      <!-- for in-process persistent db, saved when jboss stops. The
      org.jboss.jdbc.DerbyDatabase mbean is necessary for properly db shutdown -->

      <!-- The driver class -->

      <!-- The login and password -->

      <!-- The minimum connections in a pool/sub-pool. Pools are lazily constructed on first use -->

      <!-- The maximum connections in a pool/sub-pool -->

      <!-- The time before an unused connection is destroyed -->

      <!-- Whether to check all statements are closed when the connection is returned to the pool,
           this is a debugging feature that should be turned off in production -->

      <!-- This mbean can be used when using in process persistent derby -->

   <mbean code="org.jboss.jdbc.DerbyDatabase" name="jboss:service=Derby">
     <attribute name="Database">localDB</attribute>

Don’t forget the JARs

Now if you start JBoss now, you’ll just get a ClassNotFoundException for org.jboss.jdbc.DerbyDatabase. Fortunately, Ji-Woong Choi’s comment also tells us what we need to do.

Copy ${JBOSS_HOME}/docs/examples/varia/derby-plugin.jar to ${JBOSS_HOME}/server/default/lib.

Next, download Derby (I’m using 10.4.2 as of this writing), extract the archive and copy ${DERBY_HOME}/lib/derby.jar also to ${JBOSS_HOME}/server/default/lib.

In most cases that’s pretty much all you need to properly configure a JDBC Datasource under JBoss, but not in this case.

At this point, I attempted to start JBoss but got another, more cryptic ClassNotFoundException: org/jboss/mx/server/MBeanServerBuilderImpl.

Derby + JBoss = JMX conflict

Basically, according to DERBY-3887 there’s a subtle JMX and classloader related problem that occurs because Derby tries to start a JMX server, which under JBoss should be the JBoss MBeanServer but I guess somehow at that point that class isn’t visible to Derby.

Fortunately, we find from that thread a workaround that is detailed under JBAS-1610—make JBoss use the platform JMX server (only on Java 5, obviously) by setting the jboss.platform.mbeanserver system property.

So, now we start JBoss using:

bin/ -Djboss.platform.mbeanserver

This lets Derby start up without any hitches and (apparently) JBoss still works properly. I’ve been able to deploy EJBs using JPA (Hibernate) using the Derby datasource, so far without any unwanted side-effects.

5 thoughts on “Creating and using a Derby datasource in JBoss 4.2.3.GA on Java 5

  1. hi,
    Thanks for the tips, can you show how to define more than one datasource in a *-ds.xml file ? Thanks in advance.

  2. You also need to change the SQL that creates the queue in Derby. I created a deby-jdbc-state-service.xml from the hsqldb-jdbc-state-service.xml in the /jms .

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s