<?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 6 - Compiling and Running the Sample Application</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 6: Compiling and Running the sample application">

<subsection name="Compiling the sample application">

<p>
  Now that you've generated your object model with
  Torque, and created a sample application, you are
  now ready to compile everything.  Again, Maven is used
  to control the build process.
</p>
<p>
  First, we need to tell maven where the java source
  files are located. To do this, add the following section
  just after the <code>&lt;dependencies&gt;</code> of your
  <em>project.xml</em> which you created sooner on in the
  top level directory of your project:
</p>

<source><![CDATA[
  <build>
    <sourceDirectory>src/java</sourceDirectory>
  </build>
]]></source>

<p>
  Afterwards, you can compile your jave source files
  by typing the following in the top-level directory
  of your project:
</p>

<source><![CDATA[
maven java:compile
]]></source>

<p>
  If you've done everything correctly, this should
  build without any errors.  All of the resulting Java
  class files are placed in the
  <em>target/classes</em> directory.  If the compiler
  misses any external libraries, review the
  &lt;dependencies&gt; section in your
  <em>project.xml</em>.  Should you
  encounter other errors, go back and review your
  application code.
</p>

</subsection>

<subsection name="Running the sample application">

<p>
  Before you run the sample application, you must
  first set your classpath (this was done
  automatically for you by Maven when you
  compiled).  The classpath must include: all of the
  jars denoted in the &lt;dependencies&gt; section
  of your <em>project.xml</em>, and all of your
  application and object model classes located in
  <em>target/classes</em>.
</p>

<p>
  Before compiling your application,
  maven will have downloaded all libraries
  your project depends on to the local maven repository.
  Gathering them from there is a cumbersome process.
  To ease copying them into one place, we modify
  Maven's build process a little.
  For this, you need to create a new file called
  <em>maven.xml</em> in the top-level directory
  of your project. It needs to have the
  following content:
</p>

<source><![CDATA[
<project xmlns:java="java" xmlns:deploy="deploy">
  <postGoal name="java:compile">
    <!-- include listed dependencies -->
    <deploy:copy-deps todir="${maven.build.dir}/lib"/>
    <!-- include torque.properties -->
    <copy file="src/conf/torque.properties" todir="${maven.build.dir}" />
  </postGoal>
</project>
]]></source>

<p>
  After creating the file, re-run
</p>

<source><![CDATA[
maven java:compile
]]></source>

<p>
  Now change into the target directory. In addition
  to the <em>classes</em> subdirectory which was
  already created in the first compilation run,
  you see that maven has generated an additional
  <em>lib</em> directory which contains the needed
  libraries, and that maven also copied the
  Torque.properties file here.
</p>

<p>
  Now everything is in one place, and you can start the
  application by typing (note:exchange the mysql-connector-java-5.0.4.jar
  by the datatbase driver jar you are using)
</p>

<source><![CDATA[
java -cp classes:lib/avalon-framework-api-4.3.jar:lib/commons-beanutils-core-1.7.0.jar:lib/commons-collections-3.2.jar:lib/commons-configuration-1.4.jar:lib/commons-dbcp-1.2.2.jar:lib/commons-lang-2.3.jar:lib/commons-logging-1.1.jar:lib/commons-pool-1.3.jar:lib/jcs-1.3.jar:lib/mysql-connector-java-5.0.4.jar:lib/torque-3.3.jar:lib/village-3.3.jar com.kazmier.Bookstore
]]></source>

<p>
  If all goes well, you should see the following
  output:
</p>

<source><![CDATA[
  Full booklist:

  Title:     TCP/IP Illustrated, Volume 1
  ISBN:      0-201-63346-9
  Publisher: Addison Wesley Professional
  Author:    Stevens, W.

  Title:     Effective Java
  ISBN:      0-618-12902-2
  Publisher: Addison Wesley Professional
  Author:    Bloch, Joshua

  Booklist (specific ISBN):

  Title:     TCP/IP Illustrated, Volume 1
  ISBN:      0-201-63346-9
  Publisher: Addison Wesley Professional
  Author:    Stevens, W.

  Booklist (authors swapped):

  Title:     TCP/IP Illustrated, Volume 1
  ISBN:      0-201-63346-9
  Publisher: Addison Wesley Professional
  Author:    Bloch, Joshua

  Title:     Effective Java
  ISBN:      0-618-12902-2
  Publisher: Addison Wesley Professional
  Author:    Stevens, W.

  Booklist (should be empty):
]]></source>

<p>
  If your application throws an exception, it could be
  for one of many reasons, most of which are not very
  descriptive unfortunately.  Do not be discouraged if your
  application does not run the first time.  Carefully
  retrace all of the steps outlined in this tutorial.
  If you are still not able to get your application to
  run, use the Torque user
  <a href="../../../mail-lists.html">mailing list</a> to your
  advantage.
</p>

</subsection>

</section>

<section name="Where to Go From Here">

<p>
  Congratulations!  You have completed the Torque
  tutorial.  Although this has only been an introduction
  to Torque, it should be sufficient to get you started
  with Torque in your applications.  For those of you
  seeking additional information, there are several other
  documents on this site that can provide details on
  various subjects.  Lastly, the source code is an
  invaluable resource when all else fails to provide
  answers!
</p>

</section>

<section name="User Comments">
  <a href="http://wiki.apache.org/db-torque/TutorialUserCommentsStep6">User comments</a>
  for this step
</section>

  </body>
</document>
