Step 1: Configuring the Torque generation process

The following section outlines the necessary steps to configure a Torque-based ORM project using ant. For this, you need to create ant's build.xml file and make the necessary libraries available. It is recommended to run the tutorial against a mysql database, as all of the explanation in this tutorial assumes that you use mysql.

As a starting point, create a directory as a base directory for your project (also called the project's top level directory). All the paths in the following steps will be relative to this base directory.

Ant build file

As a starting point for the build file in your project, use the following template and save it as build.xml in the project's base directory. Then edit it to reflect your specific needs (typically you need to change the database URLs, the database host, the database user and password):

<?xml version="1.0"?>
<project name="Torque" default="main" basedir=".">

  <property name="build.properties" value="build.properties"/>
  <property name="torque.contextProperties" value="${build.properties}"/>
  <property file="${torque.contextProperties}"/>  

  <path id="ant-classpath">
    <fileset dir="libs">
      <include name="*.jar"/>
    </fileset>
  </path>

  <path id="runtime-classpath">
    <fileset dir="libs">
      <include name="**/*.jar"/>
    </fileset>
  </path>
  
   <pathconvert property="classpathRuntime" refid="runtime-classpath"/>

  <taskdef
    name="torque-generator"
    classpathref="ant-classpath"
    classname="org.apache.torque.ant.task.TorqueGeneratorTask"/>

  <target name="generate"
      description="==> generates sql + om classes">
    <torque-generator 
        packaging="classpath"
        configPackage="org.apache.torque.templates.om"
        sourceDir="src/main/schema">
      <option key="torque.om.package" value="org.apache.torque.tutorial.om"/>
      <option key="torque.database" value="mysql"/>
    </torque-generator>
    <torque-generator 
        packaging="classpath"
        configPackage="org.apache.torque.templates.sql"
        sourceDir="src/main/schema"
        defaultOutputDir="target/generated-sql">
      <option key="torque.database" value="mysql"/>
    </torque-generator>
  </target>

  <target name="compile">
    <mkdir dir="target/classes"/>
     <javac debug="on" source="1.8" target="1.8" destdir="target/classes" includeAntRuntime="false" classpathref="runtime-classpath" fork="yes">   
      <src path="src/main/java"/>
      <src path="src/main/generated-java"/>
      <src path="target/generated-sources"/>
      <classpath refid="runtime-classpath"/>
    </javac>
    <copy todir="target/classes">
      <fileset dir="src/main/resources"/>
    </copy>
  </target>

  <target name="execute-sql">
    <sql classpathref="ant-classpath"
        driver="${torque.database.driver}"
        url="jdbc:mysql://localhost:3306/bookstore"
        userid="${torque.database.user}"
        password="${torque.database.password}"
        onerror="continue"
        src="target/generated-sql/bookstore-schema.sql"/>
  </target>
  
  <taskdef
    name="torque-jdbc2schema"
    classpathref="ant-classpath"
    classname="org.apache.torque.ant.task.Torque4JDBCTransformTask"/>
    
  <target name="jdbc"  description="==> jdbc to xml">
    <echo> Generating XML from JDBC connection with jars: ${antClasspath} ...</echo>
    <echo message="+-----------------------------------------------+"/>
    <echo message="|                                               |"/>
    <echo message="| Generating XML from JDBC connection !         |"/>
    <echo message="|                                               |"/>
    <echo message="+-----------------------------------------------+"/>

    <torque-jdbc2schema 
      dbDriver="${torque.database.driver}"
      dbPassword="${torque.database.password}"
      dbUrl="${torque.database.url}"
      dbUser="${torque.database.user}"
      packaging="classpath"
      configPackage="org.apache.torque.templates.jdbc2schema"
      defaultOutputDir="target/generated-schema"
      >
    </torque-jdbc2schema>
  </target> 

  <target name="clean">
    <delete dir="target" />
  </target>

  <target name="main" description="build all" depends="generate, compile">
  </target>
</project>

This build file contains the following definitions:

  • The runtime dependencies of your project to Torque (needed when you compile and use the generated java sources)
  • The definition and configuration of the Torque ant task
  • The configuration of ant's SQL task (needed if you want to execute the generated SQL using ant)
  • The configuration of the java compiler (needed when you compile the generated java sources)
  • The configuration of the clean target (removes the compiled classes, some generated classes and the generated SQL).
  • The configuration of the main target (generates classes and SQL and compiles the java classes).

A correct ant build file is very important. This enables the Torque generator to generate all of the required sources and SQL for your specific database. If you experience problems later in this tutorial, it would be wise to double-check this file.

Library set-up

For the Torque generator/jdbc and SQL ant tasks to work correctly, you need to provide them with some additional libraries. This is done as follows:

  • Create the directory libs in your project.
  • Download the binary distribution of torque-templates. Put the torque-templates-${version}.jar from its root directory in the libs directory of your project.
  • Download the binary distribution of torque-ant-tasks. Put the torque-ant-tasks-${version}.jar from its root directory in the libs directory of your project.
  • Download the binary distribution of torque-generator-tasks. Put the torque-generator-tasks-${version}.jar from its root directory to the directory of your project containing your dependency libraries ("libs" in this example).
  • Download the sources and run from the source repo's sub folder cd torque-5.0/torque-generator the following command, which copies all dependencies if Torque Generator to libs. mvn clean dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=libs -DexcludeScope=test)
  • To configure Logging (Log4j2) set e.g. set ANT_OPTS=-Dlog4j.configurationFile=libs/log4j2.xml
  • Download the appropriate mysql driver jar, e.g. from here and add the jar to the libs directory of your project.
  • Add any Fulcrum dependencies (fulcrum-security-api and fulcrum-security-torque, if you are using Turbine and references of peer interfaces in the schema.

Where to next

This completes the configuration of the Torque ant tasks (and other settings to be made in the build.xml).

Next we will look at Defining the database schema.

User Comments

User comments for this step