Apache Torque is a persistence toolkit for Java applications that use relational databases for storage. Torque is an open source project that was spawned off the Jakarta Apache Turbine Web application framework, but it’s now completely independent of Turbine. Torque supports most popular commercial and open source databases through JDBC, including Oracle, Microsoft SQL Server, IBM DB/2, MySQL, and PostgreSQL.

You can use Torque to generate the Java code for your data access layer. You can also use it to reverse-engineer Java objects from your existing database schema if you have an existing data access object (DAO) layer. For new projects, if you model your business objects in XML, Torque will generate SQL scripts to create your database tables along with Java objects for reading, writing, and finding data.

J2EE developers have a number of excellent options for a managed persistence layer. (Check out this sidebar for a look at various alternatives.) Our focus will be on what Torque offers and how to put it to work. You can download the example code for this article here.

Use Torque to generate your data access layer and value objects
Torque has two major components—a generation component and a run-time component. You can use Torque to generate value objects, SQL table creation scripts, and the data access layer. Either Apache Ant or Apache Maven can run the Torque generator. For this article, I’m going to use Ant.

Torque eases code maintenance because your value objects, data access objects, and SQL code are all generated from one XML file, known as a schema. Call this file yourprojectname-schema.xml and put it in the schema subdirectory of the Torque installation. This XML file contains a description of each of your value objects, including names, attributes, and relationships with other objects. The XML schema file we used for this example is called builder-schema.xml in the sample code you can download for this article. Note that we made a foreign key reference from the Product table to the Vendor table. This is because the relationship is that one vendor can have many products, and each product has a vendor.

The other important configuration file is build.properties in the root of the Torque installation. You must edit this file to include the name of your project, the database product used, the required JDBC connection information, and the package into which to put the generated class files. This file is also part of our sample code download.

Create the database from your database administration tool and make sure that you have version 1.5 or above of Apache Ant. Add the JAR file for your JDBC drivers to the lib subdirectory of the Torque installation. Then, run this command from the Torque directory:
ant –f build-torque.xml

Torque should generate all of your class files into an src/java directory under the main Torque install. The SQL scripts will be in src/sql.

The generated Java classes and SQL scripts
Torque will create five Java classes for each object in the schema XML file:

  • ·        Base Peer class
  • ·        Peer class (extends the Base Peer class)
  • ·        Base Data Object class
  • ·        Data Object class (extends the Base Data Object class)
  • ·        Map Builder class

Because you can edit your schema and rerun the generation script, there has to be a way for any extensions you make to the generated objects to survive the generation. Torque solves this problem by creating base classes, which are regenerated every time, and extension classes, which are generated only if they don’t exist. Add all of your code to the extension classes. The Base Peer, Base Data Object, and Map Builder classes shouldn’t be edited.

The Base Data Object class contains methods for getting and setting the attributes on the object and for saving the object to the database. An example is BaseVendor.java. The Base Peer class contains methods for retrieving, selecting, inserting, and deleting data objects from the database. See BaseVendorPeer.java for an example. The MapBuilder class is used by the Peer class.

The Peer class and the Data Object class are empty, and you can add or override methods as necessary to implement your business logic. (See VendorPeer.java and Vendor.java in the download.)

The SQL scripts are created specifically for your database product. Each vendor has slightly different quirks, and Torque has to work with all of them. To migrate your database to a new product, change your build.properties to point to the new information and regenerate your classes and SQL scripts. The main generated SQL script is in builder-schema.sql. Torque can also run the SQL script for you if needed. Be sure you also run the two ID method SQL scripts against your database if you choose the Torque ID Broker method (discussed below).

Criteria class
In Torque, SQL WHERE clauses are modeled using a class named Criteria. Create a new Criteria object and add your constraint clauses to the object using its methods.

ID methods
Torque can use one of several methods to generate primary keys for the objects in your database. For this example, we are using Torque’s ID Broker to generate the keys. This doesn’t rely on the capabilities of the database. If we wanted to use our database’s built-in feature, we would use the native method. Each database has a different way to create unique primary keys for each record in the table. Torque can be set up to use the database-specific method if needed. Torque can also be told not to generate primary keys for the records in the table. Associating database primary keys with a single instance of an object is one of the most difficult parts of writing an effective object-relational mapper, and Torque is very flexible here.

Integrating Torque in your application
Once we have our generated classes and our database is set up, we can use Torque in our application. Edit the Torque.properties file to use our JDBC connection information and project name (builder). Be sure to initialize Torque with the Torque.init() method in your application. For our sample application, we’ll demonstrate the one-to-many relationship between our Vendor and Product objects. We’ll also use the Peer class to delete the Product object. For more information, go to the Torque Web site and look at the methods on the generated classes.