db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r232619 - in /db/torque/trunk/xdocs: changes.xml navigation.xml tutorial/index.xml tutorial/step1.xml tutorial/step2.xml tutorial/step3.xml tutorial/step4.xml
Date Sun, 14 Aug 2005 16:24:41 GMT
Author: tfischer
Date: Sun Aug 14 09:24:18 2005
New Revision: 232619

URL: http://svn.apache.org/viewcvs?rev=232619&view=rev
Log:
Updated the tutorial. The following was done:
- Separated the configuration of generator and runtime
- Separated writing of the sample application and compiling/running the sample application
- Thrown out confusing hints what the user should do if he does not use maven. The User is using maven to run the tutorial. Full stop. (Just retained one reference to the build-torque ant file).
- Added information so that a user who has never used maven before can run the tutorial.
- Thrown out stuff that is not absolutely necessary to understand what the user is doing and how the sample application works, but retaining links like "For more information, look here"

Modified:
    db/torque/trunk/xdocs/changes.xml
    db/torque/trunk/xdocs/navigation.xml
    db/torque/trunk/xdocs/tutorial/index.xml
    db/torque/trunk/xdocs/tutorial/step1.xml
    db/torque/trunk/xdocs/tutorial/step2.xml
    db/torque/trunk/xdocs/tutorial/step3.xml
    db/torque/trunk/xdocs/tutorial/step4.xml

Modified: db/torque/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewcvs/db/torque/trunk/xdocs/changes.xml?rev=232619&r1=232618&r2=232619&view=diff
==============================================================================
--- db/torque/trunk/xdocs/changes.xml (original)
+++ db/torque/trunk/xdocs/changes.xml Sun Aug 14 09:24:18 2005
@@ -28,6 +28,9 @@
   <body>
 
   <release version="3.2-rc2-dev" date="in CVS">
+    <action type="update" dev="tfischer">
+      Reworked the tutorial.
+    </action>
     <action type="add" dev="henning">
       Added templates site reference to menus in runtime, generator, maven-plugin.
     </action>

Modified: db/torque/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/db/torque/trunk/xdocs/navigation.xml?rev=232619&r1=232618&r2=232619&view=diff
==============================================================================
--- db/torque/trunk/xdocs/navigation.xml (original)
+++ db/torque/trunk/xdocs/navigation.xml Sun Aug 14 09:24:18 2005
@@ -24,6 +24,8 @@
         <item name="Step 2"              href="/tutorial/step2.html"/>
         <item name="Step 3"              href="/tutorial/step3.html"/>
         <item name="Step 4"              href="/tutorial/step4.html"/>
+        <item name="Step 5"              href="/tutorial/step5.html"/>
+        <item name="Step 6"              href="/tutorial/step6.html"/>
       </item>
       <item name="User Guide"            href="/user-guide.html"/>
       <item name="Inheritance Guide"     href="/inheritance-guide.html"/>

Modified: db/torque/trunk/xdocs/tutorial/index.xml
URL: http://svn.apache.org/viewcvs/db/torque/trunk/xdocs/tutorial/index.xml?rev=232619&r1=232618&r2=232619&view=diff
==============================================================================
--- db/torque/trunk/xdocs/tutorial/index.xml (original)
+++ db/torque/trunk/xdocs/tutorial/index.xml Sun Aug 14 09:24:18 2005
@@ -5,6 +5,7 @@
     <title>Torque 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>
 
@@ -26,10 +27,34 @@
 </p>
 
 <p>
+  In this tutorial, it is assumed that you have experience 
+  in programming in Java, and that you have some experience
+  using JDBC (e.g. you should know what a jdbc driver and a
+  connection URL is).
+  Although <a href="http://maven.apache.org/">Maven</a> 
+  is heavily used in this tutorial, it is not assumed that 
+  you have any experience in using it.
+</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 sample application running as is. 
+  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 example 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/eyebrowse/ReadMsg?listName=turbine-user@jakarta.apache.org&amp;msgNo=5287">
+  <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>.
   It has subsequently been updated for Turbine 3.1 which
   separates the <a href="../generator/">generator</a> from
@@ -44,8 +69,7 @@
 <section name="Where to next">
 
 <p>
-  First we will look at <a href="step1.html">Obtainning the Torque 
-  Distribution</a>.
+  First we will look at <a href="step1.html">Installing Maven and the Torque Maven Plugin</a>.
 </p>
 
 </section>

Modified: db/torque/trunk/xdocs/tutorial/step1.xml
URL: http://svn.apache.org/viewcvs/db/torque/trunk/xdocs/tutorial/step1.xml?rev=232619&r1=232618&r2=232619&view=diff
==============================================================================
--- db/torque/trunk/xdocs/tutorial/step1.xml (original)
+++ db/torque/trunk/xdocs/tutorial/step1.xml Sun Aug 14 09:24:18 2005
@@ -2,14 +2,14 @@
 
 <document>
   <properties>
-    <title>Torque Tutorial</title>
+    <title>Torque Tutorial - Step 1: Installing Maven and 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>
+  </properties>
   <body>
 
-<section name="Step 1: Obtaining the Torque Distribution">
+<section name="Step 1: Installing Maven and the Torque Maven Plugin">
 
 <p>
   First of all, note that Torque is divided into three parts.
@@ -25,7 +25,8 @@
     <li>
       The maven plugin integrates the generator into 
       <a href="http://maven.apache.org/">Maven</a>, a software 
-      project management tool.
+      project management tool. In other words, the maven plugin is 
+      a frontend for the generator.
     </li>
     <li>
       The runtime has to be included in your projects for the generated classes
@@ -34,16 +35,21 @@
   </ul>
   For this tutorial, we will be using the maven plugin for Torque 3.2.x 
   (which will silently invoke the generator) to
-  generate our object model classes and the Torque 3.2.x runtime for our
-  application that makes use of the generated classes.
+  generate our object model classes and sql scripts. For working with the 
+  generated classes, we will use the Torque 3.2.x runtime for our
+  sample application.
 </p>
 
 <p>
   If you have not already done so, download and install 
-  <a href="http://maven.apache.org/">Maven</a>.  You then need to obtain the 
-  Torque maven plugin.  The <a href="../maven-howto.html">Maven Howto</a> 
-  includes details of how to build the maven plugin from source, but you can 
-  easily install a binary distribution thus:
+  <a href="http://maven.apache.org/">Maven</a>. It is highly recommended to use 
+  version 1.0.2 of Maven.
+</p>
+
+<p>
+  Maven uses the <a href="http://www.ibiblio.org/maven">ibiblio maven repository</a>
+  to download any libraries and resources it needs. From there, obtain the Torque 
+  maven plugin by typing
 </p>
 
 <source><![CDATA[
@@ -51,17 +57,10 @@
 ]]></source>
 
 <p>
-  At runtime the generated object model classes need access to the Torque 
-  runtime distribution and associated libraries - these are available from the
-  <a href="http://db.apache.org/torque/download.html">
-  Downloads page</a> (the file to download is torque-3.2-rc1.tar.gz or 
-  torque-3.2-rc1.zip, depending on your development platform).  We will cover
-  what to do with this file in a later step.
-</p>
-
-<p>
-  If you are using the maven plugin, you do not need to download the generator 
-  separately. The maven plugin will download the needed resources.
+  You do not need to download the generator or the 
+  runtime separately. Maven will download them from 
+  the ibiblio distribution site automatically
+  when they are needed.
 </p>
 
 </section>
@@ -69,7 +68,7 @@
 <section name="Where to next">
 
 <p>
-  Next we will look at <a href="step2.html">Configuring Torque</a>.
+  Next we will look at <a href="step2.html">Configuring the Torque generator</a>.
 </p>
 
 </section>

Modified: db/torque/trunk/xdocs/tutorial/step2.xml
URL: http://svn.apache.org/viewcvs/db/torque/trunk/xdocs/tutorial/step2.xml?rev=232619&r1=232618&r2=232619&view=diff
==============================================================================
--- db/torque/trunk/xdocs/tutorial/step2.xml (original)
+++ db/torque/trunk/xdocs/tutorial/step2.xml Sun Aug 14 09:24:18 2005
@@ -2,14 +2,14 @@
 
 <document>
   <properties>
-    <title>Torque Tutorial - Step 2: Configuring Torque</title>
+    <title>Torque Tutorial - Step 2: Configuring the Torque generator</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 2: Configuring Torque">
+<section name="Step 2: Configuring the Torque generator">
 
 <p>
   The following section outlines the necessary steps to
@@ -23,28 +23,38 @@
 </p>
 
 <p>
