<!---
 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.
-->

# Apache Db Torque Project 

## General 

- Apache Torque is an object-relational mapper using java.
- It generates the necessary classes (including the Data Objects) from an XML schema describing the database layout.
- it uses velocity / groovy templates during the code generation process.

## Requirements

- Version 9 will require Java 21 or higher.
- Versions 8 requires Java 17
- Versions 7.x requires Java 17.
- Version 6 requires Java 11. 
- Version 5 and 5.1 require Java 8. 
- Torque 4.0 requires JDK 1.6 or higher

- Build and Tests run with Java 8 and 14 (v5.1) and Java 20 (v6.0). 

- IDE integration

To run with eclipse skip torque Maven plugin, which tries to generate classes from unconfigured 

    mvn eclipse:eclipse -Dmaven.torque.skip=true
    
or try it with default database and activated beans and managers profile (some Java classes depend on this):

    mvn eclipse:eclipse -hsqldb,beans,managers
   

### Modules

- This project consists of seven modules

    - torque-runtime 
    - torque-generator
    - torque-templates
    - torque-maven-plugin 
    - torque-ant-tasks
    - torque-site 
    - torque-test (internal only)
    - torque-build (internal only)


### Core modules

*Torque-generator* is the core module providing the mechanism to generate the mappings, 
which are provided by *Torque-templates* module. You need the ant tool installed.

*Torque-runtime* is the only module needed, if building / generation step was done.


#### Test module

Two kinds of tests exist. Module "internal" tests without database dependency or explicitely inlined 
dependency as in torque-templates (ddl templates) database testing in the module "Torque-test".

*Torque-test* allows to test against databases and provides a [README](torque-test/README.md) of its own. 
You need the ant tool installed.

You start Torque-Test module in the **torque-test folder** by this command (with default database hsqldb) 

    mvn clean install -Phsqldb,beans,managers


#### Site module

*Torque-site* is used to generate the site (add post-site to merge the documentation of dependent modules. 
You need the ant tool installed. Run this command from the root folder: 

    mvn site post-site

N.B. This has to be run from root folder, as torque-site expects existing target/site folders for each module (torque-test amd torque-build are not included).
Required minimal memory 1GB, set Maven_OPTS=2G.

The ant build tool does not (yet) include pmd/xref reports in the final site building, 
although they are build for inspection in each sub module (except test). 

    
#### Build modules

- *Torque-maven-plugin* provides a Maven plugin (generator).

- *Torque-ant-tasks* is to provide some ant tasks to generate the Torque artefacts (xml, java, sql).

To build all with checksums run in root 

    mvn clean install -Papache-release

*Change from previous releases*
  
Profile apache-release does not activates torque-test profile anymore, which was completely removed. Runing torque-test module now happens only from within the folder torque-test.

#### Security Check
    
To check seucrity issues run profile owasp (or set -Ddependency.check.skip=false)

    mvn package -Papache-release,hsqldb-jenkins,beans,managers,owasp 
    
The flag dependency.check.skip is set in the owasp profile to false, which is by default true.

#### Provided  database profiles

- derby (not supported since Torque 8)
- derbyEmbedded (deprecated since Torque 8)
- hsqldb
- mssql
- mysql
- oracle
- postgresql

#### Other profiles

- apache-release
- owasp

#### Deploy Artifacts and Release modules

Find more information here: [Developer Guide|https://db.apache.org/torque/torque-5.0/developer-info/developer-guide.html]

Check versions with Maven Versions Plugin:

    - mvn versions:display-plugin-updates
    - mvn versions:display-dependency-updates
    - mvn versions:display-property-updates

- Requirements

Public Key is added to KEYS. 

##### Deploy artifacts

You will be asked for your gpg passphrase during the build process, if not provided otherwise.

    mvn clean package -Papache-release,hsqldb-jenkins,beans,managers
    mvn deploy -DskipTests=true
    

##### Release modules

First test the release locally and run integration tests in folder torque-test, until the build is successfull, 
then clean again and run and perform release (from the parent root):

    mvn release:prepare -DdryRun=true -DautoVersionSubmodules=true -Papache-release

    mvn release:clean ..
    
You have to add profiles hsqldb-jenkins to allow for running the test module (which is included by profile apache-release; find more information below in Note)
and profile apache-release to create the release checksums.
    
    mvn release:prepare -DautoVersionSubmodules=true -Papache-release
    
    mvn release:perform 
    
Note: We need to add profiles managers, beans as release perform does a checkout 
of the tagged version (which is then uploaded to nexus) and is running the build process again. 
In module torque-test the beans and manager java is generated only, if the beforementioned profiles are active.

###### Important information for release build 

From the developer-guide: Running release:prepare "will change the version in the poms 
to the release version and then run a clean verify cycle on the new poms. 
This will fail because **the test project** needs the *torque maven plugin* which is not installed
in the new version yet. 
To fix this, you might have to run **rm derby.log**, 
then run **mvn install** to install the torque artifacts in the release version.
    
Then run again **mvn -Ptest release:prepare ..**  to finish building the release.
This requires **activated profile test** to also apply the release prepare step to module torque-test, 
which is by default not in modules list.


Now close the staging repository after Login in Nexus Repo
  https://repository.apache.org/index.html#stagingRepositories
  
Then prepare voting information and voting. 

If voting was successfull, proceed by publishing in Nexus Repo and distribute binaries and sources to website. Otherwise drop the staged repo in Nexus repo.

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.