About this Tutorial
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.6 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 modules
Torque is divided into several parts, some of which can be used independenty of other parts:
- The Torque generator is a general code generation tool. It reads input from various sources, e.g. XML files or JDBC Metadata, and creates output files (e.g. java files, sql files).
- The Torque Maven plugin integrates the generator into Maven, a software project management tool. In other words, the maven plugin is a maven frontend for the generator.
- The Torque ant tasks integrate the generator into Ant, a java build tool.
- The Torque templates use the Torque generator to generate OR Mapping java classes which can access your database. They also generate SQL scripts to create all the necessary tables, constraints etc. in your database. The information about the database structure is contained in an XML file read by the Torque generator. The structure of this file is also defined by the Torque templates.
- The Torque runtime has to be included in ORM projects to use the classes generated by the generator using the templates.
Where to next
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.