-  To accomplish all of the above, you only need to
-  create/edit three files: the Torque generator properties,
-  the Torque database schema, and the Torque run-time
-  properties.  Each of these files is covered in the
+  To accomplish all of the above, you need to
+  create/edit the Torque generator properties file
+  (which is providing the generator with the
+  necessary information)
+  and the Torque database schema file(s) 
+  (which contain the structure of your database).
+  Each of these files is covered in the
   following sections.
 </p>
 
+<p>
+  As a starting point, create a directory as a 
+  base directory for your project (also called 
+  the project's top level directory),
+  and change into that directory.
+  All the paths in the following steps will be 
+  relative to this base directory.
+</p>
+
 </section>
 
 <section name="Torque Generator Properties">
 
 <p>
-  Torque is a system that literally generates Java
+  The Torque generator literally generates Java
   source/class files representing your object model,
   SQL statements for your specific database, and
-  documentation.  To accomplish these tasks, it uses
-  <a href="http://maven.apache.org/">Maven</a> and
-  the Torque <a href="../maven-plugin/">maven-plugin</a>
-  to drive the Torque <a href="../generator/">generator</a>.
+  documentation.  
   You configure the generator by setting properties in the
   <em>project.properties</em> file in root directory of your 
-  project - this is the file that we will edit first.
+  project.  As a starting point, use the following template
+  and edit it to reflect your specific needs
 </p>
 
 <source><![CDATA[
@@ -82,31 +92,19 @@
 ]]></source>
 
 <p>
-  For a reference as to what each property, and others, controls, please
-  see the <a href="../generator/properties-reference.html">properties 
-  reference</a>.
-</p>
-
-<p>
   Setting these properties correctly is very
-  important.  These enable Torque to generate all of
+  important.  They enable Torque to generate all of
   the required sources and SQL for your specific
   database.  If you experience problems later in this
   tutorial, it would be wise to double-check these
   values.
 </p>
 
-<subsection name="Customizing the Generator Templates">
 <p>
-  The object model class files generated by Torque are produced using a set of
-  <a href="http://jakarta.apache.org/velocity/">Velocity</a> templates that are 
-  included in the torque-gen-templates jar file.  If you want to customise the templates 
-  that are used to generate your object model class files you can either build
-  your own customised version of the torque-gen-templates jar file 
-  and install it in your local Maven repository or use additional properties
-  to tell the maven-plugin where to find your customised templates.
+  For a reference as to what each property, and others, controls, please
+  see the <a href="../generator/properties-reference.html">properties 
+  reference</a> for the Torque generator.
 </p>
-</subsection>
 
 </section>
 
@@ -115,20 +113,17 @@
 <p>
   The second file that you must edit to configure
   Torque is the database schema.  The database schema
-  is an XML file that represents your SQL database in
-  Torque.  This is where you define all of your
+  is an XML file that represents the structure of your 
+  SQL database in Torque.  
+  This is where you define all of your
   tables, column names and types, as well as the keys
   used to index these tables.
 </p>
 
 <p>
-  By default your database schema file should be located in the
-  <em>src/schema</em> directory under the base of your project, but
-  you can tell Torque where to find it using the 
-  <code>torque.schema.dir</code> property in 
-  <code>project.properties</code> (the <code>torque.home</code>
-  property can also be used to point to the parent of the 
-  <em>schema</em> directory.  Here you will
+  Your database schema file should be located in the
+  <em>src/schema</em> directory under the base of your project.
+  In this directory, you will
   create two XML files: <em>id-table-schema.xml</em> and
   <em>project-schema.xml</em>.  The
   <em>id-table-schema.xml</em> file is used internally
@@ -143,8 +138,8 @@
 </p>
 
 <p>
-  For this tutorial, we will use a simple database
-  that might be used to support a bookstore
+  In this tutorial, we will use a simple 
+  database that might be used to support a bookstore
   application.  The database will contain three
   tables: author, publisher, and book.  The first
   table will contain author information (first
@@ -153,13 +148,16 @@
   table will contain book information (title, and
   ISBN).  The author id and publisher id will be
   foreign keys in the book table.  The schema
-  representation for this database is as follows:
+  representation for this database is stored 
+  in the file <em>project-schema.xml</em>, which should 
+  be created in the <em>src/schema</em> directory 
+  and contain the following:
 </p>
 
 <source><![CDATA[
 <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
 <!DOCTYPE database SYSTEM
- "http://db.apache.org/torque/dtd/database_3_1.dtd">
+ "http://db.apache.org/torque/dtd/database_3_2.dtd">
 
 <database
   name="bookstore"
@@ -244,24 +242,12 @@
 ]]></source>
 
 <p>
-  Edit <em>project-schema.xml</em> to reflect the
-  above database schema.  If you would rather create
-  your own schema file, be sure the filename ends in
-  &#145;-schema.xml&#146;, and delete
-  <em>project-schema.xml</em> because Torque will
-  generate an object model for that file as well.  Do
-  not delete <em>id-table-schema.xml</em> if you plan
-  on using Torque's IDBroker service, which is used in
-  this tutorial.
-</p>
-
-<p>
   There are several items of importance to note.  The
   <em>database</em> element's <em>name</em> attribute
   must be the same as the database name specified by
   the <em>databaseUrl</em> property in
   <em>project.properties</em>; likewise, the run-time
-  properties (described in the next section) should
+  properties (described in step 4) should
   also reflect this value.  Failure to do so will
   prevent Torque from creating your database tables
   (if instructed to do so) or prevent your object
@@ -307,8 +293,7 @@
     <td>none</td>
     <td>
       Instructs Torque to not generate IDs.  This
-      can be useful in some situations (an example
-      is described below).
+      can be useful in some situations.
     </td>
   </tr>
 </table>
@@ -324,52 +309,6 @@
 </p>
 
 <p>
-  One common reason that a table might override the
-  <em>defaultIdMethod</em> is when a table is composed
-  only of foreign keys (i.e. a &#145;junction
-  entity&#146; in database-speak).  In this case, all
-  columns should be defined as primary keys because
-  they are all needed to declare a row as unique.
-  However, Torque should not generate primary key IDs
-  for objects in this table because the objects that
-  compose the table already have primary key IDs.
-  Thus, the <em>idMethod</em> attribute of the table
-  must be set to <em>none</em>.  For example, if the
-  <em>book</em> table defined above did not have any
-  additional attributes other than a
-  <em>publisher_id</em> and <em>author_id</em>, the
-  schema for the <em>book</em> table should be defined
-  as:
-</p>
-
-<source><![CDATA[
-  <table name="book" idMethod="none" description="Book Table">
-    <column
-      name="publisher_id"
-      required="true"
-      primaryKey="true"
-      type="INTEGER"
-      description="Foreign Key Publisher"/>
-    <column
-      name="author_id"
-      required="true"
-      primaryKey="true"
-      type="INTEGER"
-      description="Foreign Key Author"/>
-    <foreign-key foreignTable="publisher">
-      <reference
-        local="publisher_id"
-        foreign="publisher_id"/>
-    </foreign-key>
-    <foreign-key foreignTable="author">
-      <reference
-        local="author_id"
-        foreign="author_id"/>
-    </foreign-key>
-  </table>
-]]></source>
-
-<p>
   Another common mistake is to forget that XML is
   <b>case-sensitive</b>.  All of the elements and
   attributes must be specified according to the
@@ -381,20 +320,16 @@
 </p>
 
 <p>
-  Finally, you must also edit (or add if its not
-  present) the <em>name</em> attribute to the
-  <em>database</em> element in
-  <em>id-table-schema.xml</em>.  The value should be
-  identical to the value in your database schema file.
-  This will instruct Torque to create
-  <em>id-table</em> in the same database as your
-  schema.  Below is the file used in this example:
+  To initialize the IDBroker service, create a file
+  called <em>id-table-schema.xml</em> in the 
+  <em>src/schema</em> subdirectory of your project's
+  base directory. It should have the following contents:
 </p>
 
 <source><![CDATA[
 <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
 <!DOCTYPE database SYSTEM
- "http://db.apache.org/torque/dtd/database_3_1.dtd">
+ "http://db.apache.org/torque/dtd/database_3_2.dtd">
 
 <database name="bookstore">
   <table name="ID_TABLE" idMethod="idbroker">
@@ -422,257 +357,30 @@
 ]]></source>
 
 <p>
-  Torque uses the database schema files to generate
-  your object model and Java classes to support it.
-  In addition, Torque generates SQL that can be used
-  to create your databases and tables from these
-  schemas.  For additional information on
-  the XML elements and attributes, please refer to the
-  <a href="../generator/schema-reference.html">
-  Torque Schema Reference</a>.
-</p>
-
-</section>
-
-<section name="Torque Run-Time Properties">
-
-<p>
-  The last step in the configuration of Torque are the
-  Torque run-time properties.  As the name suggests,
-  these properties are used when your application is
-  executing the object model code generated by Torque.
-  The run-time properties control logging and database
-  parameters such as drivers, usernames, and
-  passwords.  These properties can be saved in any
-  file because your application must explicitly
-  initialize Torque (as you'll see later in this
-  tutorial).
-</p>
-
-<p>
-  The runtime distribution archive includes an Ant build file that can be used 
-  to generate your Torque runtime configuration.  When you unpack the archive 
-  you will see the following:
-</p>
-
-<source><![CDATA[
-torque/
-    database/         <--- Contains database specific property files used 
-                           during the generating of runtime configuration
-                           property files.
-    docs/             <--- Contains a copy of the Torque documentation, 
-                           including the API JavaDocs.
-    lib/              <--- Contains the jar files required by the Torque 
-                           runtime.
-    master/build.xml  <--- The Ant build file for regenerating 
-                           Torque.properties.
-    master/default.properties
-                      <--- The properties that will be used when regenerating 
-                           Torque.properties.
-    master/Torque.master
-                      <--- The unprocessed property file template.
-    componentConfiguration.xml
-    roleConfiguration.xml
-                      <--- These are included to assist with using Torque as 
-                           component in a container (e.g. one of the Avalon
-                           containers).
-    LICENSE.txt       <--- The License for the Torque runtime.
-    README.txt        <--- Helpful information.
-    Torque.properties <--- A sample generated runtime configuration file - this
-                           will be replaced when you regenerate the runtime 
-                           configuration.
-]]></source>
-
-<p>
-  To generate Torque.properties for your project you can edit the input 
-  properties in <code>master/default.properties</code> and then run 
-  <code>ant</code> to regenerate <code>Torque.properties</code>.  Note that 
-  the sample and generated <code>Torque.properties</code> file contains 
-  a good amount of information regarding the available Torque run-time
-  properties.
+  Note that again, the <em>name</em> attribute to the
+  <em>database</em> element has the same value as in the
+  <em>project-schema.xml</em>.  
 </p>
 
 <p>
-  For simplicity, we'll just create our own <code>Torque.propereties</code>
-  file (again, this tutorial will guide you through the bare minimum to
-  get your application up and running).  Create a new file
-  called <em>Torque.properties</em> in the top-level directory of your
-  project and add the following lines to it:
+  For additional information on
+  the XML elements and attributes, please refer to the
+  <a href="../generator/schema-reference.html">
+  Torque Schema Reference</a>.
 </p>
 
-<source><![CDATA[
-torque.database.default = bookstore
-torque.database.bookstore.adapter = mysql
-
-# Using commons-dbcp 
-torque.dsfactory.bookstore.factory = org.apache.torque.dsfactory.SharedPoolDataSourceFactory
-torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
-torque.dsfactory.bookstore.connection.url = jdbc:mysql://localhost:3306/bookstore
-torque.dsfactory.bookstore.connection.user = user
-torque.dsfactory.bookstore.connection.password = password
-  ]]></source>
-
-  <p>
-    We are using the commons-dbcp for our connection pool - see 
-    <a href="../configuration-howto.html">Pool-config Howto</a>
-    details of the available <code>DataSource</code> factories.
-  </p>
-
-  <table>
-    <tr> <th>Property</th> <th>Description</th> </tr>
-    <tr>
-      <td>torque.database.default</td>
-      <td>
-        Torque has the ability to use multiple
-        databases.  This property specifies which
-        database is to be used as the default.
-      </td>
-    </tr>
-    <tr>
-      <td>torque.database.XXX.adapter</td>
-      <td>
-        Torque has the ability to deal with multiple database systems.
-        This property specifies the database adapter to use.
-      </td>
-    </tr>
-    <tr>
-      <td>torque.dsfactory.XXX.factory</td>
-      <td>
-        The factory class that will be used to provide database connections.
-      </td>
-    </tr>
-    <tr>
-      <td>torque.dsfactory.XXX.connection.driver</td>
-      <td>
-        The JDBC database driver to use when
-        connecting to your database.
-      </td>
-    </tr>
-    <tr>
-      <td>torque.database.XXX.connection.url</td>
-      <td>
-        The URL that will be used to access your
-        database.  Torque's generated object model
-        will perform all database operations using
-        this URL.  This value should reflect the
-        database name specified in your database
-        schema file (see the <em>database</em>
-        element's <em>name</em> attribute).
-      </td>
-    </tr>
-    <tr>
-      <td>torque.database.XXX.connection.username</td>
-      <td>
-        The username that has sufficient privileges
-        to access your database.  This user does not
-        require privileges to create and drop
-        tables, unlike the username that was
-        specified in <em>project.properties</em>.
-      </td>
-    </tr>
-    <tr>
-      <td>torque.database.XXX.connection.password</td>
-      <td>
-        The password for the specified username.
-      </td>
-    </tr>
-  </table>
-
-  <p>
-    It is worth re-iterating that these run-time
-    properties are not used by Torque when generating
-    your object model and creating your database.  They
-    are used only by the application utilizing the
-    Torque-generated object model classes at run-time.
-  </p>
-
-  <subsection name="Logging configuration">
-
-  <p>
-    To have any logging messages sent to the console add the following
-    to a file named <code>log4j.properties</code> and place this in
-    your classpath (putting it in your <code>target/classes</code>
-    will do the trick).
-  </p>
-
-<source><![CDATA[
-log4j.rootCategory = INFO, default
-log4j.appender.default = org.apache.log4j.ConsoleAppender
-log4j.appender.default.layout = org.apache.log4j.SimpleLayout
-]]></source>
-
-  <table>
-    <tr> <th>Property</th> <th>Description</th> </tr>
-    <tr>
-      <td>log4j.rootCategory</td>
-      <td>
-        Torque uses 
-        <a href="http://jakarta.apache.org/commons/logging/">Commons 
-        Logging</a>, which in turn by default uses 
-        <a href="http://logging.apache.org/log4j/">Log4J</a>
-        for a logging.  This parameter configures
-        the Log4J system to log all messages but debug messages (use
-        <code>DEBUG</code> rather than <code>INFO</code> to have get
-        the debug messages too).
-      </td>
-    </tr>
-    <tr>
-      <td>log4j.appender.default</td>
-      <td>
-        Configures Log4J to send all logging messages to the console.
-        Log4J can just as easily send all logging to a file or a
-        syslog server.
-      </td>
-    </tr>
-    <tr>
-      <td>log4j.appender.default.layout</td>
-      <td>
-        Log4J logs messages using a layout.  Layouts
-        can be very simple or complicated.  This
-        tutorial uses the very rudimentary
-        SimpleLayout.
-      </td>
-    </tr>
-  </table>
-
-  </subsection>
-
 </section>
 
-<section name="Torque runtime and dependant libraries">
-
-  <p>
-    In order to be able to compile and use the generated class files it is 
-    necessary to include the Torque runtime jar file and jar files for all of
-    the necessary dependencies in the classpath of your project.  The necessary 
-    jars are included in the <code>torque/lib</code> directory of the Torque
-    runtime.  If you are using Maven to build your project it may be easiest to
-    copy the necessary <a href="../dependencies.html">dependencies</a> from the 
-    <a href="http://cvs.apache.org/viewcvs.cgi/db-torque/project.xml?only_with_tag=TORQUE_3_1_BRANCH">Torque
-    runtime POM</a>.
-    Do not forget to include the jar containing your database driver
-    into the classpath.
-  </p>
-
-  <p>
-    <b>
-      Note: There is no need to include the torque-gen jar file in your project
-      classpath, including it may adversly affect the logging configuration of 
-      your application.
-    </b>
-  </p>
-
-</section>
 
 <section name="Where to next">
 
   <p>
-    That completes the configuration of Torque.  You are now
-    ready to start building your object model and creating
-    your database.
+    That completes the configuration of the Torque generator.  
+    You are now ready to start building your object model 
+    and creating your database.
   </p>
   <p>
-    Next we will look <a href="step3.html">Invoking Torque</a>.
+    Next we will look <a href="step3.html">Invoking the Torque generator</a>.
   </p>
 
 </section>

Modified: db/torque/trunk/xdocs/tutorial/step3.xml
URL: http://svn.apache.org/viewcvs/db/torque/trunk/xdocs/tutorial/step3.xml?rev=232619&r1=232618&r2=232619&view=diff
==============================================================================
--- db/torque/trunk/xdocs/tutorial/step3.xml (original)
+++ db/torque/trunk/xdocs/tutorial/step3.xml Sun Aug 14 09:24:18 2005
@@ -2,16 +2,17 @@
 
 <document>
   <properties>
-    <title>Torque Tutorial - Step 3: Invoking Torque</title>
+    <title>Torque Tutorial - Step 3: Invoking the Torque generator</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 Torque">
+<section name="Step 3: Invoking the Torque generator">
 
 <p>
-  With the configuration of Torque completed, you can now
+  With the configuration of the Torque generator completed, you can now
   generate the object model to support your database, and
   optionally create your database and all of its
   associated tables.  As mentioned earlier in this
@@ -64,31 +65,25 @@
 ]]></source>
 
 <p>
-  Upon a successful build, indicated by the
-  &#145;BUILD SUCCESSFUL&#146; message, you will find
-  the generated class files within the <code>src</code>
-  directory of your project (this is the default, you can 
-  alter where the files are generated to using the 
-  <code>torque.home</code>, <code>torque.output.dir</code>
-  and/or <code>torque.java.dir</code>
-  properties in your <code>project.properties</code> file - see
-  the <a href="../generator/properties-reference.html">properties 
-  reference</a> for more detail).
+  A successful build will be indicated by the
+  &#145;BUILD SUCCESSFUL&#146; message.
 </p>
 
 <p>
-  The Java classes are located in the <em>java</em>
-  directory and will be in a directory hierarchy
-  matching that of the <code>torque.targetPackage</code> you
+  The generated Java classes are located in the 
+  <em>src/java</em> directory and will be in a 
+  directory hierarchy matching that of the 
+  <code>torque.targetPackage</code> you
   specified in <em>project.properties</em>.
   These are the files that will be compiled into your
   object model classes.
 </p>
 
 <p>
-  The SQL files are located in the <em>sql</em>
-  directory.  For each database schema in your
-  <em>schema</em> directory, there will be a
+  The generated SQL files are located in the 
+  <em>target/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
@@ -97,6 +92,16 @@
 </p>
 
 <p>
+  To change the directory where the classes are generated,
+  use the properties <code>torque.home</code>, 
+  <code>torque.output.dir</code>
+  and/or <code>torque.java.dir</code>
+  in your <code>project.properties</code> file - see
+  the <a href="../generator/properties-reference.html">properties 
+  reference</a> for more detail).
+</p>
+
+<p>
   If you encounter errors while building, it is more
   than likely a formatting error of your database
   schema file.  Check the format of the file and make
@@ -117,12 +122,110 @@
   defined in <em>project.properties</em>) is in your
   classpath so that Torque can connect to your
   database and execute the generated SQL commands.
-  The easiest way to accomplish that is to add your
-  database driver as a dependency in your project 
-  (add it to your <code>project.xml</code>.
+  The easiest way to accomplish this is to add the 
+  database driver jar to your local maven repository,
+  and specify it as a dependency in your project.
+  This is done as follows:
+</p>
+
+<subsection name="Adding the driver to the maven repository">
+
+<p>
+  For licensing reasons, most database drivers cannot 
+  be downloaded automatically by maven. Therefore,
+  you have to add the driver manually to your local maven 
+  repository. The local maven repository
+  is located by default in the directory 
+  <em>%HOMEDRIVE%%HOMEPATH%\.maven\repository</em>
+  in windows, and <em>$HOME/.maven/repository</em>
+  in linux/unix. Change into that direcory and
+  create a subdirectory <em>${groupId}/jars</em>,
+  where <em>${groupId}</em> is typically set to
+  the name of the database (for example, use
+  <em>mysql/jars</em> for mysql).
+  Then, download the database driver, and copy the 
+  driver jar to the subdirectory you just created.
+</p>
+
+</subsection>
+
+<subsection name="Specifying the driver dependency">
+
+<p>
+  The dependencies of a project are specified 
+  in a file named <em>project.xml</em> in the 
+  top level directory of your project.
+  (This is not the only use of this file,
+  see the 
+  <a href="http://maven.apache.org/start/ten-minute-test.html">
+  maven getting started guide</a>
+  and the 
+  <a href="http://maven.apache.org/reference/project-descriptor.html">
+  Maven Project descriptor reference</a> for more
+  information.)
+</p>
+
+<p>
+  If you did not create a <em>project.xml</em> file yet,
+  create it in the top level directory of your project 
+  and fill it using the following template. (If you
+  already have a <em>project.xml</em>, 
+  just add the dependency.)
+</p>
+
+<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project>
+  <pomVersion>3</pomVersion>
+  <groupId>torque</groupId>
+  <id>torque-tutorial</id>
+  <name>Torque</name>
+  <currentVersion>3.2-rc2-dev</currentVersion>
+
+  <dependencies>
+    <dependency>
+      <artifactId>${artifactId}</artifactId>
+      <groupId>${groupId}</groupId>
+      <version>${version}</version>
+    </dependency>
+  </dependencies>
+</project>
+]]></source>
+
+<p>
+  Replace the variables ${driverJarName}, 
+  ${databaseName}, and ${driverVersion} by the values 
+  needed to locate the driver jar. These variable 
+  must be chosen such that using the path
+  <em>${repo}/${groupId}/${type}s/${artifactId}-${version}.${type}</em> 
+  points to the driver jar you copied into the
+  local maven repository.
+  Here, <em>${repo}</em> is the path to the 
+  local maven repository, ${type} is set to 
+  <code>jar</code> by default, and the other variables 
+  are set in the <em>project.xml</em>.
+  If the name of the driver jar cannot be expressed as
+  <em>${artifactId}-${version}.${type}</em>, rename 
+  the driver jar in yor local maven repository.
 </p>
 
 <p>
