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.
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.