seade 2004/08/19 07:34:14
Modified: xdocs/tutorial step1.xml step4.xml index.xml step3.xml
step2.xml
Log:
A vast array of documentation updates - long overdue.
Revision Changes Path
1.4 +26 -18 db-torque/xdocs/tutorial/step1.xml
Index: step1.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/tutorial/step1.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- step1.xml 11 May 2003 12:59:07 -0000 1.3
+++ step1.xml 19 Aug 2004 14:34:14 -0000 1.4
@@ -4,39 +4,47 @@
<properties>
<title>Torque Tutorial</title>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
+ <author email="[EMAIL PROTECTED]">Scott Eade</author>
</properties>
<body>
<section name="Step 1: Obtaining the Torque Distribution">
<p>
- First, you need to obtain the Torque
- <a href="http://jakarta.apache.org/builds/jakarta-turbine/torque/release/";>
- distribution</a>.
- Note that for this tutorial, you should NOT use the CVS version
- of db-torque instead of the normal release version, since the
- Torque CVS tree has a differing directory layout; thus it's unsuitable
- for this example (at least if you're a newbie who doesn't know how to
- configure the CVS version properly, which is probably true
- for most people that are reading this tutorial).
+ 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
+ application that makes use of the generated classes.
</p>
<p>
- After you have obtained your copy of the Torque, you can either
- unpack the jar and integrate all of the Torque files into your
- source tree, or keep Torque in the jar and use it via the classpath.
+ 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:
</p>
+<source><![CDATA[
+!!! TO DO - The binary plugn is yet to be deployed, in the mean time you must build
the plugin from source. !!!
+!!! TO DO - Confirm these values !!!
+maven plugin:download -DartifactId=maven-torque-plugin
-DgroupId=maven-torque-plugin -Dversion=3.1.1
+]]></source>
+
<p>
- This tutorial will take the former approach. See <a href="../jar-guide.html">jar
- guide</a> for a description of the latter approach.
+ 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://jakarta.apache.org/builds/jakarta-turbine/torque/release/3.1.1/";>
+ 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
+ what to do with this file in a later step.
</p>
+</section>
+
+<section name="Where to next">
+
<p>
- You need to unpack the Torque jar to a directory where
- you want to develop your application. This will create
- a directory called <em>torque</em>. It is here that you
- will configure Torque and build your application.
+ Next we will look at <a href="step2.html">Configuring Torque</a>.
</p>
</section>
1.5 +238 -237 db-torque/xdocs/tutorial/step4.xml
Index: step4.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/tutorial/step4.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- step4.xml 5 Jan 2004 00:33:47 -0000 1.4
+++ step4.xml 19 Aug 2004 14:34:14 -0000 1.5
@@ -4,6 +4,7 @@
<properties>
<title>Torque Tutorial - Step 4 - Writing a Sample Application</title>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
+ <author email="[EMAIL PROTECTED]">Scott Eade</author>
</properties>
<body>
@@ -33,7 +34,7 @@
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 (via <em>ant</em>). Any
+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.
@@ -94,7 +95,7 @@
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. Thats
+ values, then call the <em>save</em> method. That's
it. The following is from the sample application:
</p>
@@ -177,9 +178,9 @@
<source><![CDATA[
/*
-* Using the convenience methods to handle
-* the foreign keys.
-*/
+ * Using the convenience methods to handle
+ * the foreign keys.
+ */
Book effective = new Book();
effective.setTitle("Effective Java");
effective.setISBN("0-618-12902-2");
@@ -188,8 +189,8 @@
effective.save();
/*
-* Inserting the foreign-keys manually.
-*/
+ * Inserting the foreign-keys manually.
+ */
Book tcpip = new Book();
tcpip.setTitle("TCP/IP Illustrated, Volume 1");
tcpip.setISBN("0-201-63346-9");
@@ -216,7 +217,7 @@
<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 vector of Data Objects
+ <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
@@ -226,7 +227,7 @@
<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 an
+ 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
@@ -237,11 +238,11 @@
<source><![CDATA[
Criteria crit = new Criteria();
-List v = BookPeer.doSelect(crit);
+List books = BookPeer.doSelect(crit);
]]></source>
<p>
- The results are stored in a vector which can then be
+ 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
@@ -249,17 +250,16 @@
</p>
<source><![CDATA[
-Iterator i = v.iterator();
-while (i.hasNext())
+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");
+ 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>
@@ -330,7 +330,7 @@
<source><![CDATA[
Criteria crit = new Criteria();
crit.add(BookPeer.ISBN, "0-618-12902-2");
-List v = BookPeer.doSelect(crit);
+List books = BookPeer.doSelect(crit);
]]></source>
<p>
@@ -510,47 +510,49 @@
<source><![CDATA[
// Book.java
-public class Book
- extends com.kazmier.om.BaseBook
- implements Persistent
+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 (Exception ignored)
+ 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();
}
- return sb.toString();
- }
}
// Author.java
public class Author
- extends com.kazmier.om.BaseAuthor
- implements Persistent
+ extends com.kazmier.om.BaseAuthor
+ implements Persistent
{
- public String toString()
- {
- return getLastName() + ", " + getFirstName();
- }
+ public String toString()
+ {
+ return getLastName() + ", " + getFirstName();
+ }
}
// Publisher.java
public class Publisher
- extends com.kazmier.om.BasePublisher
- implements Persistent
+ extends com.kazmier.om.BasePublisher
+ implements Persistent
{
- public String toString()
- {
- return getName();
- }
+ public String toString()
+ {
+ return getName();
+ }
}
]]></source>
@@ -569,42 +571,48 @@
<source><![CDATA[
// BookPeer.java
-import org.apache.torque.util.*;
+import java.util.List;
+import org.apache.torque.TorqueException;
+import org.apache.torque.util.Criteria;
public class BookPeer
- extends com.kazmier.om.BaseBookPeer
+ extends com.kazmier.om.BaseBookPeer
{
- public static List doSelectAll() throws Exception
- {
- Criteria crit = new Criteria();
- return doSelect(crit);
- }
+ public static List doSelectAll() throws TorqueException
+ {
+ Criteria crit = new Criteria();
+ return doSelect(crit);
+ }
}
// AuthorPeer.java
-import org.apache.torque.util.*;
+import java.util.List;
+import org.apache.torque.TorqueException;
+import org.apache.torque.util.Criteria;
public class AuthorPeer
- extends com.kazmier.om.BaseAuthorPeer
+ extends com.kazmier.om.BaseAuthorPeer
{
- public static List doSelectAll() throws Exception
- {
- Criteria crit = new Criteria();
- return doSelect(crit);
- }
+ public static List doSelectAll() throws TorqueException
+ {
+ Criteria crit = new Criteria();
+ return doSelect(crit);
+ }
}
// PublisherPeer.java
-import org.apache.torque.util.*;
+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 Exception
- {
- Criteria crit = new Criteria();
- return doSelect(crit);
- }
+ public static List doSelectAll() throws TorqueException
+ {
+ Criteria crit = new Criteria();
+ return doSelect(crit);
+ }
}
]]></source>
@@ -625,7 +633,9 @@
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.
+ 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[
@@ -638,147 +648,138 @@
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)
+ public static void main(String[] args)
{
- e.printStackTrace();
+ 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)
- throws Exception
- {
- Iterator i = booklist.iterator();
- while (i.hasNext())
+ /*
+ * Helper method to print a booklist to standard out.
+ */
+ private static void printBooklist(List booklist)
{
- Book book = (Book) i.next();
- System.out.println(book);
+ for (Iterator i = booklist.iterator(); i.hasNext();)
+ {
+ Book book = (Book) i.next();
+ System.out.println(book);
+ }
}
- }
}
]]></source>
<p>
- Save this code in the <em>torque/src/java</em>
+ 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>torque/src/java/com/kazmier</em>
+ 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.
@@ -791,20 +792,20 @@
<p>
Now that you've generated your object model with
Torque, and created a sample application, you are
- now ready to compile everything. Again, Ant is used
+ now ready to compile everything. Again, Maven is used
to control the build process. To compile, type the
- following in the Torque top-level directory:
+ following in the top-level directory of your project:
</p>
<source><![CDATA[
-ant -f build-torque.xml compile
+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>torque/bin/classes</em> directory. Should you
+ <em>target/classes</em> directory. Should you
encounter errors, go back and review your
application code.
</p>
@@ -812,26 +813,26 @@
<p>
Before you run the sample application, you must
first set your classpath (this was done
- automatically for you via Ant's build file when you
+ automatically for you by Maven when you
compiled). The classpath must include: all of the
- jars in the <em>torque/lib</em> directory, 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>torque/bin/classes</em>.
+ <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 Torque directory (first add your database
- driver to the <em>torque/lib</em> directory if you
+ top-level project directory (first add your database
+ driver to the <em>lib</em> directory if you
haven't already):
</p>
<source><![CDATA[
- [EMAIL PROTECTED] torque]$ CLASSPATH=bin/classes
- [EMAIL PROTECTED] torque]$ for i in lib/*
+ [EMAIL PROTECTED] bookstore]$ CLASSPATH=bin/classes
+ [EMAIL PROTECTED] bookstore]$ for i in lib/*
> do
> CLASSPATH=$CLASSPATH:$i
> done
@@ -841,7 +842,7 @@
<p>
With your classpath set, you are now ready to
finally run the application. From the top-level
- directory with your Torque run-time properties, type
+ directory with your project run-time properties, type
the following, replacing the name of the class with
your class:
</p>
@@ -858,34 +859,34 @@
<source><![CDATA[
Full booklist:
- Title: Effective Java
- ISBN: 0-618-12902-2
- Publisher: Addison Wesley Professional
- Author: Bloch, Joshua
-
- Title: TCP/IP Illustrated, Volume 1
- ISBN: 0-201-63346-9
- Publisher: Addison Wesley Professional
- Author: Stevens, W.
+ 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.
+ Title: TCP/IP Illustrated, Volume 1
+ ISBN: 0-201-63346-9
+ Publisher: Addison Wesley Professional
+ Author: Stevens, W.
Booklist (authors swapped):
- Title: Effective Java
- ISBN: 0-618-12902-2
- Publisher: Addison Wesley Professional
- Author: Stevens, W.
-
- Title: TCP/IP Illustrated, Volume 1
- ISBN: 0-201-63346-9
- Publisher: Addison Wesley Professional
- Author: Bloch, Joshua
+ Title: TCP/IP Illustrated, Volume 1
+ ISBN: 0-201-63346-9
+ Publisher: Addison Wesley Professional
+ Author: Bloch, Joshua
+
+ Title: Effective Java
+ ISBN: 0-618-12902-2
+ Publisher: Addison Wesley Professional
+ Author: Stevens, W.
Booklist (should be empty):
]]></source>
@@ -900,8 +901,8 @@
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 Turbine
- <a href="/mail.html">mailing list</a> to your
+ run, use the Torque user
+ <a href="../mail-lists.html">mailing list</a> to your
advantage.
</p>
1.5 +19 -3 db-torque/xdocs/tutorial/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/tutorial/index.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- index.xml 5 Jan 2004 00:33:47 -0000 1.4
+++ index.xml 19 Aug 2004 14:34:14 -0000 1.5
@@ -4,6 +4,7 @@
<properties>
<title>Torque Tutorial</title>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
+ <author email="[EMAIL PROTECTED]">Scott Eade</author>
</properties>
<body>
@@ -12,7 +13,8 @@
<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 Turbine web
+ 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
@@ -25,21 +27,35 @@
to demonstrate the power of Torque. The tutorial is not
meant to be an exhaustive introduction to Torque, please
refer to the documentation on the
- <a href="index.html">Torque homepage</a> for more
+ <a href="../">Torque homepage</a> for more
detailed information.
</p>
<p>
The example used throughout this tutorial is based on an
- email sent to the <a href="/mail.html">
+ email sent to the <a href="../mail-lists.html">
turbine-user</a> mailing list by Steven F. Davis
called
<a href="http://nagoya.apache.org/eyebrowse/[EMAIL PROTECTED]&msgNo=5287">
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
+ the <a href="../">runtime</a> and provides a
+ <a href="../maven-plugin/">maven-plugin</a> for executing
+ the generator using <a href="http://maven.apache.org/";>
+ Maven</a>.
</p>
</section>
+<section name="Where to next">
+
+<p>
+ First we will look at <a href="step1.html">Obtainning the Torque
+ Distribution</a>.
+</p>
+
+</section>
</body>
</document>
1.3 +49 -31 db-torque/xdocs/tutorial/step3.xml
Index: step3.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/tutorial/step3.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- step3.xml 11 May 2003 12:59:07 -0000 1.2
+++ step3.xml 19 Aug 2004 14:34:14 -0000 1.3
@@ -4,6 +4,7 @@
<properties>
<title>Torque Tutorial - Step 3: Invoking Torque</title>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
+ <author email="[EMAIL PROTECTED]">Scott Eade</author>
</properties>
<body>
@@ -14,11 +15,17 @@
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 Ant to perform these tasks.
+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.
+</p>
+
</section>
<section name="Generating the Object Model and Associated SQL">
@@ -46,29 +53,32 @@
</p>
<p>
- To generate your object model and the associated
- SQL, type the following command in the top-level
- <em>torque</em> directory:
+ To generate your object model and the associated SQL, type the
+ following command in your top-level project directory:
</p>
<source><![CDATA[
-ant -f build-torque.xml
+maven torque
]]></source>
-<p/>
<p>
Upon a successful build, indicated by the
‘BUILD SUCCESSFUL’ message, you will find
- a new <em>torque/src</em> directory. It is here
- that you will find the generated Java classes and
- generated SQL.
+ 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).
</p>
<p>
The Java classes are located in the <em>java</em>
directory and will be in a directory hierarchy
- matching that of the <em>targetPackage</em> you
- specified in your Torque <em>build.properties</em>.
+ 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>
@@ -76,7 +86,7 @@
<p>
The SQL files are located in the <em>sql</em>
directory. For each database schema in your
- <em>torque/schema</em> directory, there will be a
+ <em>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
@@ -89,8 +99,10 @@
than likely a formatting error of your database
schema file. Check the format of the file and make
sure it conforms to the
- <a href="../schema-reference.html">
- Torque Schema Reference</a>.
+ <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.
</p>
</section>
@@ -102,13 +114,12 @@
create your database and all of the associated
tables for you. However, you must first make sure
that the appropriate database driver (the one you
- defined in <em>build.properties</em>) is in your
+ 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 to the <em>torque/lib</em>
- directory. Ant's build file automatically adds all
- of the jar files in this directory to its classpath.
+ database driver as a dependency in your project
+ (add it to your <code>project.xml</code>.
</p>
<p>
@@ -122,21 +133,21 @@
<p>
To create your database, type the following command
- in the top-level <em>torque</em> directory:
+ in the top-level directory of your project:
</p>
<source><![CDATA[
-ant -f build-torque.xml create-db
+maven torque:create-db
]]></source>
<p>
To create your tables, type the following commands in
- the top-level <em>torque</em> directory:
+ the top-level directory of your project:
</p>
<source><![CDATA[
-ant -f build-torque.xml id-table-init-sql
-ant -f build-torque.xml insert-sql
+maven torque:id-table-init-sql
+maven torque:insert-sql
]]></source>
<p>
@@ -161,21 +172,28 @@
<p>
If you encounter errors while creating your
database, it is more than likely a misconfiguration
- of your <em>build.properties</em>. Another common
+ of your <em>project.properties</em>. Another common
problem is that the user specified in the
- <em>build.properties</em> does not have sufficient
+ <em>project.properties</em> does not have sufficient
privilege to create databases and tables. In either
case, refer to the section above that explains the
- <em>build.properties</em> file.
+ <em>project.properties</em> file.
</p>
</section>
-<p>
-Now that you have generated all of your object model
-classes and created your database, you are now ready to
-build your first Torque application.
-</p>
+<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
+ build your first Torque application.
+ </p>
+ <p>
+ Next we will look <a href="step4.html">Writing a Sample Application</a>.
+ </p>
+
+</section>
</body>
</document>
1.9 +216 -96 db-torque/xdocs/tutorial/step2.xml
Index: step2.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/tutorial/step2.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- step2.xml 13 Aug 2004 05:58:20 -0000 1.8
+++ step2.xml 19 Aug 2004 14:34:14 -0000 1.9
@@ -4,6 +4,7 @@
<properties>
<title>Torque Tutorial - Step 2: Configuring Torque</title>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
+ <author email="[EMAIL PROTECTED]">Scott Eade</author>
</properties>
<body>
@@ -16,13 +17,13 @@
Torque to create your object model and all of the Java
classes that support it. In addition, Torque can
generate and execute all of the appropriate SQL commands
- to create your database, freeing you from doing it
- yourself.
+ to create your database, freeing you from having to do it
+ manually.
</p>
<p>
To accomplish all of the above, you only need to
- create/edit three files: the Torque build properties,
+ 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
following sections.
@@ -30,44 +31,56 @@
</section>
-<section name="Torque Build Properties">
+<section name="Torque Generator Properties">
<p>
- Torque is a system that literally builds Java
+ Torque is a system that 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://ant.apache.org/";>Ant</a> to control its
- build process, and ant uses the
- <em>build.properties</em> file in the top-level
- Torque directory to setup your development
- environment. It is this file that we will now edit.
-</p>
-
-<p>
- Keep in mind, this tutorial is going to show you the
- bare minimum to get your first Torque application up
- and running. However, the <em>build.properties</em>
- file is thoroughly commented, so please refer to it
- if you have a question regarding a part of the file
- that is not covered here. Make the following
- changes and edit appropriately for your environment.
- The properties are described in the table following
- (note: you'll need to add the
- <em>torque.database.buildUrl</em> property):
+ <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>.
+ 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.
</p>
<source><![CDATA[
+ # The name of the project Torque will generate code for.
torque.project = bookstore
+
+ # The target database platform.
torque.database = mysql
+
+ # The target package to put the generated classes in.
torque.targetPackage = com.kazmier.om
+
+ # The JDBC URL that Torque can use to create and
+ # drop databases if instructed to do so.
torque.database.createUrl = jdbc:mysql://127.0.0.1/mysql
+
+ # The JDBC URL that will be used to create tables in your database.
torque.database.buildUrl = jdbc:mysql://127.0.0.1/bookstore
+
+ # The JDBC URL that will be used to access your database.
torque.database.url = jdbc:mysql://127.0.0.1/bookstore
+
+ # The JDBC database driver to use when connecting to your database.
torque.database.driver = org.gjt.mm.mysql.Driver
+
+ # The administrative username that has sufficient privileges to create
+ # and drop databases and tables that Torque executes at generation time.
torque.database.user = adminuser
+
+ # The administrative password for the supplied username.
torque.database.password = adminpassword
+
+ # 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>
@@ -85,6 +98,18 @@
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 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.
+</p>
+</subsection>
+
</section>
<section name="Torque Database Schema">
@@ -99,9 +124,14 @@
</p>
<p>
- The database schema file is located in the
- <em>torque/schema</em> directory. Here you will
- find two XML files: <em>id-table-schema.xml</em> and
+ By default your database schema file should be located in the
+ <em>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
+ 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
by Torque's IDBroker service (which is a database
@@ -111,7 +141,7 @@
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>build.properties</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
@@ -239,7 +269,7 @@
<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>build.properties</em>; likewise, the run-time
+ <em>project.properties</em>; likewise, the run-time
properties (described in the next section) should
also reflect this value. Failure to do so will
prevent Torque from creating your database tables
@@ -268,7 +298,7 @@
<td>idbroker</td>
<td>
Instructs Torque to use its
- <a href="../peers-howto.html#ID%20Broker">IDBroker</a>
+ <a href="../peers-howto.html#ID_Broker">IDBroker</a>
service to generate IDs in a database agnostic
manner. This is the method that will be
used in this tutorial.
@@ -423,7 +453,7 @@
configuration of Torque by editing the Torque
run-time properties. For additional information on
the XML elements and attributes, please refer to the
- <a href="../schema-reference.html">
+ <a href="../generator/schema-reference.html">
Torque Schema Reference</a>.
</p>
@@ -441,93 +471,110 @@
passwords. These properties can be saved in any
file because your application must explicitly
initialize Torque (as you'll see later in this
- document).
+ tutorial).
</p>
<p>
- There is a sample run-time properties file included
- in the Torque distribution called
- <em>Torque.properties</em> located in the
- <em>torque/schema</em> directory. However, for
- simplicity, we'll just create our own. Again, this
- tutorial will guide you through the bare minimum to
- get your application up and running. For more
- information regarding the Torque run-time
- properties, refer to the comments in the sample file
- included in the distribution. Create a new file
- called <em>Torque.properties</em> in the top-level
- <em>torque</em> directory (to avoid overwriting the
- sample property file) and add the following lines to
- it:
+ 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[
-log4j.rootCategory = DEBUG, default
-log4j.appender.default = org.apache.log4j.FileAppender
-log4j.appender.default.file = ./torque.log
-log4j.appender.default.layout = org.apache.log4j.SimpleLayout
+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.prperties
+ <--- 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.
+</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:
+</p>
+
+<source><![CDATA[
torque.database.default = bookstore
-torque.database.bookstore.driver = org.gjt.mm.mysql.Driver
-torque.database.bookstore.url = jdbc:mysql://127.0.0.1/bookstore
-torque.database.bookstore.username = user
-torque.database.bookstore.password = password
+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/>
+
+ <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>log4j.rootCategory</td>
- <td>
- Torque uses <a href="http://logging.apache.org/log4j/";>Log4J</a>
- for a logging. This parameter configures
- the Log4J system to log all messages (debug,
- info, warn, error, and fatal).
- </td>
- </tr>
- <tr>
- <td>log4j.appender.default</td>
+ <td>torque.database.default</td>
<td>
- Configures Log4J to send all logging
- messages to a file in the filesystem. Log4J
- could just as easily send all logging to a
- syslog server.
+ Torque has the ability to use multiple
+ databases. This property specifies which
+ database is to be used as the default.
</td>
</tr>
<tr>
- <td>log4j.appender.default.file</td>
+ <td>torque.database.XXX.adapter</td>
<td>
- The name of the file where messages are
- logged. This is relative to the starting
- point of the JVM.
+ Torque has the ability to deal with multiple database systems.
+ This property specifies the database adapter to use.
</td>
</tr>
<tr>
- <td>log4j.appender.default.layout</td>
+ <td>torque.dsfactory.XXX.factory</td>
<td>
- Log4J logs messages using a layout. Layouts
- can be very simple or complicated. This
- tutorial uses the very rudimentary
- SimpleLayout.
+ The factory class that will be used to provide database connections.
</td>
</tr>
<tr>
- <td>torque.database.default</td>
- <td>
- Torque has the ability to use multiple
- databases. This command specifies which
- database is to be used as the default.
- </td>
- </tr>
- <tr>
- <td>torque.database.bookstore.driver</td>
+ <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.bookstore.url</td>
+ <td>torque.database.XXX.connection.url</td>
<td>
The URL that will be used to access your
database. Torque's generated object model
@@ -539,23 +586,23 @@
</td>
</tr>
<tr>
- <td>torque.database.bookstore.username</td>
+ <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 the Torque
- <em>build.properties</em>.
+ specified in <em>project.properties</em>.
</td>
</tr>
<tr>
- <td>torque.database.bookstore.password</td>
+ <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
@@ -564,13 +611,86 @@
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>
-<p>
- That completes the configuration of Torque. You are now
- ready to start building your object model and creating
- your database.
-</p>
+<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>.
+ </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.
+ </p>
+ <p>
+ Next we will look <a href="step3.html">Invoking Torque</a>.
+ </p>
+
+</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