+  For example, if the downloaded driver was put into the local
+  repository as 
+  <em>mysql/jars/mysql-connector-java-3.1.6-bin.jar</em>,
+  <code>${artifactId}</code> would be set to
+  <code>mysql-connector-java</code>,
+  <code>${groupId}</code> would be set to
+  <code>mysql</code>,
+  and <code>${version}</code> would be set to
+  <code>3.1.6-bin</code> in the <em>project.xml</em>.
+</p>
+
+</subsection>
+
+<subsection name="Creating the database">
+
+<p>
   <b>
     Note: Torque will <em>drop</em> the database and
     tables that it is about to create if they exist!
@@ -142,13 +245,28 @@
 
 <p>
   Note that creating the database might not work 
-  for some databases or the database user configured
-  in the generator properties might not have the 
-  necessary permissions to do so. If you encounter 
-  problems in this step, skip it and create the 
-  database manually.
+  for some databases at all (e.g. oracle).
+  Also, for other databases (e.g. mysql), 
+  the database user must be database administrator 
+  to be able to create the database, and often
+  (e.g. mysql, postgresql), one must connect to a
+  database which is different from the database
+  which one wants to create (this is why there are 
+  different properties 
+  <code>torque.database.createUrl</code>
+  and <code>torque.database.buildUrl</code>
+  in the <em>project.properties</em> 
+  for creating the database and the tables,
+  respectively).<br /> 
+  If you encounter problems in this step, 
+  you might want to skip it 
+  and create the database manually.
 </p>
 
