Introduction to the Generator
Torque uses the information from the database schema to generate classes by which the database can be accessed. Also, Torque can generate SQL scripts and documentation in HTML and xdoc format from the schema. The Torque generator must be invoked in order to generate these artifacts. This can be done in three different ways: via Maven 2/3, via ant or via plain Java.
As the Torque generator is a general-purpose code generator, it must also know how to generate these classes. This is done by referencing the Torque templates from the generator run.
In the templates, the different generation goals (om classes, sql, doc...)
are organized in different packages. For each generation goal,
the correct package needs to be accessed. This is described in detail
in the following sections.
Using Maven 2/3
Preparation
When using Maven, the Torque generator is invoked by the Torque Maven Plugin. There is no need to invoke the generator manually or to add the generator to the runtime dependencies of your project. For adding the Torque Maven plugin to your build, add the following to your pom.xml:
<plugin>
<groupId>org.apache.torque</groupId>
<artifactId>torque-maven-plugin</artifactId>
<version>4.0</version>
<executions>
...(see below)
</executions
<dependencies>
<dependency>
<groupId>org.apache.torque</groupId>
<artifactId>torque-templates</artifactId>
<version>4.0</version>
</dependency>
</dependencies>
</plugin>
In the following, only basic configuration of the Torque Maven Plugin is covered. For details of configuration of the Torque Maven Plugin, refer to the generate goal reference.
Generation of om classes
For generating the OM classes, add the following execution to the executions list of the torque-generator plugin:
<execution>
<id>generate-sources</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<packaging>classpath</packaging>
<configPackage>org.apache.torque.templates.om</configPackage>
<sourceDir>${torque.schema.source.dir}</sourceDir>
<options>
<torque.om.package>${torque.target.package}</torque.om.package>
</options>
</configuration>
</execution>
Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema). Replace ${torque.target.package} with the base package for your generation, e.g. org.apache.torque.test.
You can add additional options to the configuration inside the options tag. The available options are described below.
This execution will generate the om code for all source files in the schema directory ending on -schema.xml, but excluding id-table-schema.xml. The output will be produced in the directories target/generated-sources and src/main/generated-java.
See the Customizing page for a documentation of available options which can be used to customize the generated output.
Generation of ddl sql
For generating the data description language(ddl) sql for the tables, add the following execution to the executions list of the Torque Maven plugin:
<execution>
<id>generate-sql</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<packaging>classpath</packaging>
<configPackage>org.apache.torque.templates.sql</configPackage>
<sourceDir>${torque.schema.source.dir}</sourceDir>
<defaultOutputDir>target/generated-sql</defaultOutputDir>
<defaultOutputDirUsage>none</defaultOutputDirUsage>
<options>
<torque.database>${torque.target.database}</torque.database>
</options>
</configuration>
</execution>
Replace ${torque.target.database} with the target database type (e.g. mysql, oracle). Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema).
This will generate the sql code for all source files in the schema directory ending on -schema.xml; the output goes to the directory target/generated-sql.
See the Customizing page for a documentation of available options which can be used to customize the generated output.
Generation of IDBroker SQL
For generating the SQL to fill the IDBroker tables, add the following execution to the executions list of the Torque Maven plugin:
<execution>
<id>generate-idtable-sql</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<packaging>classpath</packaging>
<configPackage>org.apache.torque.templates.idtable</configPackage>
<sourceDir>${torque.schema.source.dir}</sourceDir>
<defaultOutputDir>target/generated-sql</defaultOutputDir>
<defaultOutputDirUsage>none</defaultOutputDirUsage>
<options>
<torque.database>${torque.target.database}</torque.database>
</options>
</configuration>
</execution>
Replace ${torque.target.database} with the target database type (e.g. mysql, oracle). Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema).
This will generate the sql code for all source files in the schema directory ending on -schema.xml; the output goes to the directory target/generated-sql.
See the Customizing page for a documentation of available options which can be used to customize the generated output.
Note that for generating the ddl for the id tables, you need to generate the ddl sql for the following schema file:
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<database name="${database.name}"
xmlns="http://db.apache.org/torque/5.0/templates/database"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://db.apache.org/torque/5.0/templates/database
http://db.apache.org/torque/torque-5.0/documentation/orm-reference/database-5-0-strict.xsd">
<table name="ID_TABLE" idMethod="idbroker">
<column name="ID_TABLE_ID" required="true" primaryKey="true" type="INTEGER"/>
<column name="TABLE_NAME" required="true" size="250" type="VARCHAR"/>
<column name="NEXT_ID" type="INTEGER"/>
<column name="QUANTITY" type="INTEGER"/>
<unique>
<unique-column name="TABLE_NAME"/>
</unique>
</table>
</database>
where ${database.name} should be replaced by the symbolic name of the database for which you want to use the idbroker. The generation of om classes is not required for the idbroker table.
Generation of database create scripts
For generating the SQL scripts for creating a database (which does not make sense for every database vendor), add the following execution to the executions list of the Torque Maven plugin:
<execution>
<id>generate-createdb-sql</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<packaging>classpath</packaging>
<configPackage>org.apache.torque.templates.sql.createdb</configPackage>
<sourceDir>${torque.schema.source.dir}</sourceDir>
<defaultOutputDir>target/generated-createdb-sql</defaultOutputDir>
<defaultOutputDirUsage>none</defaultOutputDirUsage>
<options>
<torque.database>${torque.target.database}</torque.database>
</options>
</configuration>
</execution>
Replace ${torque.target.database} with the target database type (e.g. mysql, oracle). Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema).
This will generate the createdb sql code for all source files in the schema directory ending on -schema.xml; the output goes to the directory target/generated-createdb-sql.
Generation of html documentation
For generating html documentation for the tables, add the following execution to the executions list of the Torque Maven plugin:
<execution>
<id>generate-html-doc</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<packaging>classpath</packaging>
<configPackage>org.apache.torque.templates.doc.html</configPackage>
<sourceDir>${torque.schema.source.dir}</sourceDir>
<defaultOutputDir>target/generated-docs</defaultOutputDir>
<defaultOutputDirUsage>none</defaultOutputDirUsage>
<options>
<torque.om.package>${torque.target.package}</torque.om.package>
<torque.database>${torque.target.database}</torque.database>
</options>
</configuration>
</execution>
Replace ${torque.target.database} with the target database type (e.g. mysql, oracle). Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema). Replace ${torque.target.package} with the base package for your generation, e.g. org.apache.torque.test.
This will generate the html documentation for all source files in the schema directory ending on -schema.xml. The output will be produced in the directory target/generated-docs.
Generation of xdoc documentation
For generating xdoc documentation for the tables (to be included into your maven site), add the following execution to the executions list of the Torque Maven plugin:
<execution>
<id>generate-xdoc</id>
<phase>pre-site</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<packaging>classpath</packaging>
<configPackage>org.apache.torque.templates.doc.xdoc</configPackage>
<sourceDir>${torque.schema.source.dir}</sourceDir>
<defaultOutputDir>target/generated-xdocs</defaultOutputDir>
<defaultOutputDirUsage>none</defaultOutputDirUsage>
<options>
<torque.om.package>${torque.target.package}</torque.om.package>
<torque.database>${torque.target.database}</torque.database>
</options>
</configuration>
</execution>
Replace ${torque.target.database} with the target database type (e.g. mysql, oracle). Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema). Replace ${torque.target.package} with the base package for your generation, e.g. org.apache.torque.test.
This will generate the xdoc documentation for all source files in the schema directory ending on -schema.xml. The output is produced in the directory target/generated-xdocs. You may then want to add the following configuration to your pom to include this directory in your site:
<plugin>
<artifactId>maven-site-plugin</artifactId>
<groupId>org.apache.maven.plugins</groupId>
<configuration>
<xdocDirectory>target/generated-xdocs</xdocDirectory>
</configuration>
</plugin>
Generation of XML schema from an existing database
For extracting the structure of an existing database into a schema file, add the following execution to the executions list of the Torque Maven plugin:
<execution>
<id>generate-schema-from-jdbc</id>
<phase>generate-test-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<packaging>classpath</packaging>
<configPackage>org.apache.torque.templates.jdbc2schema</configPackage>
<defaultOutputDir>target/generated-schema</defaultOutputDir>
<defaultOutputDirUsage>none</defaultOutputDirUsage>
<options>
<torque.jdbc2schema.driver>${torque.driver}</torque.jdbc2schema.driver>
<torque.jdbc2schema.url>${torque.database.url}</torque.jdbc2schema.url>
<torque.jdbc2schema.user>${torque.database.user}</torque.jdbc2schema.user>
<torque.jdbc2schema.password>${torque.database.password}</torque.jdbc2schema.password>
<torque.jdbc2schema.schema>${torque.database.schema}</torque.jdbc2schema.schema>
</options>
</configuration>
</execution>
Replace ${torque.driver} with the fully qualified class name of the database driver. Replace ${torque.database.url} with the url to connect to the database. Replace ${torque.database.user} and ${torque.database.password} with the database username and the corresponding password. You may want to replace ${torque.database.schema} with the database schema to read, if not please remove the line containing it.
Note that Torque relies on metainformation supplied by the database driver for creating the schema file. This metainformation does not contain all information which is contained in the schema file, so the created file can only serve as a starting point. The information which can be read from the database differs from database to database. Table and column names can be read for almost every database. Column types, primary key information, and information about nullability and column default values is available for most databases, but there might be edge cases where type information is not detailed enough to determine the correct column type. Foreign key information and information about indices are typically not read.
Using Ant
Preparation
When using Ant, the Torque generator is invoked by the generator task, which is defined in the torque-ant-tasks project. Thus, the generator task needs to be defined as follows in the buildfile before it can be used:
<taskdef
name="torque-generator"
classpathref="ant-classpath"
classname="org.apache.torque.ant.task.TorqueGeneratorTask"/>
where ant-classpath points to a path which contains all jars from the binary Torque ant tasks distribution, plus the torque-templates jar.
In the following, only basic configuration of the Torque Ant Tasks is covered. For details of configuration of the Torque Ant Tasks, refer to the generator task reference and generator task reference.
Generation of om classes
A basic configuration for generating the om classes would be
<torque-generator
packaging="classpath"
configPackage="org.apache.torque.templates.om"
sourceDir="${torque.schema.source.dir}">
<option key="torque.om.package" value="${torque.target.package}"/>
</torque-generator>
Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema). Replace ${torque.target.package} with the base package for your generation, e.g. org.apache.torque.test.
Other generated artifacts
See the maven example above for the settings necessary to generate the other possible artifacts and apply them to the ant tasks. TODO describe in detail.
See the ORM tutorial for a complete build file example.
Using Java
Preparation
Using Java to generate classes should not normally be necessary. However, it can be useful if you neither use Maven nor Ant as build system. To use the generator from Maven, the Torque generato jar and its dependencies must be on the class path.
In the following, only basic configuration of the Torque Generator is covered. For details of configuration of the Torque Generator, refer to the its javadocs.
Generation of om classes
A basic set-up for generating the om classes would be
Controller controller = new Controller();
List<UnitDescriptor> unitDescriptors = new ArrayList<UnitDescriptor>();
Map<String, String> overrideOptions = new HashMap<String, String>();
overrideOptions.put("torque.om.package", "${torque.target.package}");
CustomProjectPaths projectPaths
= new CustomProjectPaths(
new Maven2DirectoryProjectPaths(new File(".")));
projectPaths.setConfigurationPackage("org.apache.torque.templates.om");
projectPaths.setConfigurationDir(null);
projectPaths.setSourceDir(new File("${sourceDir}"));
projectPaths.setOutputDirectory(
null,
new File("target/generated-sources"));
projectPaths.setOutputDirectory(
Maven2ProjectPaths.MODIFIABLE_OUTPUT_DIR_KEY,
new File("src/main/generated-java"));
UnitDescriptor unitDescriptor = new UnitDescriptor(
UnitDescriptor.Packaging.CLASSPATH,
projectPaths,
new DefaultTorqueGeneratorPaths());
unitDescriptor.setOverrideOptions(
new MapOptionsConfiguration(overrideOptions));
unitDescriptors.add(unitDescriptor);
controller.run(unitDescriptors);
Replace ${torque.schema.source.dir} with the directory where you put your database schemata (e.g. /src/main/schema). Replace ${torque.target.package} with the base package for your generation, e.g. org.apache.torque.test.
Other generated artifacts
See the maven example above for the settings necessary to generate the other possible artifacts and apply them to the ant tasks.