This tutorial is intended to give first-time users an introduction to using Torque. Torque has two primary foci: It is a tool for java code generation and, building on top of that, it provides object-relational mapping (ORM) for database access in java. These two aspects are treated in different parts of this tutorial; the two parts can be read independently of each other.
Both parts include how to obtain and install the relevant parts of Torque.
The ORM part then contains setting up a database
and writing a sample application.
The code generation part shows how the Torque generator can be used
for custom code generation.
The tutorial is not a reference. Refer to the Torque templates documentation and Torque runtime documentation for more detailed information about the ORM part, and to the Torque generator documentation for the generator part.
In this tutorial, it is assumed that you have experience
in programming in Java. It is also assumed that you have already been using
either Ant or
Maven (if you do not know one of these
build systems, please look at one of the introductions at their home pages).
It is expected that you have a working installation of the
JDK, Version 1.5 or higher.
The ORM part further assumes that you have some experience using JDBC (e.g. you should know what a jdbc driver and a connection URL is).
For each step in the tutorial, user comments are available in the Torque Wiki, see the links at the bottom of each page. If you had difficulties with a particular step and found a solution, please write it up and add it to the corresponding wiki page for each step.
If you are using Torque for the first time, you should
stick very closely to the example provided in the Tutorial,
and get the samples running as they are.
If you play around, there are quite a few places where
things can go wrong, and is not always clear why they go wrong.
Errors are much easier to find when you can pinpoint
the source of the error by
"Ok, it went wrong when I changed foo".
Once you got a running example, you can (and should) still play around to see whether Torque can satisfy your particular needs.
The ORM part used throughout this tutorial is based on an email sent to the turbine-user mailing list by Steven F. Davis called torque outside turbine - detailed example (long).
Torque is divided into several parts, some of which can be used independenty of other parts:
For the ORM part, we will first look at Configuring the Torque generation process. If you are using Maven as build system, look at configuring Maven for Torque. If you plan to use ant, look at configuring Ant for Torque For the code generation part, see getting started with Torque code generation.