+</subsection>
+
+<subsection name="Creating the tables">
+
 <p>
   To create your tables, type the following commands in
   the top-level directory of your project:
@@ -184,22 +302,24 @@
   of your <em>project.properties</em>.  Another common
   problem is that the user specified in the
   <em>project.properties</em> does not have sufficient
-  privilege to create databases and tables.  In either
+  privilege to create tables.  In either
   case, refer to the section above that explains the
   <em>project.properties</em> file.
 </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 now ready to
+    classes and created your database, you are ready to
     build your first Torque application.
   </p>
   <p>
-    Next we will look <a href="step4.html">Writing a Sample Application</a>.
+    Next we will look <a href="step4.html">Configuring the Torque Runtime</a>.
   </p>
 
 </section>

Modified: db/torque/trunk/xdocs/tutorial/step4.xml
URL: http://svn.apache.org/viewcvs/db/torque/trunk/xdocs/tutorial/step4.xml?rev=232619&r1=232618&r2=232619&view=diff
==============================================================================
--- db/torque/trunk/xdocs/tutorial/step4.xml (original)
+++ db/torque/trunk/xdocs/tutorial/step4.xml Sun Aug 14 09:24:18 2005
@@ -2,927 +2,296 @@
 
 <document>
   <properties>
-    <title>Torque Tutorial - Step 4 - Writing a Sample Application</title>
+    <title>Torque Tutorial - Step 4: Configuring the Torque Runtime</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 4: Writing a Sample Application">
+<section name="Configuring the Torque Runtime">
 
 <p>
