db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject cvs commit: db-torque/xdocs/tutorial step1.xml index.xml step3.xml step2.xml
Date Mon, 18 Jul 2005 04:33:13 GMT
tfischer    2005/07/17 21:33:10

  Modified:    xdocs/tutorial step1.xml index.xml step3.xml step2.xml
  Log:
  - thrown out some historical stuff
  - change version names
  - added a remark on the structure of torque (runtime, generator, maven plugin)
  - added a remark that the create-db might not work in all circumstances
  
  Revision  Changes    Path
  1.9       +31 -6     db-torque/xdocs/tutorial/step1.xml
  
  Index: step1.xml
  ===================================================================
  RCS file: /home/cvs/db-torque/xdocs/tutorial/step1.xml,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- step1.xml	2 Jul 2005 07:33:53 -0000	1.8
  +++ step1.xml	18 Jul 2005 04:32:08 -0000	1.9
  @@ -5,14 +5,34 @@
       <title>Torque Tutorial</title>
       <author email="pete-apache-dev@kazmier.com">Pete Kazmier</author>
       <author email="seade@backstagetech.com.au">Scott Eade</author>
  -  </properties>
  +    <author email="fischer@seitenbau.de">Thomas Fischer</author>
  + </properties>
     <body>
   
   <section name="Step 1: Obtaining the Torque Distribution">
   
   <p>
  -  For this tutorial we will be using the maven plugin for Torque 3.1.1 to
  -  generate our object model classes and the Torque 3.1.1 runtime for our
  +  First of all, note that Torque is divided into three parts.
  +  <ul>
  +    <li>
  +      The generator generates your persistence classes from an xml
  +      description of the database. It also generates and executes
  +      sql scripts to create all the necessary tables, constraints etc. 
  +      in your database.
  +    </li>
  +    <li>
  +      The maven plugin integrates the generator into 
  +      <a href="http://maven.apache.org/">Maven</a>, a software 
  +      project management tool.
  +    </li>
  +    <li>
  +      The runtime has to be included in your projects for the generated classes
  +      to work properly.
  +    </li>
  +  </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.
   </p>
   
  @@ -25,18 +45,23 @@
   </p>
   
   <source><![CDATA[
  -maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.1.1
  +maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.2-rc1
   ]]></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.1.1.tar.gz or 
  -  torque-3.1.1.zip, depending on your development platform).  We will cover
  +  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.
  +</p>
  +
   </section>
   
   <section name="Where to next">
  
  
  
  1.7       +2 -9      db-torque/xdocs/tutorial/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/db-torque/xdocs/tutorial/index.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- index.xml	30 Jan 2005 11:29:24 -0000	1.6
  +++ index.xml	18 Jul 2005 04:32:12 -0000	1.7
  @@ -13,12 +13,6 @@
   <p>
     This tutorial is intended to give first-time users an
     introduction to using Torque, an object-relational tool.
  -  Torque was developed as part of the 
  -  <a href="http://jakarta.apache.org/turbine/">Turbine</a> web
  -  application framework.  Until recently, it was tightly
  -  coupled in that framework, and could not be used
  -  independently.  This tutorial is an introduction to the
  -  decoupled version of Torque.
   </p>
   
   <p>
  @@ -33,9 +27,8 @@
   
   <p>
     The example used throughout this tutorial is based on an
  -  email sent to the <a href="../mail-lists.html">
  -  turbine-user</a> mailing list by Steven F. Davis
  -  called
  +  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">
     torque outside turbine - detailed example (long)</a>.
     It has subsequently been updated for Turbine 3.1 which
  
  
  
  1.5       +22 -15    db-torque/xdocs/tutorial/step3.xml
  
  Index: step3.xml
  ===================================================================
  RCS file: /home/cvs/db-torque/xdocs/tutorial/step3.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- step3.xml	30 Aug 2004 00:24:43 -0000	1.4
  +++ step3.xml	18 Jul 2005 04:32:17 -0000	1.5
  @@ -11,21 +11,21 @@
   <section name="Step 3: Invoking Torque">
   
   <p>
  -With the configuration of Torque 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
  -tutorial, Torque utilizes Maven to perform these tasks.
  -Each of these tasks is covered in the following
  -sections.
  +  With the configuration of Torque 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
  +  tutorial, Torque utilizes Maven to perform these tasks.
  +  Each of these tasks is covered in the following
  +  sections.
   </p>
   
   <p>
  -Note: If you are yet to jump aboard the Maven ship you can 
  -download the torque-gen archive and make use of the Ant build 
  -file <code>build-torque.xml</code> contained therein - see the 
  -<a href="../user-guide.html#Generator_with_the_Ant_build_file">User Guide</a>.

  -for details.
  +  Note: If you are yet to jump aboard the Maven ship you can 
  +  download the torque-gen archive and make use of the Ant build 
  +  file <code>build-torque.xml</code> contained therein. Some hints
  +  about this can be found in the 
  +  <a href="../user-guide.html#Generator_with_the_Ant_build_file">User Guide</a>.

   </p>
   
   </section>
  @@ -102,9 +102,7 @@
     schema file.  Check the format of the file and make
     sure it conforms to the
     <a href="../generator/schema-reference.html">
  -  Torque Schema Reference</a>.  Validating the file 
  -  against the provided DTD will help ensure that it 
  -  will be processed correctly.
  +  Torque Schema Reference</a>.
   </p>
   
   </section>
  @@ -143,6 +141,15 @@
   ]]></source>
   
   <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.
  +</p>
  +
  +<p>
     To create your tables, type the following commands in
     the top-level directory of your project:
   </p>
  
  
  
  1.11      +17 -40    db-torque/xdocs/tutorial/step2.xml
  
  Index: step2.xml
  ===================================================================
  RCS file: /home/cvs/db-torque/xdocs/tutorial/step2.xml,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- step2.xml	20 Aug 2004 03:07:04 -0000	1.10
  +++ step2.xml	18 Jul 2005 04:32:21 -0000	1.11
  @@ -5,6 +5,7 @@
       <title>Torque Tutorial - Step 2: Configuring Torque</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>
   
  @@ -12,10 +13,10 @@
   
   <p>
     The following section outlines the necessary steps to
  -  define your database schema and configure Torque to use
  -  your schema.  Upon completion, you'll be able to use
  -  Torque to create your object model and all of the Java
  -  classes that support it.  In addition, Torque can
  +  define your database schema and configure the Torque generator
  +  to use your schema. Upon completion, you'll be able to use
  +  the generator to create your object model and all of the Java
  +  classes that support it.  In addition, the generator can
     generate and execute all of the appropriate SQL commands
     to create your database, freeing you from having to do it
     manually.
  @@ -78,9 +79,6 @@
   
     # The hostname or IP address of your database server.
     torque.database.host = 127.0.0.1
  -
  -  # The location of the your *-schema.xml files (see below).
  -  #torque.schema.dir = ./schema
   ]]></source>
   
   <p>
  @@ -102,11 +100,11 @@
   <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 jar file.  If you want to customise the templates 
  +  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 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.
  +  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.
   </p>
   </subsection>
   
  @@ -125,7 +123,7 @@
   
   <p>
     By default your database schema file should be located in the
  -  <em>schema</em> directory under the base of your project, but
  +  <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>
  @@ -137,15 +135,8 @@
     by Torque's IDBroker service (which is a database
     independent method for generating unique IDs).
     <em>project-schema.xml</em> is where you'll define
  -  your database schema.  Historically, the name of
  -  your database schema file was required to be in the
  -  format of <em>name-schema.xml</em> where
  -  <em>name</em> was the same as the <em>project</em>
  -  property defined in <em>project.properties</em>;
  -  otherwise, Torque was not able to find your
  -  database schema file.  This is no longer the case,
  -  <em>name</em> is no longer restricted to the project
  -  name. However, it must end with
  +  your database schema. The name of
  +  your database schema file must end with
     &#145;-schema.xml&#146; because Torque will only
     generate object models for files ending with that
     pattern.
  @@ -320,20 +311,6 @@
         is described below).
       </td>
     </tr>
  -  <tr>
  -    <td>autoincrement</td>
  -    <td>
  -      This method has been deprecated.  Use the
  -      <em>native</em> method instead.
  -    </td>
  -  </tr>
  -  <tr>
  -    <td>sequence</td>
  -    <td>
  -      This method has been deprecated.  Use the
  -      <em>native</em> method instead.
  -    </td>
  -  </tr>
   </table>
   
   <p>
  @@ -396,7 +373,7 @@
     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
  -  <a href="/torque/dtd/database_3_1.dtd">DTD</a>
  +  <a href="/torque/dtd/database_3_2.dtd">DTD</a>
     for the database schema.  In addition, you must
     include the XML declaration and DTD specification in
     your database schema file.  Failure to do so can
  @@ -449,9 +426,7 @@
     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.  In the next section, we will conclude the
  -  configuration of Torque by editing the Torque
  -  run-time properties.  For additional information on
  +  schemas.  For additional information on
     the XML elements and attributes, please refer to the
     <a href="../generator/schema-reference.html">
     Torque Schema Reference</a>.
  @@ -675,12 +650,14 @@
       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
  -      classath, including it may adversly affect the logging configuration of 
  +      classpath, including it may adversly affect the logging configuration of 
         your application.
       </b>
     </p>
  
  
  

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