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:

maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.2

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.2.tar.gz or torque-gen-3.2.zip, depending on your development platform). Unpack the archive to reveal the following directory structure:

torque-gen-3.2/
    docs/              <--- Contains a copy of the Torque documentation,
                            including the API JavaDocs.
    lib/               <--- Contains the jar files required by the Torque
                            generator, including the torque-gen-templates
                            jar containing the templates. If you want to
                            modify the templates, you can unpack the
                            templates jar, set the
                            <code>torque.useClasspath</code> to
                            <code>false</code>
                            and the <code>torque.schema.dir</code>
                            to the correct directory in the
                            <code>build.properties</code>
    src/schema/        <--- Contains the schema for the table used by Torque's
                            IDBroker.
    build.properties   <--- The various properties that you use to configure
                            the Torque generator.
    build-torque.xml   <--- The Ant build file containing the various torque
                            goals.
    default.properties <--- The default property values that are used to
                            configure the Torque generator.
    LICENSE.txt        <--- The License for the Torque generator.
    torque-gen-3.2.jar
                       <--- The generator jar.

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.

<database name="my_project">

  <table name="ID_TABLE">
    <column name="ID_TABLE_ID" required="true" primaryKey="true" type="INTEGER"/>
    <column name="TABLE_NAME" required="true" size="255" type="VARCHAR"/>
    <column name="NEXT_ID" type="INTEGER"/>
    <column name="QUANTITY" type="INTEGER"/>

    <unique>
      <unique-column name="TABLE_NAME"/>
    </unique>

  </table>

  <table name="TURBINE_PERMISSION" idMethod="idbroker">
    <column name="PERMISSION_ID" required="true" primaryKey="true" type="INTEGER"/>
    <column name="PERMISSION_NAME" required="true" size="99" type="VARCHAR" javaName="Name"/>

    <unique>
      <unique-column name="PERMISSION_NAME"/>
    </unique>

  </table>

  <table name="TURBINE_ROLE_PERMISSION">
    <column name="ROLE_ID" required="true" primaryKey="true" type="INTEGER"/>
    <column name="PERMISSION_ID" required="true" primaryKey="true" type="INTEGER"/>

    <foreign-key foreignTable="TURBINE_ROLE">
      <reference local="ROLE_ID" foreign="ROLE_ID"/>
    </foreign-key>

    <foreign-key foreignTable="TURBINE_PERMISSION">
      <reference local="PERMISSION_ID" foreign="PERMISSION_ID"/>
    </foreign-key>
  </table>

</database>

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.

torque.database.default = my_project
torque.database.my_project.adapter = mysql

# Using commons-dbcp
torque.dsfactory.my_project.factory = org.apache.torque.dsfactory.SharedPoolDataSourceFactory
torque.dsfactory.my_project.connection.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.my_project.connection.url = jdbc:mysql://localhost:3306/my_project
torque.dsfactory.my_project.connection.user = user
torque.dsfactory.my_project.connection.password = password
  

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:

maven torque

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:

maven torque:create-db

To create the tables:

maven torque:id-table-init-sql
maven torque:insert-sql

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.

import java.util.*;
import ...om.*;
import org.apache.torque.Torque;
import org.apache.torque.util.Criteria;

public class Bookstore
{
    public static void main(String[] args)
    {
        try
        {
            /* Initialize Torque */
            Torque.init("Torque.properties");

            /* Creating new objects */
            Publisher addison = new Publisher();
            addison.setName("Addison Wesley Professional");
            addison.save();

            Author bloch = new Author();
            bloch.setFirstName("Joshua");
            bloch.setLastName("Bloch");
            bloch.save();

            /* Foreign keys provided using convenience methods and manually. */
            Book tcpip = new Book();
            tcpip.setTitle("TCP/IP Illustrated, Volume 1");
            tcpip.setISBN("0-201-63346-9");
            effective.setPublisher(addison);
            tcpip.setAuthorId(stevens.getAuthorId());
            tcpip.save();

            /* Selecting all books */
            List booklist = BookPeer.doSelectAll();
            // iterate over booklist, casting the items to Book

            /* Selecting specific objects */
            Criteria crit = new Criteria();
            crit.add(BookPeer.ISBN, "0-201-63346-9");
            booklist = BookPeer.doSelect(crit);
            // iterate over booklist, casting the items to Book

            /* Updating data */
            effective.setAuthor(stevens);
            effective.save();

            tcpip.setAuthor(bloch);
            BookPeer.doUpdate(tcpip);

            /* Deleting data */
            crit = new Criteria();
            crit.add(BookPeer.ISBN, "0-618-12902-2");
            BookPeer.doDelete(crit);

            crit = new Criteria();
            crit.add(BookPeer.ISBN, "0-201-63346-9");
            crit.add(BookPeer.TITLE, "TCP/IP Illustrated, Volume 1");
            BookPeer.doDelete(crit);

            AuthorPeer.doDelete(bloch);
            AuthorPeer.doDelete(stevens);
            PublisherPeer.doDelete(addison);
        }
        catch (Exception e)
        {
            e.printStackTrace();
        }
    }
}