-Congratulations, you have finally reached the fun the
-part of this tutorial.  This is where you'll discover
-the power of Torque.  Be warned, you'll never want to
-write another SQL statement ever again!
-</p>
-
-<p>
-As mentioned earlier, when Torque created your object
-model, it created four Java classes for each table
-defined in your database schema.  For example, the
-<em>book</em> table, defined in the database schema
-presented earlier, will result in the following classes:
-<em>Book</em>, <em>BookPeer</em>, <em>BaseBook</em>, and
-<em>BaseBookPeer</em>.
-</p>
-
-<p>
-<em>Book</em> and <em>BookPeer</em> are subclasses of
-<em>BaseBook</em> and <em>BaseBookPeer</em>
-respectively.  The two Base classes (<em>BaseBook</em>
-and <em>BaseBookPeer</em>) contain Torque-generated
-logic and should <b>not</b> be modified because Torque
-will overwrite your changes if you happen to generate
-your object model again.  Any
-business logic that you might want to add should be
-placed in the <em>Book</em> and <em>BookPeer</em>
-classes.  This is covered later in the tutorial.
-</p>
-
-<p>
-You might be asking yourself, what is the difference
-between the Peer classes (<em>BookPeer</em> and
-<em>BaseBookPeer</em>) and their counterparts
-(<em>Book</em> and <em>BaseBook</em>), also known as
-Data Objects?  The Peer classes &#147;wrap&#148; their
-associated database tables and provide static methods to
-manipulate those tables such as <em>doSelect</em>,
-<em>doInsert</em>, and <em>doUpdate</em>.  Data Objects,
-on the other hand, &#147;wrap&#148; individual rows
-within those tables and provide getters/mutators for each
-column defined in those tables as well as the convenient
-<em>save</em> method.  Both Peer and Data Objects have a
-one-to-one mapping to a table defined in your database
-schema.  For a more in-depth discussion on Peers and
-Data Objects, refer to the
-<a href="../peers-howto.html#Peer%20Classes">Peers HOWTO</a>.
-An example of adding logic to both the Peer and Data
-Objects is presented later in the tutorial.
-</p>
-
-<p>
-Now that we've covered the basics of the object model
-that Torque generated for you, the rest of this section
-describes the Torque-way of doing database inserts,
-selects, updates, and deletes illustrated with small
-segments of code.  These segments of code are part of a
-sample application that is presented in full after a
-brief discussion on extending the object model classes.
-Finally, instructions on how to compile and run the
-application are detailed.
-</p>
-
-</section>
-
-<section name="Inserting Rows">
-
-<p>
-  Inserting rows into your tables is easy with Torque.
-  Simply instantiate a new Data Object of the
-  appropriate class, set its properties using the
-  mutators named after the table's columns,
-  then invoke the Data Object's <em>save</em> method.
-  Note: It is not necessary to set the object's
-  primary key ID because Torque will do this for you
-  automatically unless you've specified otherwise (see
-  the Database Schema Configuration section above).
-</p>
-
-<p>
-  For example, to insert a new row in the
-  <em>author</em> table (as defined in this tutorial's
-  database schema): instantiate a new <em>Author</em>
-  object, invoke the object's <em>setFirstName</em>
-  and <em>setLastName</em> methods with appropriate
-  values, then call the <em>save</em> method.  That's
-  it.  The following is from the sample application:
-</p>
-
-<source><![CDATA[
-Publisher addison = new Publisher();
-addison.setName("Addison Wesley Professional");
-addison.save();
-
-Author bloch = new Author();
-bloch.setFirstName("Joshua");
-bloch.setLastName("Bloch");
-bloch.save();
-]]></source>
-
-<p>
-  It is also possible to insert a row using the Peer
-  class directly instead of invoking the <em>save</em>
-  method of your Data Object.  Recall, the Peer class
-  provides static methods to perform operations on a
-  table.  One of these operations is the ability to
-  insert rows via the <em>doInsert</em> method.  The
-  Data Object's <em>save</em> method actually calls
-  <em>doInsert</em> for you (or <em>doUpdate</em> if
-  the object is not new and must be updated).
-</p>
-
-<p>
-  For example, you can use
-  <em>AuthorPeer.doInsert</em> as an alternative
-  method to insert a new row in the <em>author</em>
-  table.  The following is from the sample
-  application:
-</p>
-
-<source><![CDATA[
-Author stevens = new Author();
-stevens.setFirstName("W.");
-stevens.setLastName("Stevens");
-AuthorPeer.doInsert(stevens);
-]]></source>
-
-<p>
-  It should also be noted for completeness that
-  <em>doInsert</em> can be passed a <em>Criteria</em>
-  object (discussed in the next section) instead of a
-  Data Object (see the Javadoc for details).  However,
-  the most common method for the insertion of rows in
-  a table is via the <em>save</em> method of the Data
-  Object rather than directly using the Peer's
-  <em>doInsert</em> method.
-</p>
-
-<p>
-  Inserting a row in a table that contains a foreign
-  key is also simple.  As a convenience, Torque creates
-  a mutator for the specific Data Object class
-  that represents the foreign-key in the object model.
-  The name of this method is <em>setTable</em> where
-  <em>Table</em> is the name of the foreign-key's
-  table (as defined in the database schema).  Upon
-  calling this method with a reference to the
-  appropriate Data Object, Torque will automatically
-  extract and insert the foreign-key for you.
-</p>
-
-<p>
-  For example, the <em>book</em> table (as defined in
-  the database schema) contains two foreign-keys:
-  <em>author_id</em> and <em>publisher_id</em>.  To
-  insert a row in this table, follow the same
-  procedure as above, but instead of explicitly
-  setting the foreign-keys (via <em>setAuthorId</em>
-  and <em>setPublisherId</em>), use <em>setAuthor</em>
-  and <em>setPublisher</em> and pass references to an
-  <em>Author</em> and <em>Publisher</em> Data Object.
-  Both methods are illustrated in the following code
-  which builds upon the earlier objects that were
-  created:
-</p>
-
-<source><![CDATA[
-/*
- * Using the convenience methods to handle
- * the foreign keys.
- */
-Book effective = new Book();
-effective.setTitle("Effective Java");
-effective.setISBN("0-618-12902-2");
-effective.setPublisher(addison);
-effective.setAuthor(bloch);
-effective.save();
-
-/*
- * Inserting the foreign-keys manually.
- */
-Book tcpip = new Book();
-tcpip.setTitle("TCP/IP Illustrated, Volume 1");
-tcpip.setISBN("0-201-63346-9");
-tcpip.setPublisherId(addison.getPublisherId());
-tcpip.setAuthorId(stevens.getAuthorId());
-tcpip.save();
-]]></source>
-
-<p>
-  As you can see, inserting rows into your database is
-  very easy to do with your Torque object model.
+  Before we can start to write a Torque application, we have to 
+  configure the runtime environment:
+  <ul>
+    <li>
+      We have to make sure that the generated 
+      object model classes have access to the Torque 
+      runtime and associated libraries.
+    </li>
+    <li>
+      The Torque runtime needs a configuration file
+      in order to retrieve the data which is necessary 
+      to connect to the database. 
+    </li>
+  </ul>
+  These two steps will be covered in the following sections.
 </p>
 
 </section>
 
