Running the Torque Tutorial on Derby

Torque, an Apache DB subproject, is a persistence layer that performs object mapping between java objects and a relational database.

Torque 3.2 has an excellent tutorial that uses MySQL. This page summarizes the changes required for each step to run the tutorial on Derby 10.1 using the Derby embedded JDBC driver. The instructions below assume Derby 10.1.3.1 -- modify those instructions to match the specific release you installed. (These instructions have also been verified to work with the Derby 10.2 beta.)

Currently Torque just works with the embedded jdbc driver; it doesn't work with the Derby Network Client JDBC driver or the IBM DB2 Universal JDBC driver because of an issue with the Village software it uses. Details are in DERBY-142.

Torque Generator Properties

Below is a project.properties file that works with the Derby embedded driver:

   # The name of the project Torque will generate code for.
   torque.project = bookstore

   # The target database platform.
   torque.database = derby

   # The target package to put the generated classes in.
   torque.targetPackage = com.kazmier.om

   # The JDBC URL that Torque can use to create and
   # drop databases if instructed to do so.
   # Derby note: Manually create/drop databases
   torque.database.createUrl =

   # The JDBC URL that will be used to create tables in your database.
   torque.database.buildUrl = jdbc:derby:bookstore

   # The JDBC URL that will be used to access your database.
   torque.database.url = jdbc:derby:bookstore

   # The JDBC database driver to use when connecting to your database.
   torque.database.driver = org.apache.derby.jdbc.EmbeddedDriver

   # The administrative username that has sufficient privileges to create
   # and drop databases and tables that Torque executes at generation time.
   torque.database.user = app

   # The administrative password for the supplied username.
   torque.database.password = app

   # The hostname or IP address of your database server.
   torque.database.host = 127.0.0.1 
  

Adding the driver to the maven repository

I added the Derby jar to my local maven repository like this:

  mkdir ~/.maven/repository/derby
  mkdir ~/.maven/repository/derby/jars
  cp /opt/Apache/db-derby-10.1.3.1-bin/lib/derby.jar ~/.maven/repository/derby/jars/derby-10.1.3.1-bin.jar

There are probably other ways for incorporating the Derby jar that don't require renaming the jar to include the version.

Specifying the driver dependency

Here is the complete project.xml file:

   <project>
     <pomVersion>3</pomVersion>
     <groupId>torque</groupId>
     <id>torque-tutorial</id>
     <name>Torque</name>
     <currentVersion>3.2</currentVersion>

     <dependencies>

       <dependency>
         <artifactId>derby</artifactId>
         <groupId>derby</groupId>
         <version>10.1.3.1-bin</version>
       </dependency>

     </dependencies>
   </project>

Creating the database

The Torque Tutorial instructions mention that maven torque:create-db doesn't work for all databases, and I didn't find a way to make it work for Derby. (I also didn't try very hard, so it might be possible.)

Manually create the database in the root directory of your Torque project like this:

   java org.apache.derby.tools.ij
   ij version 10.1
   ij> connect 'jdbc:derby:bookstore;create=true';
   ij> quit; 

Now set the DERBY_SYSTEM_HOME environment variable to this directory location. You'll use it in Step 6 to set the derby.system.home property so Derby will know where to find the database you created. For example, here is how I set it on my Linux machine:

   export DERBY_SYSTEM_HOME=/home/jta/Apache/TorqueTutorial

If I were on Windows, I would have set the variable like this instead:

   set DERBY_SYSTEM_HOME=C:\home\jta\Apache\TorqueTutorial

Creating the tables

No changes to this step are required.

Torque Run-Time Properties

Here is the complete src/conf/torque.properties file:

   torque.database.default = bookstore
   torque.database.bookstore.adapter = derby

   #Using commons-dbcp
   torque.dsfactory.bookstore.factory = org.apache.torque.dsfactory.SharedPoolDataSourceFactory
   torque.dsfactory.bookstore.connection.driver = org.apache.derby.jdbc.EmbeddedDriver
   torque.dsfactory.bookstore.connection.url = jdbc:derby:bookstore
   torque.dsfactory.bookstore.connection.user = app
   torque.dsfactory.bookstore.connection.password = app

No changes to this step are required.

I made two modifications for running the sample application:

• Set the derby.system.home property to the environment variable created in Step 3.
• Replace the mysql jar with the derby jar: lib/derby-10.1.3.1-bin.jar

Here is the command I ran on my Linux machine:

   [jta@gertie target]$ java -Dderby.system.home=$DERBY_SYSTEM_HOME -cp classes:lib/avalon-framework-4.1.4.jar:lib/commons-beanutils-1.7.0.jar:lib/commons-collections-3.1.jar:lib/commons-configuration-1.1.jar:lib/commons-dbcp-1.2.1.jar:lib/commons-lang-2.1.jar:lib/commons-logging-1.0.4.jar:lib/commons-pool-1.2.jar:lib/jcs-20030822.182132.jar:lib/derby-10.1.3.1-bin.jar:lib/torque-3.2.jar:lib/village-2.0.jar com.kazmier.Bookstore

Jean Anderson wrote these instructions. Please post any questions about them to derby-user@db.apache.org.