Author: gk
Date: Tue Aug 11 13:36:00 2026
New Revision: 1937059
Log:
[TORQUE-376] - See https://issues.apache.org/jira/browse/TORQUE for the
tracking issue.
- add torque-build module
- update and add documenation in torque-site: Add more information about
outlets and explain generation process in workflow.xml.
- fix download for torque generator in torque tutorial/orm/step1-ant.xml
Added:
db/torque/trunk/torque-build/
db/torque/trunk/torque-build/README.md
db/torque/trunk/torque-build/build-torque.xml
db/torque/trunk/torque-build/build.properties
db/torque/trunk/torque-build/pom.xml
db/torque/trunk/torque-build/src/
db/torque/trunk/torque-build/src/main/
db/torque/trunk/torque-build/src/main/java/
db/torque/trunk/torque-build/src/main/resources/
db/torque/trunk/torque-build/src/main/resources/log4j2.xml
db/torque/trunk/torque-build/src/main/schema/
db/torque/trunk/torque-build/src/main/schema/bookstore-schema.xml
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/workflow.xml
Modified:
db/torque/trunk/README.md
db/torque/trunk/pom.xml
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/index.xml
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/outletTypes.xml
db/torque/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step1-ant.xml
Modified: db/torque/trunk/README.md
==============================================================================
--- db/torque/trunk/README.md Tue Aug 11 12:45:04 2026 (r1937058)
+++ db/torque/trunk/README.md Tue Aug 11 13:36:00 2026 (r1937059)
@@ -45,7 +45,7 @@ or try it with default database and acti
### Modules
-- This project consists of six modules
+- This project consists of seven modules
- torque-runtime
- torque-generator
@@ -54,6 +54,7 @@ or try it with default database and acti
- torque-ant-tasks
- torque-site
- torque-test (internal only)
+ - torque-build (internal only)
### Core modules
@@ -225,3 +226,7 @@ If voting was successfull, proceed by pu
Check [here|https://infra-reports.apache.org/#sitesource] the source repo of
the website https://db.apache.org/torque matches distributionManagement site
url in torque-site pom.xml.
+#### Torque Build - ORM artifacts (classes and SQL DDL)
+
+ *Torque-build* is an example build environment, which allows to build ORM
classses and SQL DDL from a schema.xml (which may be retro generated from a
databse) and provides a [README](torque-build/README.md) of its own.
+You need the ant tool installed.
\ No newline at end of file
Modified: db/torque/trunk/pom.xml
==============================================================================
--- db/torque/trunk/pom.xml Tue Aug 11 12:45:04 2026 (r1937058)
+++ db/torque/trunk/pom.xml Tue Aug 11 13:36:00 2026 (r1937059)
@@ -652,12 +652,14 @@
<exclude>velocity.log</exclude>
<exclude>.checkstyle</exclude>
<exclude>checkstyle-cache.ccf</exclude>
- <exclude>**/derby.log</exclude>
+ <exclude>**/*.log</exclude>
<exclude>**/LICENSE-EDL.txt</exclude>
<exclude>DEPENDENCIES</exclude>
<!-- special excludes for torque-test because this is
not a module
in the normal build process -->
<exclude>torque-test/src/main/generated-java/**/*</exclude>
+
<exclude>torque-build/src/main/generated-java/**/*</exclude>
+ <exclude>torque-build/lib/**</exclude>
<!-- hsqldb-jenkins -->
<exclude>torque-test/torque-test/**</exclude>
<exclude>torque-test/README.md</exclude>
@@ -762,7 +764,7 @@
</reportSets>
<configuration>
<!-- test project javadoc is not needed in the main site
and javadoc fails during the release build, so skip -->
- <skippedModules>torque-test</skippedModules>
+ <skippedModules>torque-test,torque-build</skippedModules>
</configuration>
</plugin>
<plugin>
Added: db/torque/trunk/torque-build/README.md
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ db/torque/trunk/torque-build/README.md Tue Aug 11 13:36:00 2026
(r1937059)
@@ -0,0 +1,221 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# torque-build — Torque ORM Reference Build
+
+This module provides a ready-to-use Ant build configuration for generating
Torque ORM Java
+classes and SQL DDL from an XML schema file. It packages the
`build-torque.xml` Ant script
+and `build.properties` configuration file as a reference starting point for
new Torque projects.
+
+A bundled bookstore schema (`Author` and `Book` tables) is included in
+`src/main/schema/bookstore-schema.xml` for self-testing without an external
database.
+
+---
+
+## Prerequisites
+
+| Tool | Minimum Version |
+|------|----------------|
+| Java | 17 |
+| Apache Ant | 1.10 |
+| Apache Maven | 3.9.5 |
+
+---
+
+## Quick Start (One Command)
+
+From the repository root, run phase process-resources to resolve dependencies
and generate
+ORM classes from the bundled bookstore schema using e.g. postgresql (no
external database lookup
+is needed, as the schema is already provided):
+
+```sh
+mvn clean process-resources
+```
+
+This single command:
+1. Resolves all runtime JARs into `torque-build/libs/`
+2. Runs `ant generate` (ORM Java + SQL DDL)
+3. Runs `ant compile` (compiles generated classes)
+
+After success, check:
+- `torque-build/target/generated-sources/example/om/Base*.java` — generated
base classes
+- `torque-build/src/main/generated-java/example/om/*.java` — generated header
classes
+- `torque-build/target/generated-sql/bookstore-schema.sql` — generated SQL DDL
+
+---
+
+## Manual Ant Workflow
+
+If you want to run the Ant targets directly (e.g., to develop or debug):
+
+### Step 1: Resolve Dependencies
+
+Run once to populate `libs/` before using Ant directly:
+
+```sh
+cd torque-build
+mvn dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=libs
+```
+
+Or from the repository root:
+
+```sh
+mvn process-resources -Dmaven.antrun.skip=true
+```
+
+### Step 2: Run Ant Targets
+
+```sh
+cd torque-build
+
+# Generate ORM classes and SQL DDL
+ant generate -f build-torque.xml
+
+# Compile generated + hand-written Java sources
+ant compile -f build-torque.xml
+
+# Generate and compile (default target)
+ant -f build-torque.xml
+
+# List all available targets
+ant -f build-torque.xml -p
+
+# Clean build output
+ant clean -f build-torque.xml
+```
+
+---
+
+## Ant Target Reference
+
+| Target | Depends On | Description | CI-testable |
+|--------|-----------|-------------|-------------|
+| `main` (default) | `generate`, `compile` | Full build: generate ORM/SQL +
compile | Yes |
+| `generate` | — | Two `torque-generator` invocations: ORM classes + SQL DDL |
Yes |
+| `compile` | — | Compile all Java sources (hand-written + generated) | Yes |
+| `execute-sql` | — | Execute generated DDL against a configured database |
**Manual only** |
+| `jdbc` | — | Reverse-engineer a live database into `schema.xml` | **Manual
only** |
+| `clean` | — | Delete `target/` directory | Yes |
+
+> **Manual-only targets**: `execute-sql` and `jdbc` require a running database
instance
+> with JDBC connection settings configured in `build.properties`. They are not
part of
+> automated CI (they are not exercised by `mvn process-resources`).
+
+---
+
+## Configuring `build.properties`
+
+Open `build.properties` and set the properties for your target database. The
file ships with
+Postgresql active. Uncomment the block for your database:
+
+
+No JDBC driver settings are needed for `generate` and `compile`.
+
+### MySQL
+
+```properties
+torque.database = mysql
+torque.database.driver = com.mysql.cj.jdbc.Driver
+torque.database.url =
jdbc:mysql://localhost:3306/mydb?useSSL=false&allowPublicKeyRetrieval=true
+torque.database.user = root
+torque.database.password =
+```
+
+### PostgreSQL
+
+```properties
+torque.database = postgresql
+torque.database.driver = org.postgresql.Driver
+torque.database.url = jdbc:postgresql://localhost:5432/mydb
+torque.database.user = postgres
+torque.database.password =
+```
+
+### HSQLDB
+
+```properties
+torque.database = hsqldb
+torque.database.driver = org.hsqldb.jdbcDriver
+torque.database.url = jdbc:hsqldb:hsql://localhost/mydb
+torque.database.user = sa
+torque.database.password =
+```
+
+> **Note**: The `torque.database` setting affects SQL dialect selection. The
`generate`
+> and `compile` targets work with any setting. JDBC-specific settings are only
used by
+> `execute-sql` and `jdbc` targets.
+
+---
+
+## Key `build.properties` Settings
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `torque.database` | `mysql` | Target SQL dialect |
+| `torque.targetPackage` | `example.om` | Java package for generated ORM
classes |
+| `torque.schema.dir` | `${torque.home}/src/main/schema` | Schema XML input
directory |
+| `torque.output.dir` | `${torque.home}/src` | Root output directory |
+| `torque.useManagers` | `false` | Generate Manager/cache classes |
+| `torque.generateBeans` | `false` | Generate Bean wrapper classes |
+
+---
+
+## Using Your Own Schema
+
+Replace or supplement the bundled schema:
+
+1. Put your `myproject-schema.xml` in `src/main/schema/`
+2. Set `torque.project = myproject` in `build.properties`
+3. Run `ant generate -f build-torque.xml`
+
+---
+
+## JGit Merge — Preserving Hand-Edited Files
+
+The Torque generator uses **JGit three-way merge** for files in
`src/main/generated-java/`.
+These are the "header" classes (non-`Base*`) where you add custom business
logic.
+
+- On **first generation**: header class files are created in
`src/main/generated-java/`
+- On **re-generation**: JGit merges new generator output with your hand-edits,
preserving
+ custom code in the header classes
+- `Base*` classes in `target/generated-sources/` are always fully regenerated
+
+This means you can safely re-run `ant generate` without losing customizations,
as long as
+the merge strategy is `merge` (the default).
+
+---
+
+## Logging
+
+Torque does use internally Log4j2 logging. To configure Log4j2 logging for the
Ant task, set `ANT_OPTS` before running Ant:
+
+```sh
+set ANT_OPTS=-Dlog4j.configurationFile=src/main/resources/log4j2.xml #
Windows
+export ANT_OPTS=-Dlog4j.configurationFile=src/main/resources/log4j2.xml # Unix
+```
+
+Another sample `log4j2.xml` may be found in the Torque generator distribution.
+
+---
+
+## Java 17 Note
+
+The `compile` target in `build-torque.xml` uses `source="17"` and
`target="17"`.
+Torque 7.x requires Java 17+. If you are targeting a different Java release,
adjust
+the `source` and `target` attributes in `build-torque.xml` accordingly.
Added: db/torque/trunk/torque-build/build-torque.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ db/torque/trunk/torque-build/build-torque.xml Tue Aug 11 13:36:00
2026 (r1937059)
@@ -0,0 +1,146 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<project name="Torque" default="main" basedir="."><!-- requires maven:
${project.build.directory} -->
+
+ <property name="build.properties" value="build.properties"/>
+ <property name="torque.contextProperties" value="${build.properties}"/>
+ <!-- Default database: overridden by build.properties if torque.database is
set there -->
+ <!--property name="torque.database" value="mysql"/-->
+ <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"/>
+ <pathconvert property="antClasspath" refid="ant-classpath"/>
+
+ <taskdef
+ name="torque-generator"
+ classpathref="ant-classpath"
+ classname="org.apache.torque.ant.task.TorqueGeneratorTask"/>
+
+ <target name="generate" description="==> generates sql + om classes">
+ <echo>Generate with antClasspath: ${antClasspath} ...</echo>
+ <torque-generator
+ packaging="classpath"
+ configPackage="org.apache.torque.templates.om"
+ sourceDir="src/main/schema"
+ >
+
+ <!-- see also build.properties -->
+ <option key="torque.om.useManagers" value="${torque.useManagers}"/>
+ <option key="torque.om.generateBeans" value="${torque.generateBeans}"/>
+ <option key="torque.om.objectIsCaching"
value="${torque.objectIsCaching}"/>
+ <option key="torque.om.save.addSaveMethods"
value="${torque.addSaveMethod}"/>
+ <option key="torque.om.addGetByNameMethods"
value="${torque.addGetByNameMethod}"/>
+ <option key="torque.om.complexObjectModel"
value="${torque.complexObjectModel}"/>
+
+ <option key="torque.om.package" value="${torque.targetPackage}"/>
+ <option key="torque.database" value="${torque.database}"/>
+ <option key="torque.om.complexObjectModel.generateFillers"
value="${torque.generateFiller}"/>
+ </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="${torque.database}"/>
+ </torque-generator>
+ </target>
+
+ <target name="compile">
+ <echo>Compiling with classpathRuntime: ${classpathRuntime} ...</echo>
+ <mkdir dir="${basedir}/src/main/java"/>
+ <mkdir dir="${basedir}/src/main/generated-java"/>
+ <mkdir dir="${basedir}/src/main/resources"/>
+ <mkdir dir="${basedir}/target/classes"/>
+ <mkdir dir="${basedir}/target/generated-sources"/>
+ <javac debug="on" source="17" target="17"
destdir="${basedir}/target/classes" includeAntRuntime="false"
classpathref="runtime-classpath" fork="yes">
+ <src path="${basedir}/src/main/java"/>
+ <src path="${basedir}/src/main/generated-java"/>
+ <src path="${basedir}/target/generated-sources"/>
+ </javac>
+ <copy todir="${basedir}/target/classes">
+ <fileset dir="${basedir}/src/main/resources"/>
+ </copy>
+ </target>
+
+ <!-- Manual-only: requires an existing database instance and a configured
JDBC URL.
+ Run 'ant execute-sql -f build-torque.xml' only after configuring
torque.database.*
+ properties in build.properties. Not applicable for Derby Embedded. -->
+ <target name="execute-sql">
+ <echo>reading ${torque.project}-schema.sql and connect to
${torque.database.url} with user ${torque.database.user}, database must
exist!</echo>
+ <echo>Set password at command line with
-Dtorque.database.password=xxx...</echo>
+ <!-- mysql 8: The driver is automatically registered via the SPI and
manual loading of the driver class is generally unnecessary. -->
+ <sql classpathref="ant-classpath"
+ driver="${torque.database.driver}"
+ url="${torque.database.url}"
+ userid="${torque.database.user}"
+ password="${torque.database.password}"
+ onerror="continue"
+ src="target/generated-sql/${torque.project}-schema.sql"/>
+ </target>
+
+ <taskdef
+ name="torque-jdbc2schema"
+ classpathref="ant-classpath"
+ classname="org.apache.torque.ant.task.Torque4JDBCTransformTask"/>
+
+ <!-- Manual-only: requires a running database instance with a configured
JDBC URL.
+ Run 'ant jdbc -f build-torque.xml' only after configuring
torque.database.*
+ properties in build.properties. -->
+ <target name="jdbc" description="==> jdbc to xml">
+ <echo> Generating XML from JDBC connection with antClasspath:
${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>
Added: db/torque/trunk/torque-build/build.properties
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ db/torque/trunk/torque-build/build.properties Tue Aug 11 13:36:00
2026 (r1937059)
@@ -0,0 +1,172 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# -------------------------------------------------------------------
+#
+# T O R Q U E C O N F I G U R A T I O N F I L E
+#
+# -------------------------------------------------------------------
+# This file contains the most commonly used properties. For a
+# complete list of build properties, please refer to the torque-templates
+# options.properties file.
+# -------------------------------------------------------------------
+
+torque.home = .
+
+# -------------------------------------------------------------------
+#
+# D I R E C T O R I E S
+#
+# -------------------------------------------------------------------
+
+torque.output.dir = ${torque.home}/src
+torque.schema.dir = ${torque.home}/src/main/schema
+
+# -------------------------------------------------------------------
+#
+# P R O J E C T
+#
+# -------------------------------------------------------------------
+# Name of your Torque project. Non-Java generated files will be named
+# using the project name (e.g. bookstore-schema.sql for project=bookstore).
+# -------------------------------------------------------------------
+
+#torque.project = myproject
+
+
+# -------------------------------------------------------------------
+#
+# T A R G E T D A T A B A S E
+#
+# -------------------------------------------------------------------
+# The target database for SQL generation. Possible choices include:
+# derby, hsqldb, mysql, postgresql, mssql, oracle
+#
+# Default: mysql
+# Uncomment one of the blocks below to switch databases.
+# -------------------------------------------------------------------
+
+#torque.database = mysql
+
+
+# --- HSQLDB ---
+#torque.database = hsqldb
+# torque.database.driver = org.hsqldb.jdbcDriver
+# torque.database.url = jdbc:hsqldb:hsql://localhost/mydb
+# torque.database.user = sa
+# torque.database.password =
+
+# --- MySQL ---
+# torque.database = mysql
+# torque.database.driver = com.mysql.cj.jdbc.Driver
+# torque.database.url =
jdbc:mysql://localhost:3306/mydb?useSSL=false&allowPublicKeyRetrieval=true
+# torque.database.user = root
+# torque.database.password =
+
+# --- PostgreSQL ---
+torque.database = postgresql
+# torque.database.driver = org.postgresql.Driver
+# torque.database.url = jdbc:postgresql://localhost:5432/mydb
+# torque.database.user = postgres
+# torque.database.password =
+
+
+# -------------------------------------------------------------------
+#
+# O B J E C T M O D E L I N F O R M A T I O N
+#
+# -------------------------------------------------------------------
+# These settings will allow you to customize the way your
+# Peer-based object model is created.
+# -------------------------------------------------------------------
+#
+# Reference in Torque-templates project in
+# /src/main/resources/org/apache/torque/templates/om/conf/options.properties
+#
+#
+# addGetByNameMethod
+# If true, Torque adds methods to get database fields by name/position.
+#
+# addIntakeRetrievable
+# If true, the data objects will implement Intake's Retrievable
+# interface
+#
+# addSaveMethod
+# If true, Torque adds tracking code to determine how to save objects.
+#
+# addTimeStamp
+# If true, Torque true puts time stamps in generated om files.
+#
+# basePrefix
+# A string to pre-pend to the file names of base data and peer objects.
+#
+# complexObjectModel
+# If true, Torque generates data objects with collection support and
+# methods to easily retreive foreign key relationships.
+#
+# targetPackage
+# Sets the Java package the om files will generated to, e.g.
+# "com.company.project.om".
+#
+# useClasspath
+# If true, Torque will not look in the <code>templatePath</code> directory,
+# for templates, but instead load them from the classpath, allowing you to
+# use Torque without extracted it from the jar.
+#
+# useManagers
+# If true, Torque will generate Manager classes that use JCS for caching.
+# Still considered experimental.
+#
+# objectIsCaching
+# If true, Torque generates data objects that cache their foreign
+# key relationships. If this is not desired (because the underlying objects
+# can be manipulated from other code), set this property to false. This
currently
+# cannot combined with the manager setting from above.
+#
+# silentDbFetch
+# If true, the getXXX() methods which retrieve associated objects
+# will fetch the associated objects silently. If false, only the
+# methods where a connection is specified explicitly will
+# fetch the associated objects silently; the methods where no connection
+# is specified will not do a silent fetch and return null if no previous
+# explicit fetch was made.
+# This setting has no effect if objectIsCaching is set to false.
+#
+#
+# generateBeans
+# If true, Torque will generate an additional bean for each data object,
+# plus methods to create beans from data objects and vice versa
+#
+# beanSuffix
+# A String to append to the class name of generated beans (if they are
generated)
+#
+
+torque.targetPackage = example.om
+
+torque.generateFiller = true
+torque.addGetByNameMethod = true
+torque.addIntakeRetrievable = false
+torque.addSaveMethod = true
+torque.addTimeStamp = true
+torque.basePrefix = Base
+torque.complexObjectModel = true
+torque.useClasspath = true
+torque.useManagers = true
+torque.objectIsCaching = false
+torque.silentDbFetch = true
+torque.generateBeans = true
+torque.beanSuffix = Bean
Added: db/torque/trunk/torque-build/pom.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ db/torque/trunk/torque-build/pom.xml Tue Aug 11 13:36:00 2026
(r1937059)
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+ http://maven.apache.org/maven-v4_0_0.xsd";>
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>torque</artifactId>
+ <version>7.1-SNAPSHOT</version>
+ <relativePath>..</relativePath>
+ </parent>
+
+ <artifactId>torque-build</artifactId>
+ <packaging>pom</packaging>
+ <name>Torque Build Example</name>
+ <description>
+ Reference Ant build module for Torque ORM code generation. Provides
+ build-torque.xml and build.properties as a ready-to-use starting point
+ for new Torque projects.
+ </description>
+
+ <dependencies>
+ <!-- Runtime scope: copied to libs/ by maven-dependency-plugin -->
+ <dependency>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>torque-ant-tasks</artifactId>
+ <version>${project.version}</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>torque-templates</artifactId>
+ <version>${project.version}</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>torque-runtime</artifactId>
+ <version>${project.version}</version>
+ <scope>runtime</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <!-- Step 1: Copy all runtime dependencies into libs/ so
build-torque.xml can use them -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <version>3.8.1</version>
+ <executions>
+ <execution>
+ <id>copy-dependencies</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>copy-dependencies</goal>
+ </goals>
+ <configuration>
+ <includeScope>runtime</includeScope>
+
<outputDirectory>${project.basedir}/libs</outputDirectory>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ <!-- Step 2: Run Ant generate + compile via the main target -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>clean-generated-sources</id>
+ <phase>clean</phase>
+ <configuration>
+ <target>
+ <!-- remove old generated sources -->
+ <echo message="Deleting directory
src/main/generated-java" />
+ <delete dir="src/main/generated-java" />
+ <!-- remove old generated sources -->
+ <echo message="Deleting directory libs" />
+ <delete dir="libs" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>torque-generate</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ <configuration>
+ <target>
+ <ant antfile="${basedir}/build-torque.xml"
target="main"/>
+ </target>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ <!--resources>
+ <resource>
+ <directory>${basedir}/src/main/resources</directory>
+ <filtering>false</filtering>
+ <includes>
+ <include>**/*.xml</include>
+ </includes>
+ </resource>
+ </resources-->
+ </build>
+
+</project>
Added: db/torque/trunk/torque-build/src/main/resources/log4j2.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ db/torque/trunk/torque-build/src/main/resources/log4j2.xml Tue Aug 11
13:36:00 2026 (r1937059)
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<Configuration status="warn" name="Torque">
+ <Appenders>
+ <Console name="console" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d [%t] %-5p | %c - %m%n" />
+ </Console>
+ <File name="torque" fileName="./torque-build.log">
+ <PatternLayout pattern="%d [%t] %-5p %c - %m%n" />
+ </File>
+ </Appenders>
+ <Loggers>
+ <!-- get queries: -->
+ <Logger name="org.apache.torque.util" additivity="false" level="DEBUG">
+ <AppenderRef ref="torque"/>
+ <AppenderRef ref="console" level="INFO"/>
+ </Logger>
+ <Logger name="org.apache.torque" additivity="false" level="INFO">
+ <AppenderRef ref="torque" />
+ <AppenderRef ref="console" />
+ </Logger>
+ <Logger name="org.apache.torque.dsfactory" additivity="false"
level="DEBUG">
+ <AppenderRef ref="torque" />
+ <AppenderRef ref="console" level="ERROR" />
+ </Logger>
+ <Logger name="org.apache.commons.beanutils" additivity="false"
level="WARN">
+ <AppenderRef ref="console" />
+ </Logger>
+ <Logger name="org.testcontainers" additivity="false" level="DEBUG">
+ <AppenderRef ref="torque" level="DEBUG" />
+ <AppenderRef ref="console" level="INFO"/>
+ </Logger>
+ <Logger name="org.apache.torque.generator.template.velocity"
additivity="false" level="DEBUG">
+ <AppenderRef ref="torque" level="DEBUG"/>
+ <AppenderRef ref="console" level="INFO"/>
+ </Logger>
+ <Logger name="org.apache.torque.generator.template.groovy"
additivity="false" level="DEBUG">
+ <AppenderRef ref="torque" level="DEBUG"/>
+ <AppenderRef ref="console" level="INFO"/>
+ </Logger>
+ <Logger name="org.apache.velocity" additivity="false" level="DEBUG">
+ <AppenderRef ref="console" level="DEBUG"/>
+ </Logger>
+ <Root level="DEBUG"><!-- log4j 1.2 has DEBUG -->
+ <AppenderRef ref="console" />
+ <AppenderRef ref="torque" />
+ </Root>
+ </Loggers>
+</Configuration>
\ No newline at end of file
Added: db/torque/trunk/torque-build/src/main/schema/bookstore-schema.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ db/torque/trunk/torque-build/src/main/schema/bookstore-schema.xml Tue Aug
11 13:36:00 2026 (r1937059)
@@ -0,0 +1,290 @@
+<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<!-- implementation of torque-test bookstore-scheam.xml -->
+<database name="bookstore"
+ defaultIdMethod="native"
+ 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";>
+
+ <!-- =================================================== -->
+ <!-- B O O K T A B L E -->
+ <!-- =================================================== -->
+
+ <table name="book" description="Book table">
+ <column
+ name="book_id"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ description="Book Id"
+ />
+ <column
+ name="isbn"
+ required="false"
+ type="VARCHAR"
+ size="15"
+ description="ISBN"
+ />
+ <column
+ name="author_id"
+ required="true"
+ type="INTEGER"
+ description="Foreign Key Author"
+ />
+ <column
+ name="title"
+ required="true"
+ type="VARCHAR"
+ size="255"
+ description="Book Title"
+ />
+
+ <foreign-key foreignTable="author">
+ <reference local="author_id" foreign="author_id"/>
+ </foreign-key>
+
+ </table>
+
+
+ <!-- =================================================== -->
+ <!-- A U T H O R T A B L E -->
+ <!-- =================================================== -->
+
+ <table name="author" description="Author table">
+ <column
+ name="author_id"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ />
+ <column
+ name="name"
+ required="true"
+ type="VARCHAR"
+ size="50"
+ />
+
+ </table>
+
+ <!-- =================================================== -->
+ <!-- B O O K _ A U T H O R V I E W -->
+ <!-- =================================================== -->
+
+ <!--view name="BOOK_AUTHORS" sqlSuffix="from book join author on
book.author_id=author.author_id">
+ <column name="book_id" type="INTEGER" select="book.book_id"/>
+ <column name="author_id" type="INTEGER" select="author.author_id"/>
+ <column name="book_title" type="VARCHAR" select="book.title"/>
+ <column name="author_name" type="VARCHAR" select="author.name"/>
+ </view-->
+
+
+ <table name="database_default_values">
+ <column
+ name="id"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ />
+ <!-- one normal field is required otherwise one gets syntax errors
+ on inserts where no value is changed. -->
+ <column
+ name="normal_payload"
+ type="INTEGER"
+ />
+ <column
+ name="o_integer"
+ required="true"
+ type="INTEGER"
+ javaType="object"
+ default="2"
+ useDatabaseDefaultValue="true"
+ />
+ <column
+ name="p_int"
+ required="true"
+ type="INTEGER"
+ javaType="primitive"
+ default="4"
+ useDatabaseDefaultValue="true"
+ />
+ <column
+ name="varchar_field"
+ required="true"
+ type="VARCHAR"
+ size="100"
+ default="Default!"
+ useDatabaseDefaultValue="true"
+ />
+ <!-- String yyyy-MM-dd for date values -->
+ <column
+ name="date_field"
+ type="DATE"
+ default="2010-09-08"
+ useDatabaseDefaultValue="true"
+ />
+ <!-- format String HH:mm:ss.S for time values -->
+ <column
+ name="time_field"
+ type="TIME"
+ default="10:20:30.0"
+ useDatabaseDefaultValue="true"
+ />
+ <!-- format String yyyy-MM-ddTHH:mm:ss.SSSSSSSSS for date and time
values -->
+ <column
+ name="timestamp_field"
+ type="TIMESTAMP"
+ default="2010-09-08T11:12:13.0"
+ useDatabaseDefaultValue="true"
+ />
+ </table>
+
+ <table name="java_default_values">
+ <column
+ name="id"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ />
+ <column
+ name="o_integer"
+ required="true"
+ type="INTEGER"
+ javaType="object"
+ default="2"
+ />
+ <column
+ name="p_int"
+ required="true"
+ type="INTEGER"
+ javaType="primitive"
+ default="4"
+ />
+ <column
+ name="varchar_field"
+ required="true"
+ type="VARCHAR"
+ size="100"
+ default="Default!"
+ />
+
+ <!-- String yyyy-MM-dd for date values -->
+ <column
+ name="date_field"
+ type="DATE"
+ default="2010-09-08"
+ required="true"
+ />
+ <!-- format String HH:mm:ss.S for time values -->
+ <column
+ name="time_field"
+ type="TIME"
+ default="10:20:30.0"
+ required="true"
+ />
+ <!-- format String yyyy-MM-ddTHH:mm:ss.SSSSSSSSS for date and time
values -->
+ <column
+ name="timestamp_field"
+ type="TIMESTAMP"
+ default="2010-09-08T11:12:13.0"
+ required="true"
+ />
+
+ <column
+ name="CURRENT_DATE_VALUE"
+ type="DATE"
+ useDatabaseDefaultValue="true"
+ />
+ <column
+ name="CURRENT_TIME_VALUE"
+ type="TIME"
+ useDatabaseDefaultValue="true"
+ />
+ <column
+ name="CURRENT_TIMESTAMP_VALUE"
+ type="TIMESTAMP"
+ />
+ </table>
+
+ <table name="CURRENT_DATE_TABLE"
+ description="Table which has a column which uses CURRENT_DATE from the
database as default">
+ <column
+ name="ID"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ />
+ <column
+ name="PAYLOAD"
+ required="false"
+ type="INTEGER"
+ />
+ <column
+ name="CURRENT_DATE_VALUE"
+ required="true"
+ type="DATE"
+ useDatabaseDefaultValue="true"
+ />
+ </table>
+
+ <table name="CURRENT_TIME_TABLE"
+ description="Table to test the CURRENT_TIME function">
+ <column
+ name="ID"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ />
+ <column
+ name="PAYLOAD"
+ required="false"
+ type="INTEGER"
+ />
+ <column
+ name="CURRENT_TIME_VALUE"
+ required="true"
+ type="TIME"
+ useDatabaseDefaultValue="true"
+ />
+ </table>
+
+ <table name="CURRENT_TIMESTAMP_TABLE"
+ description="Table to test the CURRENT_TIMESTAMP function">
+ <column
+ name="ID"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ />
+ <column
+ name="PAYLOAD"
+ required="false"
+ type="INTEGER"
+ />
+ <column
+ name="CURRENT_TIMESTAMP_VALUE"
+ required="true"
+ type="TIMESTAMP"
+ useDatabaseDefaultValue="true"
+ />
+ </table>
+
+</database>
Modified:
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/index.xml
==============================================================================
---
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/index.xml
Tue Aug 11 12:45:04 2026 (r1937058)
+++
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/index.xml
Tue Aug 11 13:36:00 2026 (r1937059)
@@ -27,10 +27,22 @@
<body>
<section name="Internals">
<p>
- The documents in this section contains explanations
+ The documents in this section contains explanations
how the Torque generator works internally.
This information is not needed to just use the Torque generator.
</p>
+ <ul>
+ <li>
+ <a href="workflow.html">Generation Workflow and Call Hierarchy</a> —
+ end-to-end pipeline from <code>TorqueGeneratorTask</code> through
+ <code>Controller</code>, <code>SourceProvider</code>,
<code>Outlet</code>,
+ and <code>ExistingTargetStrategy</code>; includes reverse engineering
(jdbc target).
+ </li>
+ <li>
+ <a href="outletTypes.html">Outlet Types</a> —
+ Velocity and Groovy outlet implementations.
+ </li>
+ </ul>
</section>
</body>
Modified:
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/outletTypes.xml
==============================================================================
---
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/outletTypes.xml
Tue Aug 11 12:45:04 2026 (r1937058)
+++
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/outletTypes.xml
Tue Aug 11 13:36:00 2026 (r1937059)
@@ -26,30 +26,259 @@
<body>
<section name="Introduction">
- The Torque generator can handle different outlet types,
- currently velocity and java outlets.
- The velocity outlets use templates to produce the output,
- the java outlets create their output directly in java.
+ <p>
+ The Torque generator supports three outlet types. Each outlet type is
identified
+ by the <code>xsi:type</code> attribute in the <code>outlets/*.xml</code>
+ configuration files inside a template set JAR.
+ </p>
+
+ <table>
+ <tr>
+ <th><code>xsi:type</code> value</th>
+ <th>Template mechanism</th>
+ <th>Template file extension</th>
+ <th>Used for</th>
+ </tr>
+ <tr>
+ <td><code>velocityOutlet</code></td>
+ <td>Apache Velocity template engine</td>
+ <td><code>.vm</code></td>
+ <td>Java ORM class generation (<code>om</code> template set)</td>
+ </tr>
+ <tr>
+ <td><code>groovyOutlet</code></td>
+ <td>Groovy template/script engine</td>
+ <td><code>.groovy</code></td>
+ <td>SQL DDL generation (<code>sql</code> template set, ddl
sub-set)</td>
+ </tr>
+ <tr>
+ <td><code>javaOutlet</code></td>
+ <td>Java class — no template file</td>
+ <td>(none)</td>
+ <td>JDBC reverse engineering (<code>jdbc2schema</code> template
set)</td>
+ </tr>
+ </table>
</section>
+ <section name="Template Set Mapping">
+ <p>
+ Each standard Torque template set uses a specific outlet type. The
choice is
+ driven by the complexity of the output being generated.
+ </p>
+
+ <table>
+ <tr>
+ <th><code>configPackage (with declaration information)</code></th>
+ <th>Outlet type</th>
+ <th>Template location</th>
+ <th>Why this outlet type</th>
+ </tr>
+ <tr>
+ <td><code>org.apache.torque.templates.om
+ (declared in multiple outlets/*.xml</code></td>
+ <td><code>velocityOutlet )</code></td>
+ <td><code>om/templates/**/*.vm</code></td>
+ <td>
+ Java ORM class structure is predictable: table→class,
column→field,
+ foreign-key→accessor. Velocity's <code>${variable}</code>
interpolation
+ and <code>#foreach</code> loops are sufficient for this one-to-one
mapping.
+ No per-database branching is needed because the Java ORM layer is
+ database-agnostic by design.
+ </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.torque.templates.sql</code> (DDL sub-set)
+ (declared in outlets/ddl.xml)</td>
+ <td><code>groovyOutlet</code></td>
+ <td><code>sql/templates/ddl/**/*.groovy</code></td>
+ <td>
+ SQL DDL syntax varies significantly across the supported databases
(Derby,
+ MySQL, PostgreSQL, Oracle, MSSQL, HSQLDB). Groovy provides real
+ <code>if/else</code> branching, method calls, and dynamic dispatch,
which
+ are necessary to produce correct DDL for six or more databases from a
+ single template. Velocity's scripting directives are less expressive
for
+ this level of per-database variation.
+ </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.torque.templates.sql</code> (createdb sub-set)
+ (declared in createdb/outlets/createdb.xml)</td>
+ <td><code>velocityOutlet</code></td>
+ <td><code>sql/createdb/**/*.vm</code></td>
+ <td>
+ Database creation scripts are simpler in structure than DDL and use
+ Velocity templates (legacy; this sub-set predates the Groovy
migration
+ for the main DDL set).
+ </td>
+ </tr>
+ <tr>
+ <td><code>org.apache.torque.templates.jdbc2schema
+ (declared in jdbc2schema/outlets/jdbc2schema.xml)</code></td>
+ <td><code>javaOutlet</code></td>
+ <td>(none)</td>
+ <td>
+ The reverse-engineering output is a single <code>schema.xml</code>
with a
+ fixed structure that mirrors JDBC <code>DatabaseMetaData</code>. The
Java
+ class <code>XmlOutlet</code> generates this XML directly from the
source
+ element tree without a template, since the output format is fixed
and the
+ mapping from JDBC metadata to XML attributes is straightforward
imperative
+ code.
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <section name="Outlet Declaration Examples">
+ <p>
+ Each outlet is declared in an <code>outlets/*.xml</code> configuration
file
+ inside the template set JAR. The key distinguishing attribute is
+ <code>path</code> (for template-based outlets) vs <code>class</code>
+ (for Java outlets).
+ </p>
+
+ <p><strong>velocityOutlet</strong> — uses <code>path</code> pointing to a
<code>.vm</code> file:</p>
+ <source><![CDATA[
+<outlet xsi:type="velocityOutlet"
+ name="torque.om.peer.basePeer"
+ path="templates/peer/BasePeer.vm"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
+ <!-- child elements omitted for brevity -->
+</outlet>
+]]></source>
+
+ <p><strong>groovyOutlet</strong> — uses <code>path</code> pointing to a
<code>.groovy</code> file:</p>
+ <source><![CDATA[
+<outlet xsi:type="groovyOutlet"
+ name="torque.sql.ddl.table"
+ path="templates/ddl/table.groovy"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
+ <!-- child elements omitted for brevity -->
+</outlet>
+]]></source>
+
+ <p><strong>javaOutlet</strong> — uses <code>class</code> (fully-qualified
Java class) instead of <code>path</code>:</p>
+ <source><![CDATA[
+<outlet xsi:type="javaOutlet"
+ name="torque.jdbc2schema.schema"
+ class="org.apache.torque.generator.outlet.java.XmlOutlet"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
+ <!-- child elements omitted for brevity -->
+</outlet>
+]]></source>
+ </section>
+
+ <section name="Decision Guide">
+ <p>
+ When writing a new template set, use the following criteria to choose the
+ correct outlet type:
+ </p>
+
+ <table>
+ <tr>
+ <th>Scenario</th>
+ <th>Recommended outlet type</th>
+ <th>Rationale</th>
+ </tr>
+ <tr>
+ <td>
+ Generating predictable Java or XML boilerplate where schema elements
+ (tables, columns) map directly to output structure (classes, fields)
+ with simple variable substitution and iteration
+ </td>
+ <td><code>velocityOutlet</code></td>
+ <td>
+ Velocity's <code>${var}</code> and <code>#foreach</code> are concise
+ and readable for one-to-one mapping. Use <code>.vm</code> template
files.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Generating SQL or configuration that must vary significantly per
target
+ database or environment, requiring conditional logic, method calls,
or
+ helper object interactions
+ </td>
+ <td><code>groovyOutlet</code></td>
+ <td>
+ Groovy's full programming model handles complex branching and
+ <code>torqueGenGroovy.mergepoint()</code> invocations that Velocity
+ cannot express cleanly. Use <code>.groovy</code> template files.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Generating a fixed-structure output (e.g., XML schema, property file)
+ entirely from metadata already in the source element tree, where a
+ template would add no value over direct programmatic generation
+ </td>
+ <td><code>javaOutlet</code></td>
+ <td>
+ A Java class implementing <code>Outlet</code> generates the output
+ directly. No template file is needed; use the <code>class</code>
+ attribute instead of <code>path</code> in the outlet declaration.
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ To use a custom outlet type not covered above, implement a SAX handler
+ factory and register it via the
<code>ReflectionOutletSaxHandlerFactory</code>
+ naming convention (see the Configuration section below).
+ </p>
+ </section>
+
<section name="Configuration">
- As the different outlet types need different configurations, a
- custom configuration parser is needed for each outlet type.
- (The generator type is determined by the "xsi:type" attribute of the
- outlet and filenameOutlet elements in the project configuration).
- The Torque generator needs to be told which parser it should use for which
- outlet type. This is done by registering a outletHandlerFactory
- for each generator type, see the register methods in the
- <code>org.apache.torque.generator.configuration.OutletTypes</code> class.
- The outletTypes instance is accessible via the ConfigurationHandlers
- instance in the Configuration object.
- This could in principle be used to plug in new outlet types,
- but alas, the configuration object is hidden in the controller instance
- and not accessible from the outside :-(. However, there is one
- handler factory registered by default, the
-
<code>org.apache.torque.generator.configuration.outlet.ReflectionOutletSaxHandlerFactory</code>,
- which can be used to access new outlet types using a naming convention;
- which suffices to register new outlet types.
+ <p>
+ Because each outlet type needs a different configuration parser, a
+ <em>SAX handler factory</em> is registered for each outlet type via the
+ <code>register</code> methods in
+ <code>org.apache.torque.generator.configuration.OutletTypes</code>.
+ The outlet type is determined by the <code>xsi:type</code> attribute of
+ the <code>outlet</code> and <code>filenameOutlet</code> elements in the
+ project configuration.
+ </p>
+
+ <p>
+ Three outlet SAX handler factories are registered by default:
+ </p>
+ <ul>
+ <li>
+
<code>org.apache.torque.generator.configuration.outlet.VelocityOutletSaxHandlerFactory</code>
+ — handles <code>xsi:type="velocityOutlet"</code>; reads the
<code>path</code> attribute
+ and loads the referenced <code>.vm</code> Velocity template from the
classpath.
+ </li>
+ <li>
+
<code>org.apache.torque.generator.configuration.outlet.GroovyOutletSaxHandlerFactory</code>
+ — handles <code>xsi:type="groovyOutlet"</code>; reads the
<code>path</code> attribute
+ and loads the referenced <code>.groovy</code> script.
+ </li>
+ <li>
+
<code>org.apache.torque.generator.configuration.outlet.JavaOutletSaxHandlerFactory</code>
+ — handles <code>xsi:type="javaOutlet"</code>; reads the
<code>class</code> attribute
+ and instantiates the named Java class directly (no template file
involved).
+ </li>
+ </ul>
+
+ <p>
+ In addition, a fourth factory is registered as an extension mechanism:
+ </p>
+ <ul>
+ <li>
+
<code>org.apache.torque.generator.configuration.outlet.ReflectionOutletSaxHandlerFactory</code>
+ — a dynamic dispatcher. Given a novel <code>xsi:type</code> value
+ (e.g., <code>"foo"</code>), it constructs the expected handler class
name by
+ naming convention (e.g., <code>FooSaxHandler</code>) and loads it via
reflection.
+ This allows new outlet types to be added without modifying
<code>OutletTypes.java</code>
+ — the new SAX handler class just needs to be on the classpath.
+ </li>
+ </ul>
+
+ <p>
+ The <code>OutletTypes</code> instance is accessible from the
+ <code>ConfigurationHandlers</code> held by the
<code>Configuration</code> object.
+ Note that the configuration object is encapsulated inside the controller
instance;
+ the reflection-based factory is therefore the practical way to register
custom outlet
+ types at runtime.
+ </p>
</section>
</body>
Added:
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/workflow.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++
db/torque/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/generator-internals/workflow.xml
Tue Aug 11 13:36:00 2026 (r1937059)
@@ -0,0 +1,267 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<document>
+
+ <properties>
+ <title>Generation Workflow and Call Hierarchy</title>
+ </properties>
+
+ <body>
+
+ <section name="Generation Workflow Overview">
+
+ <p>
+ The Torque code-generation pipeline processes XML schema files and
produces Java ORM
+ classes and SQL DDL through a four-stage pipeline. The entry point is
either an Ant
+ task (<code>TorqueGeneratorTask</code>) or a Maven mojo
(<code>TorqueGeneratorMojo</code>);
+ both delegate to the same internal <code>Controller</code>.
+ </p>
+
+ <p>
+ The full call chain from an Ant invocation:
+ </p>
+
+ <source><![CDATA[
+User build (Ant build.xml or Maven pom.xml)
+ └── TorqueGeneratorTask.execute() [torque-ant-tasks]
+ └── Controller.run() [torque-generator]
+ ├── Configuration reads templates + generator config
from classpath/jar
+ │ └── UnitConfiguration per generation unit (om, sql,
jdbc2schema)
+ ├── SourceProvider reads XML schema files from sourceDir
+ │ └── FileSourceProvider → parses schema XML → SourceElement
tree
+ ├── SourceTransformer optional pre-processing of source
model
+ ├── Outlet (template engine)
+ │ └── configPackage selects template set:
+ │ • org.apache.torque.templates.om → Java ORM Base*
+ header classes
+ │ • org.apache.torque.templates.sql → *-schema.sql
DDL files
+ │ • org.apache.torque.templates.jdbc2schema →
schema.xml from live DB
+ └── ExistingTargetStrategy merge / replace / skip for
already-generated files
+ └── MergeTargetFileStrategy uses JGit three-way merge to
preserve hand-edits
+]]></source>
+
+ <p>
+ Two <code>torque-generator</code> invocations are required for each
project:
+ </p>
+ <ol>
+ <li>
+ <strong>ORM generation</strong>
(<code>configPackage=org.apache.torque.templates.om</code>)
+ — writes <code>Base*</code> classes to
<code>target/generated-sources/</code> and
+ editable header classes to <code>src/main/generated-java/</code>.
+ </li>
+ <li>
+ <strong>SQL generation</strong>
(<code>configPackage=org.apache.torque.templates.sql</code>)
+ — writes DDL files to <code>target/generated-sql/</code>.
+ </li>
+ </ol>
+
+ </section>
+
+ <section name="Stage 1: Source Reading">
+
+ <p>
+ The <code>SourceProvider</code> interface abstracts how schema data
enters the pipeline.
+ The standard implementation is <code>FileSourceProvider</code>, which
reads XML schema
+ files from the directory specified by <code>sourceDir</code> in the
Ant task or
+ <code>schemaDir</code> in the Maven mojo.
+ </p>
+
+ <p>
+ Each schema file is parsed into a <code>SourceElement</code> tree — a
generic
+ node-attribute model that the template engine traverses. The root
element corresponds
+ to the <code><database></code> element of the schema XML, with
child elements
+ for each <code><table></code>, <code><column></code>,
+ <code><foreign-key></code>, and <code><view></code>.
+ </p>
+
+ <p>
+ Key classes in <code>torque-generator</code>:
+ </p>
+ <ul>
+ <li>
+ <code>org.apache.torque.generator.source.SourceProvider</code> —
interface
+ </li>
+ <li>
+
<code>org.apache.torque.generator.source.file.PropertiesSourceProvider</code> —
for
+ properties files (used internally for options)
+ </li>
+ <li>
+
<code>org.apache.torque.generator.source.stream.FileSourceProvider</code> —
reads
+ schema XML from the filesystem
+ </li>
+ </ul>
+
+ </section>
+
+ <section name="Stage 2: Source Transformation">
+
+ <p>
+ After reading, the <code>SourceElement</code> tree may be
pre-processed by one or
+ more <code>SourceTransformer</code> implementations. Transformers can
add, remove, or
+ modify nodes before template rendering begins. This stage is optional;
the ORM and SQL
+ template sets include transformers that compute derived attributes
(e.g., Java class
+ names from SQL table names, column getter/setter names).
+ </p>
+
+ <p>
+ Transformers are declared in the generator configuration XML bundled
inside the
+ <code>torque-templates</code> JAR. Custom transformers can be
contributed via the
+ generator configuration.
+ </p>
+
+ </section>
+
+ <section name="Stage 3: Template Rendering">
+
+ <p>
+ The <code>Outlet</code> interface represents a template engine
invocation. Two
+ implementations are used:
+ </p>
+ <ul>
+ <li>
+ <strong>Velocity outlets</strong> — most ORM and SQL templates use
Apache Velocity
+ (files with <code>.vm</code> extension inside the template JAR).
+ </li>
+ <li>
+ <strong>Groovy outlets</strong> — some helper outputs use Groovy
scripts for
+ programmatic control.
+ </li>
+ </ul>
+
+ <p>
+ The <code>configPackage</code> attribute on the Ant task selects which
template set
+ to apply. The generator locates templates either from the classpath
(when
+ <code>packaging="classpath"</code>) or from a directory on the
filesystem (when
+ <code>packaging="directory"</code>).
+ </p>
+
+ <p>
+ <strong>classpath packaging</strong> (recommended): the template
resources are loaded
+ from the <code>torque-templates</code> JAR on the Ant classpath. The
generator finds
+ the generator configuration XML at
+ <code>org/apache/torque/templates/om/generator.xml</code> (for the om
template set)
+ inside the JAR. This is the standard deployment mode used in
+ <code>build-torque.xml</code>.
+ </p>
+
+ <p>
+ <strong>directory packaging</strong>: the template resources are read
from a local
+ directory. This mode is used during template development or when
customising templates
+ without rebuilding the JAR.
+ </p>
+
+ <p>
+ For each output file, the <code>Controller</code> calls
+ <code>Outlet.generate(SourceElement, GeneratorContext)</code>, which
renders the
+ template against the current schema element and returns the generated
content as a
+ string.
+ </p>
+
+ <p>
+ For a full breakdown of which outlet type each standard template set
uses, how to
+ choose the correct outlet type for a new template set, and the
declaration syntax
+ for each type, see <a href="outletTypes.html">Outlet Types</a>.
+ </p>
+
+ </section>
+
+ <section name="Stage 4: Output Merge">
+
+ <p>
+ After rendering, the <code>ExistingTargetStrategy</code> decides what
to do when the
+ target output file already exists. Three strategies are available:
+ </p>
+
+ <ul>
+ <li>
+ <strong>replace</strong> — always overwrite the existing file. Used
for
+ <code>Base*</code> classes in <code>target/generated-sources/</code>.
+ </li>
+ <li>
+ <strong>skip</strong> — never overwrite. Used when a file has been
manually
+ customised and should not be touched by the generator again.
+ </li>
+ <li>
+ <strong>merge</strong> — perform a JGit three-way merge between the
previous
+ generated content, the current generated content, and the user's
hand-edited
+ version. Used for header classes in
<code>src/main/generated-java/</code>.
+ The implementation is <code>MergeTargetFileStrategy</code>, which
uses
+ Eclipse JGit to compute the merge without requiring a Git repository
on disk.
+ </li>
+ </ul>
+
+ <p>
+ The merge strategy means that developers can safely add custom methods
and fields
+ to header classes and re-run generation without losing their changes,
as long as
+ those changes do not overlap with sections modified by the generator.
+ </p>
+
+ <p>
+ The strategy for each output is declared in the generator
configuration XML inside
+ <code>torque-templates</code>. To inspect which strategy a given
output uses, look
+ at the <code><existingTargetStrategy></code> element in the
relevant
+ <code>generator.xml</code> file inside the JAR.
+ </p>
+
+ </section>
+
+ <section name="Reverse Engineering (jdbc target)">
+
+ <p>
+ The reverse-engineering pipeline reuses the same
<code>Controller</code> infrastructure
+ but uses a different entry point and template set:
+ </p>
+
+ <ul>
+ <li>
+ <strong>Entry point</strong>: <code>Torque4JDBCTransformTask</code>
(Ant) →
+ <code>TorqueJDBCTransformTask</code> (internal) — these tasks
connect to a live
+ database via JDBC and build a <code>SourceElement</code> tree from
the JDBC metadata
+ (tables, columns, primary keys, foreign keys).
+ </li>
+ <li>
+ <strong>Template set</strong>:
<code>configPackage=org.apache.torque.templates.jdbc2schema</code>
+ — renders the JDBC metadata tree into a <code>schema.xml</code> file
written to
+ <code>target/generated-schema/</code>.
+ </li>
+ <li>
+ <strong>Output strategy</strong>: replace (the generated
<code>schema.xml</code>
+ is always overwritten on each invocation).
+ </li>
+ </ul>
+
+ <p>
+ After reverse engineering, the generated <code>schema.xml</code> is a
starting point
+ for hand-editing. Copy it to <code>src/main/schema/</code>, rename it
to match
+ <code>torque.project</code>, and then run <code>ant generate</code> to
produce ORM
+ classes and SQL DDL from it.
+ </p>
+
+ <p>
+ Because reverse engineering requires a running database instance with
JDBC credentials,
+ the <code>jdbc</code> Ant target is a manual-only operation and is not
part of
+ automated CI.
+ </p>
+
+ </section>
+
+ </body>
+
+</document>
Modified:
db/torque/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step1-ant.xml
==============================================================================
---
db/torque/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step1-ant.xml
Tue Aug 11 12:45:04 2026 (r1937058)
+++
db/torque/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step1-ant.xml
Tue Aug 11 13:36:00 2026 (r1937059)
@@ -199,6 +199,81 @@
</section>
+<section name="Using the torque-build Reference Module">
+
+<p>
+ Instead of crafting the <code>build.xml</code> Ant file by hand, you can use
the
+ <strong>torque-build</strong> reference module that ships with the Torque
source
+ distribution. It provides a ready-to-use <code>build-torque.xml</code> with
all
+ generation and compilation targets pre-configured, plus a
<code>build.properties</code>
+ file where you set your database-specific settings.
+</p>
+
+<p>
+ The reference module uses <code>torque.database=postgresql</code> as its
default,
+ so you can test generation without an external database. To switch
databases, open
+ <code>build.properties</code>, comment out the PostgreSQL line, and
uncomment the
+ block for your database (MySQL, HSQLDB).
+</p>
+
+<p>
+ To use <code>torque-build</code> as your starting point:
+</p>
+
+<ol>
+ <li>
+ Copy <code>torque-build/build-torque.xml</code> and
+ <code>torque-build/build.properties</code> into your project root.
+ </li>
+ <li>
+ Place your schema XML file in <code>src/main/schema/</code>.
+ </li>
+ <li>
+ Edit <code>build.properties</code>: set <code>torque.database</code> and
+ (for non-Derby databases) the JDBC driver, URL, user, and password.
+ </li>
+ <li>
+ Resolve all runtime dependencies and run generation with one command:
+ <source>mvn process-resources -Pexamples</source>
+ Or, if you prefer to invoke Ant directly, first resolve dependencies:
+ <source>mvn dependency:copy-dependencies -DincludeScope=runtime
-DoutputDirectory=libs</source>
+ then run:
+ <source>ant generate -f build-torque.xml
+ant compile -f build-torque.xml</source>
+ </li>
+</ol>
+
+<p>
+ After generation you will find:
+</p>
+
+<ul>
+ <li>
+ Generated Java ORM base classes in <code>target/generated-sources/</code>
+ </li>
+ <li>
+ Editable header classes in <code>src/main/generated-java/</code>
+ </li>
+ <li>
+ Generated SQL DDL in <code>target/generated-sql/</code>
+ </li>
+</ul>
+
+<p>
+ <strong>JGit merge</strong>: the Torque generator uses a JGit three-way
merge strategy
+ for files in <code>src/main/generated-java/</code>. This means you can
safely add custom
+ logic to the header classes and re-run <code>ant generate</code> without
losing your
+ hand-edits — the generator merges new output with your changes.
+</p>
+
+<p>
+ See <code>torque-build/README.md</code> in the source distribution for the
full
+ configuration guide, including database-specific property blocks, the
complete Ant
+ target reference, and logging configuration.
+</p>
+
+</section>
+
<section name="Library set-up">
<p>
For the Torque generator/jdbc and SQL ant tasks to work correctly,
@@ -224,8 +299,8 @@
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).
</li>
<li>
- Download the <a
href="http://www.apache.org/dyn/closer.cgi/db/torque/torque-5.0/";>sources</a>
and run from the source repo's sub folder
- <code>cd torque-5.0/torque-generator</code> the following command, which
copies all dependencies if Torque Generator to libs.
+ Download the <a
href="http://www.apache.org/dyn/closer.cgi/db/torque/torque-7.0/";>sources</a>
and run from the source repo's sub folder
+ <code>cd torque-7.0/torque-generator</code> the following command, which
copies all dependencies if Torque Generator to libs.
<code>mvn clean dependency:copy-dependencies -DincludeScope=runtime
-DoutputDirectory=libs -DexcludeScope=test</code>)
</li>
<li>To configure Logging (Log4j2) set e.g.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