-<section name="Selecting Rows">
-
-<p>
-  Selecting rows from your database is just as easy as
-  inserting rows.  The Peer class associated with a
-  table defines a static method called
-  <em>doSelect</em> which is used to pull data out of
-  the table.  The argument to <em>doSelect</em> is a
-  <em>Criteria</em> object.  It is this object that
-  specifies the criteria to be used when selecting
-  data from the database.  As a result of the query,
-  <em>doSelect</em> returns a <code>List</code> of Data Objects
-  representing the rows of data selected.  To use
-  these Data Objects in your application, you must
-  cast them to the appropriate type in your object
-  model.
-</p>
-
-<p>
-  For example, to select all of the rows from the
-  <em>book</em> table that were inserted in the
-  previous section, you must first create a
-  <em>Criteria</em> object.  Because we want to select
-  everything from the table, no criteria will be
-  specified (i.e. no WHERE clause in the underlying
-  SELECT statement).  To perform the query, the empty
-  <em>Criteria</em> object is passed to
-  <em>BookPeer.doSelect</em>, as illustrated below:
-</p>
-
-<source><![CDATA[
-Criteria crit = new Criteria();
-List books = BookPeer.doSelect(crit);
-]]></source>
-
-<p>
-  The results are stored in a <code>List</code> which can then be
-  iterated over to access the individual <em>Book</em>
-  objects retrieved from the table.  The following
-  code prints the <em>Book</em> to standard output (a
-  better approach is presented later):
-</p>
-
-<source><![CDATA[
-for (Iterator i = book.iterator(); i.hasNext();)
-{
-    Book book = (Book) i.next();
-    System.out.println("Title: " + book.getTitle() + "\n");
-    System.out.println("ISBN:  " + book.getISBN() + "\n");
-    System.out.println("Publisher: " +
-            book.getPublisher().getName() + "\n");
-    System.out.println("Author: " +
-            book.getAuthor().getLastName() + ", " +
-            book.getAuthor().getFirstName() + "\n");
-}
-]]></source>
-
-<p>
-  In the above example, you may have noticed that by
-  calling <em>getAuthor</em> and
-  <em>getPublisher</em>, the object model
-  automatically retrieved the <em>Author</em> and
-  <em>Publisher</em> Data Objects for you.  This
-  results in an additional behind-the-scenes SQL query
-  for each table.  Although <em>getAuthor</em> is
-  called twice, only a single SQL query occurs because
-  all of the <em>Author</em> columns are selected in
-  behind-the-scenes query.
-</p>
-
-<table>
-  <tr> <th>The Gory Details (not for the faint)</th></tr>
-  <tr>
-    <td>
-      Even still, this is not the most efficient
-      method to query and populate Data Objects
-      for an entire table with foreign-keys (one
-      query for the table, then two additional
-      queries for each row).  A single query using
-      a join would be much more efficient.  As a
-      convenience, Torque generates the following
-      <em>protected</em> methods in the BasePeer
-      classes whose tables contain foreign-keys:
-      <em>doSelectJoinTable</em> where
-      <em>Table</em> is the name of the
-      foreign-key table.  This method efficiently
-      queries the database (using a single join
-      query) and automatically populates all of
-      the Data Objects.  This eliminates the
-      additional query that is issued when
-      retrieving the foreign-key Data Object.  For
-      example, <em>doSelectJoinAuthor</em> and
-      <em>doSelectJoinPublisher</em> were
-      generated in the <em>BaseBookPeer</em> class
-      that <em>BookPeer</em> extends.  As a
-      reminder, to use these convenience methods,
-      you must provide <em>public</em> members to
-      <em>BookPeer</em> for clients because they
-      are <em>protected</em> in
-      <em>BaseBookPeer</em>.  Unfortunately,
-      Torque does not generate a
-      <em>doSelectJoinAll</em> or
-      <em>doSelectJoinAuthorPublisher</em> method.
-      Those are left to the reader as an exercise
-      to implement in the <em>BookPeer</em> class.
-    </td>
-  </tr>
-</table>
-
+<section name="Setting up the classpath">  
+  
 <p>
-  To select a specific <em>Book</em> from the table,
-  create a <em>Criteria</em> object (or just reuse the
-  previous one) and use the <em>add</em> method to
-  specify some criteria.  Specifying criteria is
-  simply a matter of choosing a column (defined as
-  static constants in your Peer class) and some value
-  you want to match.  Thus, selecting a book with the
-  following ISBN, &#145;0-618-12902-2&#146;, is as
-  simple as:
-</p>
-
-<source><![CDATA[
-Criteria crit = new Criteria();
-crit.add(BookPeer.ISBN, "0-618-12902-2");
-List books = BookPeer.doSelect(crit);
-]]></source>
-
-<p>
-  This section has only skimmed the surface of
-  <em>Criteria</em> objects.  <em>Criteria</em> can be
-  used to specify very simple to very complex queries.
-  For a much more in-depth discussion of
-  <em>Criteria</em>, please refer to the
-  <a href="../criteria-howto.html">Criteria HOWTO</a>.
+  The libraries which the generated classes depend on 
+  are specified in the file <em>project.xml</em>
+  in the top level directory of the project.
+  You already created this file in step 3 of the 
+  tutorial; now it needs to be extended a bit.  
+  Assuming that you use JDK 1.4+, you need to add
+  the following entries to the &lt;dependencies&gt;
+  section of your <em>project.xml</em>
+</p>
+<source><![CDATA[
+    <dependency>
+      <artifactId>torque</artifactId>
+      <groupId>torque</groupId>
+      <version>3.2-rc1</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>avalon-framework</artifactId>
+      <groupId>avalon-framework</groupId>
+      <version>4.1.4</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>commons-beanutils</artifactId>
+      <groupId>commons-beanutils</groupId>
+      <version>1.7.0</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>commons-collections</artifactId>
+      <groupId>commons-collections</groupId>
+      <version>3.1</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>commons-configuration</artifactId>
+      <groupId>commons-configuration</groupId>
+      <version>1.1</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>commons-dbcp</artifactId>
+      <groupId>commons-dbcp</groupId>
+      <version>1.2.1</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>commons-lang</artifactId>
+      <groupId>commons-lang</groupId>
+      <version>2.1</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>commons-logging</artifactId>
+      <groupId>commons-logging</groupId>
+      <version>1.0.4</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>commons-pool</artifactId>
+      <groupId>commons-pool</groupId>
+      <version>1.2</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>jcs</artifactId>
+      <groupId>jcs</groupId>
+      <version>20030822.182132</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>village</artifactId>
+      <groupId>village</groupId>
+      <version>2.0-dev-20030825</version>
+    </dependency>
+    
+    <dependency>
+      <artifactId>xercesImpl</artifactId>
+      <groupId>xerces</groupId>
+      <version>2.6.2</version>
+    </dependency>
+
+    <dependency>
+      <artifactId>xml-apis</artifactId>
+      <groupId>xml-apis</groupId>
+      <version>2.0.2</version>
+    </dependency>
+    
+]]></source>
+
+<p>
+  You need not download any of these libraries - 
+  Maven will download them automatically when you 
+  build your project.
+</p>
+
+<p>
+  <b>
+    Note: There is no need to include the torque-gen jar file in your project
+    classpath, including it may adversly affect the logging configuration of 
+    your application.
+  </b>
 </p>
 
 </section>
 
-<section name="Updating Rows">
-
-<p>
-  Updating a row in a table is only a matter of
-  changing one or more properties of the Data Object
-  that represents the row by invoking one or more
-  mutators and then calling its <em>save</em> method.
-  When a mutator is called, the Data Object sets an
-  internal flag to indicate that its been modified.
-  This flag is checked when <em>save</em> is invoked
-  to determine if the Peer's <em>doInsert</em> or
-  <em>doUpdate</em> is called to perform the database
-  operation.
-</p>
+<section name="Torque Run-Time Properties">
 
 <p>
-  For example, changing the author of the
-  &#145;Effective Java&#146; book created earlier is
-  as simple as:
+  The second step in the configuration of the 
+  Torque Runtime are the
+  Torque run-time properties.  As the name suggests,
+  these properties are used when your application is
+  executing the object model code generated by Torque.
+  The run-time properties control database
+  parameters such as drivers, usernames, and
+  passwords.  These properties can be saved in any
+  file because your application must explicitly
+  initialize Torque (as you'll see later in this
+  tutorial).
 </p>
 
-<source><![CDATA[
-effective.setAuthor(stevens);
-effective.save();
-]]></source>
-
 <p>
-  Alternatively, instead of calling the Data Object's
-  <em>save</em> method, the Peer's <em>doUpdate</em>
-  method may be called directly with a Data Object
-  that has been modified as the argument.  This is
-  illustrated in the following fragment of code that
-  changes the author of the &#145;TCP/IP
-  Illustrated&#146; book:
+  We will save our runtime properties in the 
+  a file called <em>torque.properties</em>.
+  Create a subdirectory src/conf in the
+  top-level directory of your project, and create
+  a new file called <em>torque.properties</em> 
+  in it. Add the following lines to this file:
 </p>
 
 <source><![CDATA[
-tcpip.setAuthor(bloch);
-BookPeer.doUpdate(tcpip);
-]]></source>
+torque.database.default = bookstore
+torque.database.bookstore.adapter = mysql
 
