Turbine

Essentials

Models

Get Involved

Documentation

Database

What is Torque?

Torque is a utility packaged with Turbine that generates all the database resources required by your web application. Torque uses a single XML database schema to generate the SQL for your target database, Turbine's Peer-based object relation model representing your XML database schema, and a HTML document describing the database. The HTML document is obviously not required by Turbine, but helps in describing your web app to other developers.

Torque is currently deployed in two forms: a stand-alone version and a version that is bundled with the Turbine Developer's Kit. Both versions are identical in function, they just have slightly different configurations. The TDK version outputs the sources in a location where the project build system can find them, and the stand-alone version simply places the generated sources in an "output" directory in the Torque directory structure.

Torque Directory Structure

Here is what the Torque directory structure looks like. There are slight differences between the stand-alone and TDK versions but nothing significant:


torque/
    config/      <--- Torque configuration properties.
    lib/         <--  Jar files required by Torque (stand-alone version)
    dtd/         <--- DTD for Torque XML database descriptors.
    schema/      <--- Project specific XML database descriptor.
    templates/   <--- Velocity templates used for source generation.
    xsl/         <--- XSLT stylesheets use for HTML generation.
    output/      <--- Target location for output (stand-alone version).

    torque.xml   <--- Ant build file that controls Torque.
    torque.sh    <--- Unix script to start up Ant.
    torque.bat   <--- DOS bat file to start up Ant.

A typical user of Torque would really only ever need to edit the torque.props file in the config directory, and the project-schema.xml in the schema directory. We'll quickly go over each of these files and some of options you have using Torque.

Quick Start Guide

For those who just want to see Torque go all you have to do is select your target database and target package in torque.props, edit the project-schema.xml to suit your needs, then run torque.sh or torque.bat. That's it!

You will probably want to set the project property in the torque.props file eventually so that your generated sources have names that reflect your project name, but you can do that later :-). You also have to remember that if you change the project property that you have to change the name of your project XML database schema to match! For example if you change the project property from the default value of "project" to "killerapp" then you must change the name of the default schema in the schema directory from project-schema.xml to killerapp-schema.xml.

Configuring Torque
torque.props

Here is a list of all the properties currently supported by Torque:

project The name of your Turbine project. The project name is reflected in the names used for the generated output. If your project is set to "killerapp" then you will get the following files:
killerapp-schema.sql
killerapp.generation.report
Remember when changing this property to change the name of your XML database schema to match!
database The target database for your Turbine project. This is used in conjuction with SQL generation.
extend Used in conjuction with the OM generation.
mapname Used in conjuction with the OM generation.
suffix Used in conjuction with the OM generation.
targetPackage Used in conjuction with the OM generation.
databaseUrl Used by the JDBC -> XML process, and by the SQL Ant Task that will initialize your target database with the generated SQL.
databaseDriver Used by the JDBC -> XML process, and by the SQL Ant Task that will initialize your target database with the generated SQL.
databaseUser Used by the JDBC -> XML process, and by the SQL Ant Task that will initialize your target database with the generated SQL.
databasePassword Used by the JDBC -> XML process, and by the SQL Ant Task that will initialize your target database with the generated SQL.
You should not have to edit any properties below here!  
configDir The directory Torque looks in for the torque.props file.
templatePath The path to the Velocity templates used for source generation.
SQLControlTemplate Control template used for SQL source generation.
OMControlTemplate Control template used for object model source generation.
idTableControlTemplate Control template used for Id Broker source generation.
outputDirectory Directory where the generated sources are placed.
schemaDirectory Directory where Torque looks for XML database schemas.
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 Turbines role-based user system:


<database>

  <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="Jobentry">
    <column name="JOBID" null="false" primaryKey="true" type="INTEGER"/>
    <column name="MINUTE" default="-1" null="false" type="INTEGER"/>
    <column name="HOUR" default="-1" null="false" type="INTEGER"/>
    <column name="WEEKDAY" default="-1" null="false" type="INTEGER"/>
    <column name="DAY_OF_MONTH" default="-1" null="false" type="INTEGER"/>
    <column name="TASK" null="false" size="99" type="VARCHAR"/>
    <column name="EMAIL" size="99" type="VARCHAR"/>
  </table>

</database>

This is what the resultant SQL looks like, in the case the target database is MySQL:


drop table if exists ID_TABLE;
CREATE TABLE ID_TABLE
(
    ID_TABLE_ID integer NOT NULL,
    TABLE_NAME varchar(255) NOT NULL,
    NEXT_ID integer,
    QUANTITY integer,
    PRIMARY KEY(ID_TABLE_ID),
    UNIQUE(TABLE_NAME)
);

drop table if exists Jobentry;
CREATE TABLE Jobentry
(
    OID integer NOT NULL,
    MINUTE integer default -1 NOT NULL,
    HOUR integer default -1 NOT NULL,
    WEEKDAY integer default -1 NOT NULL,
    DAY_OF_MONTH integer default -1 NOT NULL,
    TASK varchar(99) NOT NULL,
    EMAIL varchar(99),
    PRIMARY KEY(OID)
);

This is what the sources look like for the Peer based object model:

Please refer to Getting Started to find out more about the Peer based object model.

This is what the HTML description of the database looks like:

ID_TABLE
Column Type Size
ID_TABLE_ID INTEGER  
TABLE_NAME VARCHAR 255 
NEXT_ID INTEGER  
QUANTITY INTEGER  
Jobentry
Column Type Size
JOBID INTEGER  
MINUTE INTEGER  
HOUR INTEGER  
WEEKDAY INTEGER  
DAY_OF_MONTH INTEGER  
TASK VARCHAR 99 
EMAIL VARCHAR 99 

Copyright © 1999-2001, Apache Software Foundation