<?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 Maven Plugin</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 Maven Plugin">

<p>
  With the configuration of Maven 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[
mvn generate-sources
]]></source>

<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 maven's target directory
  which can be deleted during a maven build.
  The other classes can be edited once generated
  and will not be overwritten if they exist, so they reside in the
  src tree which is not altered by maven.
  All generated classes will be in a directory hierarchy matching that of the
  <code>torque.om.package</code> option you
  specified in <em>pom.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 Maven 2 pom file.
  Check again the contents of these files.
</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 maven.
  This is not a problem for most drivers 
  (e.g. mysql, postgresql, derby...)
  but some drivers (e.g. oracle) are not available
  in the maven central repository and must be added
  to your local maven repository manually
  (check the maven 2 docs on how to do this.)
</p>

<subsection name="Specifying the driver dependency">

<p>
  There are two places where the database driver appears:
  once in the main dependencies section,
  and once in the dependencies of the maven sql plugin 
  which can execute the sql generated by Torque.
</p>

<p>
  The tutorial uses mysql as database, and the pom templates
  given in step 1 already include a mysql dependency,
  so the pom xml in the tutorial project can remain unchanged.
</p>

</subsection>

<subsection name="Creating the tables">

<p>
  To create the database tables, you first need to create the schema
  (mysql: 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, type the following commands in
  the top-level directory of your project:
</p>

<source><![CDATA[
maven sql:execute
]]></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 maven, 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="http://wiki.apache.org/db-torque/TutorialUserCommentsStep3">User comments</a>
  for this step
</section>

  </body>
</document>