-<p>
-  Again, for completeness, <em>doUpdate</em> could
-  have been passed a <em>Criteria</em> object to
-  update a row (see the Javadoc for details).  However,
-  the most common method to update rows in a table is
-  via the Data Object's <em>save</em> method rather
-  than directly using the Peer's <em>doUpdate</em>
-  method.
-</p>
-
-</section>
-
-<section name="Deleting Rows">
-
-<p>
-  Deleting rows from a table is easy as well.  The
-  Peer class defines a static method <em>doDelete</em>
-  which can be used for this purpose.  Similar to the
-  other Peer methods, <em>doDelete</em> may be passed
-  a <em>Criteria</em> object or a Data Object to
-  specify which row or rows to delete.  It should be
-  noted that there is no corresponding method in the
-  Data Object to delete a row.
-</p>
-
-<p>
-  For example, the following code deletes all of the
-  rows from the three tables that were inserted during
-  the course of this tutorial using both forms of
-  <em>doDelete</em>.  First, the books are deleted by
-  specifying <em>Criteria</em>, then the authors and
-  publishers are deleted by passing the Data Objects
-  directly to <em>doDelete</em>.
-</p>
-
-<source><![CDATA[
-crit = new Criteria();
-crit.add(BookPeer.ISBN, "0-618-12902-2");
-BookPeer.doDelete(crit);
-
-crit = new Criteria();
-crit.add(BookPeer.ISBN, "0-201-63346-9");
-crit.add(BookPeer.TITLE, "TCP/IP Illustrated, Volume 1");
-BookPeer.doDelete(crit);
-
-AuthorPeer.doDelete(bloch);
-AuthorPeer.doDelete(stevens);
-PublisherPeer.doDelete(addison);
-]]></source>
-
-<p>
-  Note: Deleting a row from a table that contains
-  foreign-keys does not automatically delete the
-  foreign-keys from their tables.  If you want to
-  delete the foreign-keys, you must do so explicitly
-  as shown in the above example.  I.e.,  deleting the
-  books from the <em>book</em> table does not
-  automatically delete the corresponding rows in the
-  <em>author</em> and <em>publisher</em> tables.
-
-</p>
-
-<table>
-  <tr> <th>The Gory Details (not for the faint)</th></tr>
-  <tr>
-    <td>
-      It should also be noted that
-      <em>doDelete</em> does not construct its
-      WHERE clause in a similar manner as the
-      <em>doSelect</em> method.  <em>doDelete</em>
-      processes <em>Criteria</em> in a more
-      primitive fashion.  Specifically,
-      <em>Criteria</em> assembled using the
-      <em>and</em> and <em>or</em> methods (not
-      covered in this tutorial) are effectively
-      ignored.  In addition, passing an empty
-      <em>Criteria</em> to <em>doDelete</em> will
-      not delete all of the rows from a table.  In
-      summary, you cannot assume that a
-      <em>Criteria</em> object which successfully
-      selects rows from a table via
-      <em>doSelect</em> will delete those rows if
-      passed to <em>doDelete</em>.  In the future,
-      <em>doDelete</em> may be modified to be
-      consistent in the handling of
-      <em>Criteria</em> objects.
-    </td>
-  </tr>
-</table>
-</section>
-
-<section name="Adding Functionality to the Object Model">
-
-<p>
-  This section will provide examples of adding
-  functionality to both the Peer and Data Object
-  classes.  As you may recall, Torque generated four
-  classes for each table defined in the database
-  schema.  Two of these classes (the Base Data Object
-  and Base Peer class) contain Torque-generated logic
-  while the other two are empty subclasses that you
-  can use to include business logic.  By now, you
-  should have a decent understanding of the type of
-  logic that might be added to these classes.  Keep in
-  mind, Torque will overwrite any changes that are
-  inadvertently added to the Base classes if you
-  regenerate your object model; however, it will not
-  overwrite changes in the non-Base classes.
-</p>
-
-<p>
-  The first change that we'll make to our object model
-  is to provide our Data Objects with adequate
-  <em>toString</em> methods.  Theses methods can then
-  be used to print the Data Objects without adding
-  unnecessary code to the core of the application.
-  The following are the modified <em>Book</em>,
-  <em>Author</em>, and <em>Publisher</em> classes,
-  which are located in a directory hierarchy matching
-  that of the <em>targetPackage</em> you specified in
-  your Torque <em>build.properties</em>:
-</p>
-
-<source><![CDATA[
-// Book.java
-import org.apache.torque.TorqueException;
-
-public  class Book
-    extends com.kazmier.om.BaseBook
-    implements Persistent
-{
-    public String toString()
-    {
-        StringBuffer sb = new StringBuffer();
-        try
-        {
-            sb.append("Title:     " + getTitle() + "\n");
-            sb.append("ISBN:      " + getISBN() + "\n");
-            sb.append("Publisher: " + getPublisher() + "\n");
-            sb.append("Author:    " + getAuthor() + "\n");
-        }
-        catch (TorqueException ignored)
-        {
-        }
-        return sb.toString();
-    }
-}
-
-// Author.java
-public  class Author
-    extends com.kazmier.om.BaseAuthor
-    implements Persistent
-{
-    public String toString()
-    {
-        return getLastName() + ", " + getFirstName();
-    }
-}
-
-// Publisher.java
-public  class Publisher
-    extends com.kazmier.om.BasePublisher
-    implements Persistent
-{
-    public String toString()
-    {
-      return getName();
-    }
-}
-]]></source>
-
-<p>
-  The next change that we'll make is to the Peer
-  classes.  For convenience (and based on the
-  suggestion in the
-  <a href="../peers-howto.html#Useful%20Methods">Peers
-  Howto</a>) we'll add <em>doSelectAll</em>
-  methods which will return a List of all the Data
-  Objects in a table.  The following are the modified
-  <em>BookPeer</em>, <em>AuthorPeer</em>, and
-  <em>PublisherPeer</em> classes which are located in
-  the same directory as the Data Objects:
-</p>
-
-<source><![CDATA[
-// BookPeer.java
-import java.util.List;
-import org.apache.torque.TorqueException;
-import org.apache.torque.util.Criteria;
-
-public class BookPeer
-    extends com.kazmier.om.BaseBookPeer
-{
-    public static List doSelectAll() throws TorqueException
-    {
-        Criteria crit = new Criteria();
-        return doSelect(crit);
-    }
-}
-
-// AuthorPeer.java
-import java.util.List;
-import org.apache.torque.TorqueException;
-import org.apache.torque.util.Criteria;
-
-public class AuthorPeer
-    extends com.kazmier.om.BaseAuthorPeer
-{
-    public static List doSelectAll() throws TorqueException
-    {
-        Criteria crit = new Criteria();
-        return doSelect(crit);
-    }
-}
-
-// PublisherPeer.java
-import java.util.List;
-import org.apache.torque.TorqueException;
-import org.apache.torque.util.Criteria;
-
-public class PublisherPeer
-  extends com.kazmier.om.BasePublisherPeer
-{
-    public static List doSelectAll() throws TorqueException
-    {
-        Criteria crit = new Criteria();
-        return doSelect(crit);
-    }
-}
-]]></source>
-
-<p>
-  In order to execute the full application presented
-  at the end of this tutorial, you must make the above
-  changes to your object model.  After you have made
-  the changes, proceed to the next section.
-</p>
-
-</section>
-
-<section name="Full Application">
-
-<p>
-  The following is the sample bookstore application in
-  its entirety.  It should look very familiar if
-  you've been following this tutorial.  In fact, its
-  almost identical with the exception that it utilizes
-  the new functionality that was added to the object
-  model in the previous section.  Note in particular the all-important
-  initialization of Torque using the <code>Torque.properties</code>
-  file we created earlier.
-</p>
-
-<source><![CDATA[
-package com.kazmier;
-
-import java.util.*;
-import com.kazmier.om.*;
-import org.apache.torque.Torque;
-import org.apache.torque.util.Criteria;
-
-public class Bookstore
-{
-    public static void main(String[] args)
-    {
-        try
-        {
-            /*
-             * Initializing Torque
-             */
-            Torque.init("Torque.properties");
-
-            /*
-             * Creating new objects. These will be inserted into your database
-             * automatically when the save method is called.
-             */
-            Publisher addison = new Publisher();
-            addison.setName("Addison Wesley Professional");
-            addison.save();
-
-            Author bloch = new Author();
-            bloch.setFirstName("Joshua");
-            bloch.setLastName("Bloch");
-            bloch.save();
-
-            /*
-             * An alternative method to inserting rows in your database.
-             */
-            Author stevens = new Author();
-            stevens.setFirstName("W.");
-            stevens.setLastName("Stevens");
-            AuthorPeer.doInsert(stevens);
-
-            /*
-             * Using the convenience methods to handle the foreign keys.
-             */
-            Book effective = new Book();
-            effective.setTitle("Effective Java");
-            effective.setISBN("0-618-12902-2");
-            effective.setPublisher(addison);
-            effective.setAuthor(bloch);
-            effective.save();
-
-            /*
-             * Inserting the foreign-keys manually.
-             */
-            Book tcpip = new Book();
-            tcpip.setTitle("TCP/IP Illustrated, Volume 1");
-            tcpip.setISBN("0-201-63346-9");
-            tcpip.setPublisherId(addison.getPublisherId());
-            tcpip.setAuthorId(stevens.getAuthorId());
-            tcpip.save();
-
-            /*
-             * Selecting all books from the database and printing the results to
-             * stdout using our helper method defined in BookPeer (doSelectAll).
-             */
-            System.out.println("Full booklist:\n");
-            List booklist = BookPeer.doSelectAll();
-            printBooklist(booklist);
-
-            /*
-             * Selecting specific objects. Just search for objects that match
-             * this criteria (and print to stdout).
-             */
-            System.out.println("Booklist (specific ISBN):\n");
-            Criteria crit = new Criteria();
-            crit.add(BookPeer.ISBN, "0-201-63346-9");
-            booklist = BookPeer.doSelect(crit);
-            printBooklist(booklist);
-
-            /*
-             * Updating data. These lines will swap the authors of the two
-             * books. The booklist is printed to stdout to verify the results.
-             */
-            effective.setAuthor(stevens);
-            effective.save();
-
-            tcpip.setAuthor(bloch);
-            BookPeer.doUpdate(tcpip);
-
-            System.out.println("Booklist (authors swapped):\n");
-            booklist = BookPeer.doSelectAll();
-            printBooklist(booklist);
-
-            /*
-             * Deleting data. These lines will delete the data that matches the
-             * specified criteria.
-             */
-            crit = new Criteria();
-            crit.add(BookPeer.ISBN, "0-618-12902-2");
-            BookPeer.doDelete(crit);
-
-            crit = new Criteria();
-            crit.add(BookPeer.ISBN, "0-201-63346-9");
-            crit.add(BookPeer.TITLE, "TCP/IP Illustrated, Volume 1");
-            BookPeer.doDelete(crit);
-
-            /*
-             * Deleting data by passing Data Objects instead of specifying
-             * criteria.
-             */
-            AuthorPeer.doDelete(bloch);
-            AuthorPeer.doDelete(stevens);
-            PublisherPeer.doDelete(addison);
-
-            System.out.println("Booklist (should be empty):\n");
-            booklist = BookPeer.doSelectAll();
-            printBooklist(booklist);
-        }
-        catch (Exception e)
-        {
-            e.printStackTrace();
-        }
-    }
-
-    /*
-     * Helper method to print a booklist to standard out.
-     */
-    private static void printBooklist(List booklist)
-    {
-        for (Iterator i = booklist.iterator(); i.hasNext();)
-        {
-            Book book = (Book) i.next();
-            System.out.println(book);
-        }
-    }
-}
+#Using commons-dbcp
+torque.dsfactory.bookstore.factory = org.apache.torque.dsfactory.SharedPoolDataSourceFactory
+torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
+torque.dsfactory.bookstore.connection.url = jdbc:mysql://localhost:3306/bookstore
+torque.dsfactory.bookstore.connection.user = user
+torque.dsfactory.bookstore.connection.password = password
   ]]></source>
 
