<?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 Tutorial - Step 3: Invoking the Torque Ant task</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="Step 3: Invoking the Torque Ant Task">

<p>
  With the creation of the build file and definition of the
  database schema completed, you can now
  generate the object model to support your database,
  and create the database tables.
  Each of these tasks is covered in the following sections.
</p>

<p>
  The generation of your object model will produce
  Java source files that represent your database structure.
  These classes enable you to create, edit,
  delete, and select objects that represent rows in
  your database tables.  In addition, Torque will
  generate SQL to create your database tables (you
  have the option of executing the SQL via maven as demonstrated
  later in this tutorial).
</p>

<p>
  The object model consists of eight classes for each
  table in your schema.  For example, the
  <em>book</em> table, defined in this tutorial,
  will result in the following eight classes:
  <em>Book</em>, <em>BookPeer</em>, 
  <em>BookPeerImpl</em>, <em>BookRecordMapper</em>,
  <em>BaseBook</em>, <em>BaseBookPeer</em>, 
  <em>BaseBookPeerImpl</em>, and <em>BaseBookRecordMapper</em>
  (a detailed discussion on the use of these classes is deferred
  until we write our sample application). See the image below for
  a UML class diagram of the generated classes and their relations.
  <img src="../../../images/generated-classes.png" alt="generated classes"/>
</p>

<p>
  To generate your object model and the associated SQL, type the
  following command in your top-level project directory:
</p>

<source><![CDATA[
ant generate
]]></source>

  Hint: You have to create a build copy of your <em>bookstore-schema.xml</em> 
  named <em>schema.xml</em> in the sourceDir (by default src/main/schema) directory!

<p>
  A successful build will be indicated by the
  BUILD SUCCESSFUL message.
</p>

<p>
  The generated Java source files are located in the
  <em>target/generated-sources</em> (BaseXXX) 
  and <em>src/main/generated-java</em> (other classes)
  directories. The locations are split because the Base classes are
  generated each time anew, are not intended to be edited
  and should not be under version control if you use a version
  control system. So they reside in the target directory
  which can be deleted for a clean build.
  The other classes can be edited once generated
  and will not be overwritten if they exist, so they reside in the
  src tree.
  All generated classes will be in a directory hierarchy matching that of the
  <code>torque.om.package</code> option you
  specified in <em>build.xml</em>.
</p>

<p>
  The generated SQL files are located in the
  <em>target/generated-sql</em> directory.
  For each database schema in your
  <em>src/schema</em> directory, there will be a
  corresponding file with a <em>.sql</em> extension
  instead of <em>.xml</em> extension.  The contents of
  these files are the SQL commands that can be used to
  manually or automatically (see next section) create
  your database tables.
</p>

<p>
  If you encounter errors while building, it is more
  than likely a formatting error of your database
  schema file or the ant build file, or a missing library.
  Check again the contents of these files and the lib/ant directory.
</p>

</section>

<section name="Creating the Database Tables">

<p>
  As mentioned previously, Torque can automatically
  create the database tables for you.
  However, you must first make sure
  that the appropriate database driver can be accessed by ant.
  We already did that by adding the mysql driver jar
  to the lib/ant directory of your project.
</p>

<subsection name="Creating the tables">

<p>
  To create the database tables, you first need to create the schema
  (in mysql speak: database) which you want to use for the tables.
  E.g. in mysql, execute the following command as root user:
</p>
<source>
  create database bookstore;
</source>

<p>
  If you want to use another database user than root to create the tables,
  make sure that this user has sufficient privileges on the database bookstore
  to create tables. Alternatively, you can just use the root user
  to create the database tables.
  In both cases, check again that the username, password and url
  of your mysql database is correct in the build.xml,
  and type the following command in the top-level directory of your project:
</p>

<source><![CDATA[
ant execute-sql
]]></source>

<p>
  Success will be indicated by the message 
  8 of 10 SQL statements executed successfully
  BUILD SUCCESSFUL.
  (Torque assumes that you already have defined a database,
  and performs a drop before attempting recreation.
  The statements dropping the foreign keys fail because 
  the table does not exist, but this is not a problem
  for creating the tables. If you re-run the command,
  all 10 statements will execute successfully.)
  You can also validate that the tables were created
  by checking your database.  For example, the
  <em>bookstore-schema.xml</em> defined in this
  tutorial should have created the following tables:
  <em>author</em>, <em>book</em>,
  and <em>publisher</em>.
</p>

<p>
  If you have difficulties in creating the tables 
  using ant, you can also execute the SQL script 
  generated in the directory <em>target/generated-sql</em> 
  manually.
</p>

</subsection>

</section>

<section name="Where to next">

  <p>
    Now that you have generated all of your object model
    classes and created your database, you are ready to
    build your first Torque application.
  </p>
  <p>
    Next we will look <a href="step4.html">Configuring the Torque Runtime</a>.
  </p>

</section>

<section name="User Comments">
  <a href="https://cwiki.apache.org/DBTORQUE/TutorialUserCommentsStep3">User comments</a>
  for this step
</section>

  </body>
</document>
