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="[EMAIL PROTECTED]">Pete Kazmier</author>
<author email="[EMAIL PROTECTED]">Scott Eade</author>
- </properties>
+ <author email="[EMAIL PROTECTED]">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/[EMAIL
PROTECTED]&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="[EMAIL PROTECTED]">Pete Kazmier</author>
<author email="[EMAIL PROTECTED]">Scott Eade</author>
+ <author email="[EMAIL PROTECTED]">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
‘-schema.xml’ 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
