The Torque generator consists of a collection of ant tasks. The core tasks generate java classes and sql scripts from an xml description of the database, but there are other tasks available. See the Schema Reference for the format of the xml file, and the Tasks reference for a complete list of available tasks.

The generator can be configured using a properties file, build.properties. See the Properties reference for a list of available properties and their purposes.

This section will give a short introduction of how to use the Torque generator using ant. For using the generator with maven, see the Maven plugin docs.

The following is just a suggestion to get you started using the generator. Once you found out how it is working, feel free to change the suggestion to fit your specific needs.

To use the generator, download the tar.gz or zip binary distribution of the Torque generator from the Torque download page. Unpack it in the root directory of your project. This will create a directory called torque-gen-3.3 in the root directory of your project. You also need to have ant installed and available in your path.

Change into the torque-gen-3.3 directory and edit the file build.properties. Look through the properties and modify them to fit your specific set-up. Afterwards, assuming you want to keep your schema files in the src/schema subdirectory of the project root directory, and generate your java classes in the target/java and the sql scripts in the target/sql subdirectories of the project root directory, add the following properties: torque.output.dir = ../target torque.schema.dir = ../src/schema

Now create the src/schema subdirectory of your project root directory. Create a schema.xml file describing your database in the newly create directory (for example you might use the bookstore-schema.xml file from the Tutorial) for a start. Note that the names of the schema file(s) needs to end with schema.xml.

If you want to use the id broker (a Torque runtime service which creates primary keys in a database independent manner), also copy the file torque-gen-3.3/src/schema/id-table-schema.xml to the src/schema subdirectory of your project root.

Now change into the torque-gen-3.3 directory, and type the command

This will create the target/java subdirectory in your project root directory containing the generated java classes, and the target/sql directory containing the generated sql scripts.

If you want to create your database using torque (this does not work for all databases), you first need to copy the database driver jar into the torque-gen-3.3/lib directory. Then make sure that the database user you have configured in the build.properties has sufficient rights to create a database. When everything is ready, type the command

To create the tables in your database, you also need the database driver jar in the torque-gen-3.3/lib directory. Type the command

You can repeat the steps above if you have changed your schema.xml. However, be aware that the insert-sql task drops all table and creates them anew, so all data in the tables is lost.

Now you have finished the short course in using the generator. To learn about how to use your generated java classes, you can either look at the Torque Runtime Docs or continue with the Tutorial at Step 4, ignoring all maven-specific parts, especially the bits about a file called project.xml. (As you use ant, you need to set up your own project build tasks.)