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 consists of two main components:
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:
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}
.
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.
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.
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 |
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.
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.
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.
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:
The following is an example of using the Torque object model classes - it is adapted from the Torque tutorial.