<?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.
-->

<document>
  <properties>
    <title>Torque 4 Tutorial</title>
    <author email="pete-apache-dev@kazmier.com">Pete Kazmier</author>
    <author email="seade@backstagetech.com.au">Scott Eade</author>
    <author email="fischer@seitenbau.de">Thomas Fischer</author>
  </properties>
  <body>

<section name="About this Tutorial">

<p>
  This tutorial is intended to give first-time users an
  introduction to using Torque. Torque has two primary foci: It is a
  tool for java code generation and, building on top of that, it provides
  object-relational mapping (ORM) for database access in java.
  These two aspects are treated in different parts of this tutorial;
  the two parts can be read independently of each other.
</p>

<p>
  Both parts include how to obtain and install the relevant parts of Torque.
  The ORM part then contains setting up a database
  and writing a sample application.
  The code generation part shows how the Torque generator can be used
  for custom code generation.<br/>
  The tutorial is not a reference. Refer to the 
  <a href="../modules/templates/index.html">Torque templates documentation</a>
  and 
  <a href="../modules/runtime/index.html">Torque runtime documentation</a>
  for more detailed information about the ORM part, and to the
  <a href="../modules/generator/index.html">Torque generator documentation</a>
  for the generator part.
</p>

<p>
  In this tutorial, it is assumed that you have experience
  in programming in Java. It is also assumed that you have already been using
  either <a href="http://ant.apache.org">Ant</a> or 
  <a href="http://maven.apache.org">Maven</a> (if you do not know one of these
  build systems, please look at one of the introductions at their home pages).
  It is expected that you have a working installation of the
  JDK, Version 1.5 or higher.
  <br/>
  The ORM part further assumes that you have some experience using JDBC 
  (e.g. you should know what a jdbc driver and a connection URL is).
</p>

<p>
  For each step in the tutorial, user comments are available
  in the
  <a href="http://wiki.apache.org/db-torque/">Torque Wiki</a>,
  see the links at the bottom of each page.
  If you had difficulties with a particular step and found
  a solution, please write it up and add it to the corresponding
  wiki page for each step.
</p>

<p>
  If you are using Torque for the first time, you should
  stick very closely to the example provided in the Tutorial,
  and get the samples running as they are.
  If you play around, there are quite a few places where
  things can go wrong, and is not always clear why they go wrong.
  Errors are much easier to find when you can pinpoint
  the source of the error by
  &quot;Ok, it went wrong when I changed foo&quot;.<br />
  Once you got a running example, you can (and should) still
  play around to see whether Torque can satisfy your particular
  needs.
</p>

<p>
  The ORM part used throughout this tutorial is based on an
  email sent to the turbine-user mailing list by
  Steven F. Davis called
  <a href="http://mail-archives.apache.org/mod_mbox/jakarta-turbine-user/200109.mbox/%3cBCAC8D6E905D234C84A49D1524A19CD1044FF7@bemail.BEDOMAIN.BEAP.COM%3e">
  torque outside turbine - detailed example (long)</a>.
</p>

</section>

<section name="Torque modules">
<p>
  Torque is divided into several parts, some of which can be used
  independenty of other parts:
  <ul>
    <li>
      The Torque generator is a general code generation tool. It reads input from
      various sources, e.g. XML files or JDBC Metadata, and creates output
      files (e.g. java files, sql files).
    </li>
    <li>
      The Torque Maven plugin integrates the generator into
      <a href="http://maven.apache.org">Maven</a>, a software
      project management tool. In other words, the maven plugin is
      a maven frontend for the generator.
    </li>
    <li>
      The Torque ant tasks integrate the generator into
      <a href="http://ant.apache.org">Ant</a>, a java build tool.
    </li>
    <li>
      The Torque templates use the Torque generator to generate 
      OR Mapping java classes which can access your database.
      They also generate SQL scripts to create all the necessary tables,
      constraints etc. in your database.
      The information about the database structure
      is contained in an XML file read by the Torque generator.
      The structure of this file is also defined by the Torque templates.
    </li>
    <li>
      The Torque runtime has to be included in ORM projects to use the classes
      generated by the generator using the templates.
    </li>
  </ul>
</p>
</section>


<section name="Where to next">

<p>
  For the ORM part, we will first look at 
  Configuring the Torque generation process.
  If you are using Maven as build system, look at 
  <a href="orm/step1-maven.html">configuring Maven for Torque</a>.
  If you plan to use ant, look at
  <a href="orm/step1-ant.html">configuring Ant for Torque</a>
  For the code generation part, see
  <a href="codegen/gettingStarted.html">getting started with Torque code generation</a>.
</p>

</section>

<section name="User Comments">
  <a href="http://wiki.apache.org/db-torque/TutorialUserComments">User comments</a>
  for the tutorial as a whole and this page
</section>

  </body>
</document>