-<p>
-  Save this code in the <em>src/java</em>
-  directory hierarchy with a filename of
-  <em>Bookstore.java</em>.  The above example must be
-  placed in <em>src/java/com/kazmier</em>
-  directory because of its package definition.  Your
-  application might go elsewhere depending on the
-  package that you've selected.
-</p>
-
-</section>
-
-<section name="Compiling and Running">
-
-<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.  To compile, type 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.  Should you
-  encounter errors, go back and review your
-  application code.
-</p>
-
-<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 from the <em>lib</em> directory of the Torque runtime archive, the
-  driver for your database, and all of your
-  application and object model classes located in
-  <em>target/classes</em>.
-</p>
-
-<p>
-  An easy way to set your classpath (if you're using a
-  bourne-shell or one of its derivatives on a
-  un*x-based system) is to type the following in the
-  top-level project directory (first add your database
-  driver to the <em>lib</em> directory if you
-  haven't already):
-</p>
-
-<source><![CDATA[
-  [kaz@coco bookstore]$ CLASSPATH=bin/classes
-  [kaz@coco bookstore]$ for i in lib/*
-  > do
-  > CLASSPATH=$CLASSPATH:$i
-  > done
-  [kaz@coco torque]$ export CLASSPATH
-]]></source>
-
-<p>
-  With your classpath set, you are now ready to
-  finally run the application.  From the top-level
-  directory with your project run-time properties, type
-  the following, replacing the name of the class with
-  your class:
-</p>
+  <p>
+    Change the adapter, driver, url, user and password parameters
+    to match the parameters for your database.
+    In the following table, the parameters used in the sample
+    configuration are described. For further information, see the
+    <a href="../configuration-howto.html">Pool-config Howto</a>.
+  </p>
 
-<source><![CDATA[
-  java com.kazmier.Bookstore
-]]></source>
+  <table>
+    <tr> <th>Property</th> <th>Description</th> </tr>
+    <tr>
+      <td>torque.database.default</td>
+      <td>
+        Torque has the ability to use multiple
+        databases.  This property specifies which
+        database is to be used as the default.
+      </td>
+    </tr>
+    <tr>
+      <td>torque.database.XXX.adapter</td>
+      <td>
+        Torque has the ability to deal with multiple database systems.
+        This property specifies the database adapter to use.
+      </td>
+    </tr>
+    <tr>
+      <td>torque.dsfactory.XXX.factory</td>
+      <td>
+        The factory class that will be used to provide database connections.
+      </td>
+    </tr>
+    <tr>
+      <td>torque.dsfactory.XXX.connection.driver</td>
+      <td>
+        The JDBC database driver to use when
+        connecting to your database.
+      </td>
+    </tr>
+    <tr>
+      <td>torque.database.XXX.connection.url</td>
+      <td>
+        The URL that will be used to access your
+        database.  Torque's generated object model
+        will perform all database operations using
+        this URL.  This value should reflect the
+        database name specified in your database
+        schema file (see the <em>database</em>
+        element's <em>name</em> attribute).
+      </td>
+    </tr>
+    <tr>
+      <td>torque.database.XXX.connection.username</td>
+      <td>
+        The username that has sufficient privileges
+        to access your database.  This user does not
+        require privileges to create and drop
+        tables, unlike the username that was
+        specified in <em>project.properties</em>.
+      </td>
+    </tr>
+    <tr>
+      <td>torque.database.XXX.connection.password</td>
+      <td>
+        The password for the specified username.
+      </td>
+    </tr>
+  </table>
 
-<p>
-  If all goes well, you should see the following
-  output:
-</p>
+  <p>
+    It is worth re-iterating that these run-time
+    properties are not used by Torque when generating
+    your object model and creating your database.  They
+    are used only by the application utilizing the
+    Torque-generated object model classes at run-time.
+  </p>
 
-<source><![CDATA[
-  Full booklist:
+</section>
 
-  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.
+<section name="Logging configuration">
 
-  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.  For example, mistyping
-    the username or password in your Torque run-time
-    properties file results in a
-    <em>NullPointerException</em>, as do many other
-    types of errors.  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.
+    Torque uses 
+    <a href="http://jakarta.apache.org/commons/logging/">
+    commons-logging</a> as a logging interface.
+    To enable logging in your application, read the 
+    <a href="http://jakarta.apache.org/commons/logging/commons-logging-1.0.3/usersguide.html">
+    commons-logging user guide</a>.
+  </p>
+  
+  <p>
+    If you have no trouble running the tutorial,
+    you do not need to configure logging now. If, however,
+    you experience runtime errors later on 
+    and do not find the reason immediately, 
+    it might be a good idea to configure 
+    logging and look at the log messages. Also, for a 
+    &quot;serious&quot; application, logging is 
+    indispensible in order to track down any 
+    unexpected errors.
   </p>
 
 </section>
 
-<section name="Where to Go From Here">
+<section name="Where to next">
 
-<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>
+  <p>
+    Now you have finished configuring the Torque runtime.
+    You are now ready to use the generated classes to access
+    the database.
+  </p>
+  <p>
+    Next we will look <a href="step5.html">Writing a Sample Application</a>.
+  </p>
 
 </section>
 
-  </body>
+</body>
 </document>



---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message