About this Guide

This User Guide is intended to help those who want to incorporate Torque into their project to provide a means of persistence for application objects.

Torque components

Torque consists of two main components:

  • Generator - The Torque generator uses a single XML database schema file to generate the SQL for your target database and Torque's Peer-based object relational model. The generator can be executed using the Torque maven-plugin or an Ant build file.
  • Runtime - The Torque runtime is required in order to compile and use of the classes produced by the generator.

Installing Torque

Generator with the Maven plugin

If you have not already done so, download and install Maven. You then need to obtain the Torque maven plugin. The Maven Howto includes details of how to build the maven plugin from source, but you can easily install a binary distribution thus:

Generator with the Ant build file

If you prefer to use Ant you need access to the Torque generator distribution and associated libraries - these are available from the Downloads page (the file to download is torque-gen-3.1.1.tar.gz or torque-gen-3.1.1.zip, depending on your development platform). Unpack the archive to reveal the following directory structure:

The instructions below are targeted towards using the Torque maven-plugin. If you are using Ant the instructions are basically the same, but instead of using project.properties you use build.properties and instead of using maven torque:${goal-name} you use ant -f build-torque.xml ${target-name}.

Runtime

At runtime the generated object model classes need access to the Torque runtime distribution and associated libraries - these are available from the Downloads page (the file to download is torque-3.1.1.tar.gz or torque-3.1.1.zip, depending on your development platform). We will cover what to do with this file in a later step.

Quick Start Guide

For those who just want to see Torque here we will race our way through all that needs to be done to define, generate and use a Torque object model.

Configure Torque Generator (project.properties)

For a complete list of generator properties, please refer to the properties reference. Below is a short list of the primary properties you should be interested in.

torque.project
torque.database
torque.targetPackage
torque.database.createUrl
torque.database.buildUrl
torque.database.url
torque.database.driver
torque.database.user
torque.database.password
torque.database.host

Define Database Schema (project-schema.xml)

This is an example of what the XML database schema might look like. This particular example is a snippet of the database used for role-based user system of Turbine.

Please refer to Torque Schema Reference to find out more about the the different elements and attributes.

Torque Runtime Configuration (Torque.properties)

The runtime distribution archive includes an Ant build file that can be used to generate your Torque runtime configuration - see the Torque tutSorial for details.

The above example uses the commons-dbcp connection pool - see Pool-config Howto details of the available DataSource factories.

Add Libraries

In order to be able to compile and use the generated class files it is necessary to include the Torque runtime jar file and jar files for all of the necessary dependencies in the classpath of your project. The necessary jars are included in the torque/lib directory of the Torque runtime. If you are using Maven to build your project it may be easiest to copy the necessary dependencies from the Torque runtime POM.

Object Model and SQL Generation

Generate the object model and associated SQL:

Note: Torque will drop the database and tables that it is about to create if they exist! You should skip the next two steps if you are working with an existing database full of data.

To creating the database:

To create the tables:

Using the Torque Object Model Classes

The following is an example of using the Torque object model classes - it is adapted from the Torque tutorial.