You are viewing a plain text version of this content. The canonical link for it is here.
Posted to torque-dev@db.apache.org by tf...@apache.org on 2010/08/20 08:28:44 UTC
svn commit: r987386 - in
/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial: index.xml
orm/step1-maven.xml orm/step1.xml orm/step2.xml orm/step3-maven.xml
orm/step3.xml orm/step4.xml orm/step5.xml orm/step6-maven.xml orm/step6.xml
Author: tfischer
Date: Fri Aug 20 06:28:44 2010
New Revision: 987386
URL: http://svn.apache.org/viewvc?rev=987386&view=rev
Log:
improved ORM tutorial for Torque 4
Added:
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-maven.xml
- copied, changed from r983438, db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-maven.xml
- copied, changed from r983438, db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-maven.xml
- copied, changed from r983438, db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6.xml
Removed:
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6.xml
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/index.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step4.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step5.xml
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/index.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/index.xml?rev=987386&r1=987385&r2=987386&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/index.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/index.xml Fri Aug 20 06:28:44 2010
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -19,16 +19,144 @@
-->
<document>
-
<properties>
<title>Torque 4 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>
- <section name="Torque 4 Tutorial">
- <p>
- Sorry, the tutorial for Torque4 does not yet exist.
- </p>
- </section>
+
+<section name="About this Tutorial">
+
+<p>
+ This tutorial is intended to give first-time users an
+ introduction to using Torque. Torque has two primary foci: It is a
+ tool for java code generation and, building on top of that, it provides
+ object-relational mapping (ORM) for database access in java.
+ These two aspects are treated in different parts of this tutorial;
+ the two parts can be read independently of each other.
+</p>
+
+<p>
+ Both parts include how to obtain and install the relevant parts of Torque.
+ The ORM part then contains setting up a database
+ and writing a sample application to demonstrate the power of Torque.
+ The code generation part shows how the Torque generator can be used
+ for custom code generation.<br/>
+ The tutorial is not a reference. Refer to the
+ <a href="../documentation/modules/templates/index.html">Torque templates documentation</a>
+ and
+ <a href="../documentation/modules/runtime/index.html">Torque runtime documentation</a>
+ for more detailed information about the ORM part, and to the
+ <a href="../documentation/modules/generator/index.html">Torque generator documentation</a>
+ for the generator part.
+</p>
+
+<p>
+ In this tutorial, it is assumed that you have experience
+ in programming in Java. It is also assumed that you have already been using
+ either <a href="http://ant.apache.org">ant</a> or
+ <a href="http://maven.apache.org">maven2</a>. If you do not know one of these
+ build systems, please look at one of the introductions at their home pages.
+ It is expected that you have a working installation of the
+ JDK, Version 1.5 or higher.
+ <br/>
+ The ORM part further assumes that you have some experience using JDBC
+ (e.g. you should know what a jdbc driver and a connection URL is).
+</p>
+
+<p>
+ For each step in the tutorial, user comments are available
+ in the
+ <a href="http://wiki.apache.org/db-torque/">Torque Wiki</a>,
+ see the links at the bottom of each page.
+ If you had difficulties with a particular step and found
+ a solution, please write it up and add it to the corresponding
+ wiki page for each step.
+</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 samples running as they are.
+ 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
+ "Ok, it went wrong when I changed foo".<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 ORM part 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/mod_mbox/jakarta-turbine-user/200109.mbox/%3cBCAC8D6E905D234C84A49D1524A19CD1044FF7@bemail.BEDOMAIN.BEAP.COM%3e">
+ torque outside turbine - detailed example (long)</a>.
+</p>
+
+</section>
+
+<section name="Torque modules">
+<p>
+ Torque is divided into several parts, some of which can be used
+ independenty of other parts:
+ <ul>
+ <li>
+ The Torque generator is a general code generation tool. It reads input from
+ various sources, e.g. XML files or JDBC Metadata, and creates output
+ files (e.g. java files, sql files).
+ </li>
+ <li>
+ The Torque Maven plugin integrates the generator into
+ <a href="http://maven.apache.org">Maven 2</a>, a software
+ project management tool. In other words, the maven plugin is
+ a frontend for the generator.
+ </li>
+ <li>
+ The Torque ant tasks integrate the generator into
+ <a href="http://ant.apache.org">ant</a>, a java build tool.
+ </li>
+ <li>
+ The Torque templates use the Torque generator to generate
+ OR Mapping java classes which can access your database.
+ They also include SQL scripts to create all the necessary tables,
+ constraints etc. in your database.
+ The information about the database structure
+ is contained in an XML file read by the Torque generator,
+ which structure is also defined in the Torque templates.
+ </li>
+ <li>
+ The Torque runtime has to be included in ORM projects to use the classes
+ generated by the generator and the templates.
+ </li>
+ </ul>
+</p>
+</section>
+
+
+<section name="Where to next">
+
+<p>
+ For the ORM part, we will first look at
+ Configuring the Torque generation process.
+ If you are using maven 2 as build system, look at
+ <a href="orm/step1-maven.html">configuring Maven 2 for Torque</a>.
+ If you plan to use ant, look at
+ <a href="orm/step1-ant.html">configuring ant for Torque</a>
+ TODO: codegen part
+</p>
+
+</section>
+
+<section name="User Comments">
+ <a href="http://wiki.apache.org/db-torque/TutorialUserComments">User comments</a>
+ for the tutorial as a whole and this page
+</section>
+
</body>
</document>
+
Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-maven.xml (from r983438, db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-maven.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-maven.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1.xml&r1=983438&r2=987386&rev=987386&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-maven.xml Fri Aug 20 06:28:44 2010
@@ -20,105 +20,231 @@
<document>
<properties>
- <title>Torque Tutorial - Step 1: Installing Maven and the Torque Maven Plugin</title>
+ <title>Torque ORM Tutorial - Step 1: Configuring the Torque generation process using maven 2</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 1: Installing Maven 1 and the Torque Maven Plugin">
+<section name="Step 1: Configuring the Torque generation process">
<p>
- First of all, note that Torque is divided into four 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.
- The generator comes packaged in two jars: The templates in
- torque-gen-templates.jar, and the rest in torque-gen.jar.
- In this tutorial, you will not use the generator directly, but you
- will invoke it using the Maven 1 plugin. This also means that you do
- not have to download the generator separately from the maven 1 plugin.
- </li>
- <li>
- The Maven 1 plugin integrates the generator into
- <a href="http://maven.apache.org/maven1">Maven 1</a>, a software
- 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
- to work properly.
- </li>
- <li>
- There is also a Maven 2 plugin available, but this is not covered
- in this tutorial.
- </li>
- </ul>
- For this tutorial, we will be using the maven 1 plugin for Torque 3.3
- (which will silently invoke the generator) to
- generate our object model classes and sql scripts. For working with the
- generated classes, we will use the Torque 3.3 runtime for our
- sample application.
+ The following section outlines the necessary steps to
+ configure a Torque-based ORM project using maven.
+ For this, you need to create maven's pom file
+ (the maven project descriptor file) which describes your project.
+ It is recommended to run the tutorial against a mysql datanase, as
+ all of the explanation in this tutorial assumes that you use mysql.
</p>
<p>
- If you have not already done so, download and install
- <a href="http://maven.apache.org/maven-1.x">Maven 1</a>.
- It is highly recommended to use version 1.0.2 of Maven.
- You can not use the Torque Maven 1 plugin with Maven 2.
+ As a starting point, create a directory as a
+ base directory for your project (also called
+ the project's top level directory).
+ All the paths in the following steps will be
+ relative to this base directory.
</p>
+</section>
+
+<section name="Maven Project descriptor">
+
<p>
- Maven uses an online repository to download any libraries and
- resources it need. The default for this has been the
- <a href="http://www.ibiblio.org/maven">ibiblio maven repository</a>.
- However, this has been moved and now Maven 1.0.x is
- unable to find required dependencies without a minor configuration
- change. (For more information see
- <a href="http://maven.apache.org/maven-1.x/news.html">the Maven 1.1 Site.</a>)
-</p>
-<p>
- In order to find the files that Torque needs, you will need to create
- a file named project.properties in your user's home directory.
- e.g. C:\Documents and Settings\userid on Windows
- or ~userid on *nix. This file only needs the following line in it:
- <ul>
- maven.repo.remote=http://repo1.maven.org/maven
- </ul>
-</p>
-<p>Once you have done this, obtain the Torque maven plugin by typing:
+ As a starting point for the pom file in your project,
+ use the following template and edit it to reflect your specific needs (
+ typically you need to change the database, the database urls,
+ the database driver, the database host, the database user and password):
</p>
<source><![CDATA[
-maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.3
+<?xml version="1.0"?>
+<project
+ xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.apache.torque.tutorial</groupId>
+ <artifactId>torque-test</artifactId>
+ <packaging>jar</packaging>
+ <name>Torque Tutorial Test Project</name>
+ <version>1.0-SNAPSHOT</version>
+
+ <dependencies>
+ <!-- Torque runtime -->
+ <dependency>
+ <artifactId>torque-runtime</artifactId>
+ <groupId>org.apache.torque</groupId>
+ <version>4.0-alpha1-SNAPSHOT</version>
+ </dependency>
+
+ <!-- db driver -->
+ <dependency>
+ <artifactId>mysql-connector-java</artifactId>
+ <groupId>mysql</groupId>
+ <version>5.0.4</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>maven-torque-generator-plugin</artifactId>
+ <version>4.0-alpha1-SNAPSHOT</version>
+ <executions>
+ <execution>
+ <id>generate-sources</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <configuration>
+ <packaging>classpath</packaging>
+ <configPackage>org.apache.torque.templates.om</configPackage>
+ <sourceDir>src/main/schema</sourceDir>
+ <options>
+ <torque.om.package>org.apache.torque.tutorial.om</torque.om.package>
+ <torque.database>mysql</torque.database>
+ </options>
+ </configuration>
+ </execution>
+ <execution>
+ <id>generate-sql</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <configuration>
+ <packaging>classpath</packaging>
+ <configPackage>org.apache.torque.templates.sql</configPackage>
+ <sourceDir>src/main/schema</sourceDir>
+ <newFileTargetDir>target/generated-sql</newFileTargetDir>
+ <newFileTargetDirUsage>none</newFileTargetDirUsage>
+ <options>
+ <torque.database>mysql</torque.database>
+ </options>
+ </configuration>
+ </execution>
+ </executions>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>torque-templates</artifactId>
+ <version>4.0-alpha1-SNAPSHOT</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>sql-maven-plugin</artifactId>
+ <version>1.4</version>
+ <configuration>
+ <driver>org.gjt.mm.mysql.Driver</driver>
+ <url>jdbc:mysql://localhost:3306/bookstore</url>
+ <username>root</username>
+ <password>password</password>
+ <onError>continue</onError>
+ <autocommit>true</autocommit>
+ <fileset>
+ <basedir>${basedir}/target/generated-sql</basedir>
+ <includes>
+ <include>*.sql</include>
+ </includes>
+ </fileset>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <artifactId>mysql-connector-java</artifactId>
+ <groupId>mysql</groupId>
+ <version>5.0.4</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+
+ <plugin>
+ <!-- setting java version to 1.5 -->
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.5</source>
+ <target>1.5</target>
+ </configuration>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy-dependencies</id>
+ <phase>package</phase>
+ <goals>
+ <goal>copy-dependencies</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
]]></source>
<p>
- 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.
+ This template contains the following definitions:
+</p>
+<ul>
+ <li>
+ The runtime dependencies of your project to Torque
+ in the main dependencies section of the pom
+ (needed when you compile and use the generated java sources)
+ </li>
+ <li>
+ The configuration of the Torque maven 2 plugin in the plugins section
+ </li>
+ <li>
+ The configuration of the maven SQL plugin in the plugins section
+ (needed if you want to execute the generated SQL using maven)
+ </li>
+ <li>
+ The configuration of the java compiler in the plugins section
+ to allow java 1.5 code
+ (needed when you compile the generated java sources)
+ </li>
+ <li>
+ The configuration of the maven dependency plugin in the plugins section
+ (gathers all dependency libraries of the project).
+ </li>
+</ul>
+<p>
+ Configuring Maven 2 correctly is very important.
+ This enablee the Torque generator 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 this file.
</p>
</section>
<section name="Where to next">
-<p>
- Next we will look at <a href="step2.html">Configuring the Torque generator</a>.
-</p>
+ <p>
+ This completes the configuration of the Torque Maven 2 plugin
+ (and other settings to be made in the pom.xml).
+ </p>
+ <p>
+ Next we will look at
+ <a href="step2.html">Defining the database schema</a>.
+ </p>
</section>
<section name="User Comments">
- <a href="http://wiki.apache.org/db-torque/TutorialUserCommentsStep1">User comments</a>
+ <a href="http://wiki.apache.org/db-torque/TutorialUserCommentsStep2">User comments</a>
for this step
</section>
-
</body>
</document>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml?rev=987386&r1=987385&r2=987386&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml Fri Aug 20 06:28:44 2010
@@ -20,117 +20,14 @@
<document>
<properties>
- <title>Torque Tutorial - Step 2: Configuring the Torque generation process</title>
+ <title>Torque ORM Tutorial - Step 2: Defining the database schema</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 the Torque generation process">
-
-<p>
- The following section outlines the necessary steps to
- define your database schema and configure the Torque maven 1 plugin
- 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 maven 1 plugin can
- generate and execute all of the appropriate SQL commands
- to create your database, freeing you from having to do it
- manually.
-</p>
-
-<p>
- To accomplish all of the above, you need to
- create/edit the Torque maven 1 plugin properties file
- (which is providing the maven 1 plugin 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 Maven 1 Plugin Properties">
-
-<p>
- The maven 1 plugin generates Java
- source/class files representing your object model,
- SQL statements for your specific database, and
- documentation.
- You configure the maven 1 plugin by setting properties in the
- <em>project.properties</em> file in root directory of your
- project. As a starting point, use the following template
- and edit it to reflect your specific needs (
- typically you need to change the database, the database urls,
- the database driver, the database host, the database user and password):
-</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
-]]></source>
-
-<p>
- Setting these properties correctly is very
- 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>
-
-<p>
- The properties that can be used in the maven 1 plugin are identical to those
- that can be used in the ant-based generator.
- 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>
-
-</section>
-
-<section name="Torque Database Schema">
+<section name="Step 2: Defining the Torque Database Schema">
<p>
The second file that you must edit to configure
@@ -143,18 +40,12 @@
</p>
<p>
- 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
- 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. The name of
+ Your database schema file is typically located in the
+ <em>src/main/schema</em> directory under the base of your project.
+ In this directory, you will create the file <em>project-schema.xml</em>
+ which defines your database schema. The name of
your database schema file must end with
- ‘-schema.xml’ because Torque will only
+ ‘schema.xml’ because Torque will only
generate object models for files ending with that
pattern.
</p>
@@ -177,12 +68,12 @@
</p>
<source><![CDATA[
-<!DOCTYPE database SYSTEM
- "http://db.apache.org/torque/dtd/database_3_3.dtd">
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!-- TODO: add xsd schema definition here -->
<database
name="bookstore"
- defaultIdMethod="idbroker">
+ defaultIdMethod="native">
<table name="publisher" description="Publisher Table">
<column
@@ -265,13 +156,9 @@
<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 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
+ must be the same as the database's' name in the runtime property file
+ <em>torque.properties</em> described later in this tutorial.
+ Failure to do so will prevent your object
model from working properly.
</p>
@@ -298,7 +185,7 @@
Instructs Torque to use its
<a href="../runtime/reference/relevant-classes.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.
+ An extra table is used for this, which needs to be created separately.
</td>
</tr>
<tr>
@@ -306,14 +193,14 @@
<td>
Instructs Torque to use the underlying
database's mechanism to generate IDs (varies
- per database).
+ per database e.g. autoincrement for mysql and schemata for postgresql).
</td>
</tr>
<tr>
<td>none</td>
<td>
- Instructs Torque to not generate IDs. This
- can be useful in some situations.
+ Instructs Torque to not generate IDs.
+ Use this setting if you want to define the primary key yourself.
</td>
</tr>
</table>
@@ -331,54 +218,12 @@
<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
- <a href="../generator/database.dtd.txt">DTD</a>
- for the database schema. In addition, you must
+ attributes must be specified according to the TODO
+ <a href="TODO">DTD</a>
+ for the database schema. In addition, you should
include the XML declaration and DTD specification in
- your database schema file. Failure to do so can
- result in errors.
-</p>
-
-<p>
- 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[
-<!DOCTYPE database SYSTEM
- "http://db.apache.org/torque/dtd/database_3_2.dtd">
-
-<database name="bookstore">
- <table name="ID_TABLE" idMethod="idbroker">
- <column
- name="ID_TABLE_ID"
- required="true"
- primaryKey="true"
- type="INTEGER"/>
- <column
- name="TABLE_NAME"
- required="true"
- size="255"
- type="VARCHAR"/>
- <column
- name="NEXT_ID"
- type="INTEGER"/>
- <column
- name="QUANTITY"
- type="INTEGER"/>
- <unique>
- <unique-column name="TABLE_NAME"/>
- </unique>
- </table>
-</database>
-]]></source>
-
-<p>
- 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>.
+ your database schema file.
+ This helps to detect errors in the schema file easily.
</p>
<p>
@@ -399,8 +244,10 @@
and creating your database.
</p>
<p>
- Next we will look at
- <a href="step3.html">Invoking the Torque Maven 1 plugin</a>.
+ Maven users should look at
+ <a href="step3-maven.html">Invoking the Torque Maven plugin</a>,
+ wheras ant users should go to
+ <a href="step3-ant.html">Invoking the ant build containing Torque</a>.
</p>
</section>
Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-maven.xml (from r983438, db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-maven.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-maven.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3.xml&r1=983438&r2=987386&rev=987386&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-maven.xml Fri Aug 20 06:28:44 2010
@@ -20,42 +20,31 @@
<document>
<properties>
- <title>Torque Tutorial - Step 3: Invoking the Torque Maven 1 Plugin</title>
+ <title>Torque Tutorial - Step 3: Invoking 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>
<body>
-<section name="Step 3: Invoking the Torque Maven 1 Plugin">
+<section name="Step 3: Invoking the Torque Maven Plugin">
<p>
- With the configuration of the Torque Maven 1 Plugin completed, you can now
- generate the object model to support your database, and
- optionally create your database and all of its associated tables.
+ With the configuration of maven and definition of the
+ database schema completed, you can now
+ generate the object model to support your database,
+ and create the database tables.
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="../generator/index.html">Generator documentation</a>
- for details.
-</p>
-
-</section>
-
-<section name="Generating the Object Model and Associated SQL">
-
-<p>
The generation of your object model will produce
- Java source files that can be used to represent your
- database. These classes enable you to create, edit,
+ Java source files that represent your database structure.
+ These classes enable you to create, edit,
delete, and select objects that represent rows in
your database tables. In addition, Torque will
generate SQL to create your database tables (you
- have the option of executing the SQL as demonstrated
+ have the option of executing the SQL via maven as demonstrated
later in this tutorial).
</p>
@@ -76,7 +65,7 @@
</p>
<source><![CDATA[
-maven torque
+mvn generate-sources
]]></source>
<p>
@@ -85,18 +74,25 @@ maven torque
</p>
<p>
- The generated Java classes are located in the
- <em>src/java</em> directory and will be in a
- directory hierarchy matching that of the
+ The generated Java source files are located in the
+ <em>target/generated-sources</em> (BaseXXX)
+ and <em>src/main/generated-java</em> (other classes)
+ directories. The locations are split because the Base classes are
+ generated each time anew, are not intended to be edited
+ and should not be under version control if you use a version
+ control system. So they reside in maven's target directory
+ which can be deleted during a maven build.
+ The other classes can be edited once generated
+ and will not be overwritten if they exist, so they reside in the
+ src tree which is not altered by maven.
+ All generated classes 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.
+ specified in <em>pom.xml</em>.
</p>
<p>
The generated SQL files are located in the
- <em>target/sql</em> directory.
+ <em>target/generated-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
@@ -107,221 +103,85 @@ maven torque
</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
- sure it conforms to the
- <a href="../generator/schema-reference.html">
- Torque Schema Reference</a>.
+ schema file or the Maven 2 pom file file.
+ Check again the contents of these files.
</p>
</section>
-<section name="Creating the Database and Tables">
+<section name="Creating the Database Tables">
<p>
As mentioned previously, Torque can automatically
- 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>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 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.
+ create the database tables for you.
+ However, you must first make sure
+ that the appropriate database driver can be accessed by maven.
+ This is not a problem for most drivers
+ (e.g. mysql, postgresql, derby...)
+ but some drivers (e.g. oracle) are not available
+ in the maven central repository and must be added
+ to your local maven repository manually
+ (check the maven 2 docs on how to do this.)
</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.)
+ There are two places where the database driver appears:
+ once in the main dependencies section,
+ and once in the dependencies of the maven sql plugin
+ which can execute the sql generated by Torque.
</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[
-<project>
- <pomVersion>3</pomVersion>
- <groupId>torque</groupId>
- <id>torque-tutorial</id>
- <name>Torque</name>
- <currentVersion>3.3</currentVersion>
-
- <dependencies>
- <dependency>
- <artifactId>${artifactId}</artifactId>
- <groupId>${groupId}</groupId>
- <version>${version}</version>
- </dependency>
- </dependencies>
-</project>
-]]></source>
-
-<p>
- Replace the variables ${artifactId},
- ${groupId} and ${version} by the values
- needed to locate the driver jar. These variables
- must be chosen such that 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 you use the mysql 5.0.4 driver,
- <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>5.0.4</code> in the <em>project.xml</em>.
+ The tutorial uses mysql as database, and the pom templates
+ gicen in step 1 already include a mysql dependency,
+ so the pom xml in the tutorial project can remain unchanged.
</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!
- You should skip this step if you are working
- with an existing database full of data.
- </b>
-</p>
-
-<p>
- To create your database, type the following command
- in the top-level directory of your project:
-</p>
-
-<source><![CDATA[
-maven torque:create-db
-]]></source>
-
-<p>
- Note that creating the database might not work
- 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).
-</p>
+<subsection name="Creating the tables">
<p>
- If you encounter problems in this step,
- one possible reason might be a misconfiguration
- 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 a database. In either
- case, refer to the section above that explains the
- <em>project.properties</em> file.
- If the problems persist, skip this step
- and create the database manually.
-</p>
-
-</subsection>
-
-<subsection name="Creating the tables">
+ To create the database tables, you first need to create the schema
+ (mysql: database) which you want to use for the tables.
+ E.g. in mysql, execute the following command as root user:
+</p>
+<source>
+ create database bookstore;
+</source>
<p>
- To create your tables, type the following commands in
+ If you want to use another database user than root to create the tables,
+ make sure that this user has sufficient privileges on the database bookstore
+ to create tables. Alternatively, you can just use the root user
+ to create the database tables.
+ In both cases, type the following commands in
the top-level directory of your project:
</p>
<source><![CDATA[
-maven torque:id-table-init-sql
-maven torque:insert-sql
+maven sql:execute
]]></source>
<p>
- Note: if this tutorial had not utilized Torque's
- <em>idbroker</em> method (as described earlier), it
- would not have been necessary to execute the
- <em>id-table-init-sql</em> target.
-</p>
-
-<p>
- Success will be indicated by the ‘BUILD
- SUCCESSFUL’ message. You can also validate
+ Success will be indicated by the message
+ 8 of 8 SQL statements executed successfully
+ ‘BUILD SUCCESSFUL’. You can also validate
this by checking your database. For example, the
- <em>bookstore-schema.xml</em> and
- <em>id-table-schema.xml</em>, defined in this
- tutorial, should have created a database called
- <em>bookstore</em>, with the following tables:
- <em>ID_TABLE</em>, <em>author</em>, <em>book</em>,
+ <em>bookstore-schema.xml</em> defined in this
+ tutorial should have created the following tables:
+ <em>author</em>, <em>book</em>,
and <em>publisher</em>.
</p>
<p>
If you have difficulties in creating the tables
- using maven, you can also execute the SQL scripts
- generated in the directory <em>target/sql</em>
+ using maven, you can also execute the SQL script
+ generated in the directory <em>target/generated-sql</em>
manually.
</p>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step4.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step4.xml?rev=987386&r1=987385&r2=987386&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step4.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step4.xml Fri Aug 20 06:28:44 2010
@@ -31,160 +31,21 @@
<p>
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.
+ configure the runtime environment of Torque.
+ The Torque runtime needs a configuration file
+ in order to retrieve the data which is necessary
+ to connect to the database.
</p>
-</section>
-
-<section name="Setting up the classpath">
-
-<p>
- 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 <dependencies>
- section of your <em>project.xml</em>
-</p>
-<source><![CDATA[
- <dependency>
- <artifactId>torque</artifactId>
- <groupId>torque</groupId>
- <version>3.3</version>
- </dependency>
-
- <dependency>
- <groupId>avalon-framework</groupId>
- <artifactId>avalon-framework-api</artifactId>
- <version>4.3</version>
- <url>http://avalon.apache.org/</url>
- </dependency>
-
- <dependency>
- <groupId>avalon-logkit</groupId>
- <artifactId>avalon-logkit</artifactId>
- <version>2.1</version>
- <type>jar</type>
- </dependency>
-
- <dependency>
- <groupId>commons-beanutils</groupId>
- <artifactId>commons-beanutils-core</artifactId>
- <version>1.7.0</version>
- <url>http://commons.apache.org/beanutils/</url>
- </dependency>
-
- <dependency>
- <groupId>commons-collections</groupId>
- <artifactId>commons-collections</artifactId>
- <version>3.2</version>
- <url>http://commons.apache.org/collections/</url>
- </dependency>
-
- <dependency>
- <groupId>commons-configuration</groupId>
- <artifactId>commons-configuration</artifactId>
- <version>1.4</version>
- <url>http://commons.apache.org/configuration/</url>
- </dependency>
-
- <dependency>
- <groupId>commons-dbcp</groupId>
- <artifactId>commons-dbcp</artifactId>
- <version>1.2.2</version>
- <url>http://commons.apache.org/dbcp/</url>
- </dependency>
-
- <dependency>
- <groupId>commons-lang</groupId>
- <artifactId>commons-lang</artifactId>
- <version>2.3</version>
- <url>http://commons.apache.org/lang/</url>
- </dependency>
-
- <dependency>
- <groupId>commons-logging</groupId>
- <artifactId>commons-logging</artifactId>
- <version>1.1</version>
- <url>http://commons.apache.org/logging/</url>
- </dependency>
-
- <dependency>
- <groupId>commons-pool</groupId>
- <artifactId>commons-pool</artifactId>
- <version>1.3</version>
- <url>http://commons.apache.org/pool/</url>
- </dependency>
-
- <dependency>
- <groupId>jcs</groupId>
- <artifactId>jcs</artifactId>
- <version>1.3</version>
- <url>http://jakarta.apache.org/jcs/</url>
- </dependency>
-
- <dependency>
- <artifactId>village</artifactId>
- <groupId>torque</groupId>
- <version>3.3</version>
- </dependency>
-
- <dependency>
- <groupId>xerces</groupId>
- <artifactId>xercesImpl</artifactId>
- <version>2.6.2</version>
- <url>http://xerces.apache.org/xerces2-j/</url>
- </dependency>
-
- <dependency>
- <groupId>xml-apis</groupId>
- <artifactId>xml-apis</artifactId>
- <version>2.0.2</version>
- <url>http://xml.apache.org/commons/</url>
- </dependency>
-
-]]></source>
-
-<p>
- You don't need to 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="Torque Runtime Properties">
+<subsection name="Torque Runtime Properties">
<p>
The second step in the configuration of the
Torque Runtime are the
- Torque run-time properties. As the name suggests,
+ Torque runtime 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
+ The runtime properties control database
parameters such as drivers, usernames, and
passwords. These properties can be saved in any
file because your application must explicitly
@@ -195,7 +56,7 @@
<p>
We will save our runtime properties in the
a file called <em>torque.properties</em>.
- Create a subdirectory src/conf in the
+ Create a subdirectory src/main/resources 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:
@@ -205,11 +66,10 @@
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.user = root
torque.dsfactory.bookstore.connection.password = password
]]></source>
@@ -289,31 +149,26 @@ torque.dsfactory.bookstore.connection.pa
Torque-generated object model classes at run-time.
</p>
-</section>
+</subsection>
-<section name="Logging configuration">
+<subsection name="Logging configuration">
<p>
Torque uses
<a href="http://commons.apache.org/logging/">
commons-logging</a> as a logging interface.
To enable logging in your application, read the
- <a href="http://commons.apache.org/logging/commons-logging-1.0.3/usersguide.html">
+ <a href="http://commons.apache.org/logging/commons-logging-1.1.1/guide.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
- "serious" application, logging is
- indispensible in order to track down any
- unexpected errors.
+ This example uses log4j as logging system and it is configured very simply
+ so that only warnings and errors are printed.
+ In a serious application, you want to improve the logging configuration.
</p>
+</subsection>
</section>
<section name="Where to next">
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step5.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step5.xml?rev=987386&r1=987385&r2=987386&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step5.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step5.xml Fri Aug 20 06:28:44 2010
@@ -32,8 +32,7 @@
<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!
+the power of Torque.
</p>
<p>
@@ -66,11 +65,11 @@ between the Peer classes (<em>BookPeer</
(<em>Book</em> and <em>BaseBook</em>), also known as
Data Objects? The Peer classes “wrap” 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,
+manipulate those tables such as <em>doSelect</em> and
+<em>doDelete</em>. Data Objects,
on the other hand, “wrap” individual rows
within those tables and provide getters/mutators for each
-column defined in those tables as well as the convenient
+column defined in those tables as well as a
<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
@@ -130,44 +129,6 @@ 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
@@ -237,10 +198,7 @@ tcpip.save();
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.
+ representing the rows of data selected.
</p>
<p>
@@ -257,7 +215,7 @@ tcpip.save();
<source><![CDATA[
Criteria crit = new Criteria();
-List books = BookPeer.doSelect(crit);
+List<Book> books = BookPeer.doSelect(crit);
]]></source>
<p>
@@ -269,9 +227,8 @@ List books = BookPeer.doSelect(crit);
</p>
<source><![CDATA[
-for (Iterator i = book.iterator(); i.hasNext();)
+for (Book book : books)
{
- Book book = (Book) i.next();
System.out.println("Title: " + book.getTitle() + "\n");
System.out.println("ISBN: " + book.getISBN() + "\n");
System.out.println("Publisher: " +
@@ -328,8 +285,6 @@ for (Iterator i = book.iterator(); i.has
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>
@@ -349,7 +304,7 @@ for (Iterator i = book.iterator(); i.has
<source><![CDATA[
Criteria crit = new Criteria();
crit.add(BookPeer.ISBN, "0-618-12902-2");
-List books = BookPeer.doSelect(crit);
+List<Book> books = BookPeer.doSelect(crit);
]]></source>
<p>
@@ -389,31 +344,6 @@ 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 ‘TCP/IP
- Illustrated’ book:
-</p>
-
-<source><![CDATA[
-tcpip.setAuthor(bloch);
-BookPeer.doUpdate(tcpip);
-]]></source>
-
-<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">
@@ -529,10 +459,11 @@ PublisherPeer.doDelete(addison);
<source><![CDATA[
// Book.java
+package org.apache.torque.tutorial.om;
+
import org.apache.torque.TorqueException;
-public class Book
- extends com.kazmier.om.BaseBook
+public class Book extends BaseBook
{
public String toString()
{
@@ -552,8 +483,9 @@ public class Book
}
// Author.java
-public class Author
- extends com.kazmier.om.BaseAuthor
+package org.apache.torque.tutorial.om;
+
+public class Author extends BaseAuthor
{
public String toString()
{
@@ -562,8 +494,9 @@ public class Author
}
// Publisher.java
-public class Publisher
- extends com.kazmier.om.BasePublisher
+package org.apache.torque.tutorial.om;
+
+public class Publisher extends BasePublisher
{
public String toString()
{
@@ -594,7 +527,7 @@ import org.apache.torque.util.Criteria;
public class BookPeer
extends com.kazmier.om.BaseBookPeer
{
- public static List doSelectAll() throws TorqueException
+ public static List<Book> doSelectAll() throws TorqueException
{
Criteria crit = new Criteria();
return doSelect(crit);
@@ -609,7 +542,7 @@ import org.apache.torque.util.Criteria;
public class AuthorPeer
extends com.kazmier.om.BaseAuthorPeer
{
- public static List doSelectAll() throws TorqueException
+ public static List<Author> doSelectAll() throws TorqueException
{
Criteria crit = new Criteria();
return doSelect(crit);
@@ -624,7 +557,7 @@ import org.apache.torque.util.Criteria;
public class PublisherPeer
extends com.kazmier.om.BasePublisherPeer
{
- public static List doSelectAll() throws TorqueException
+ public static List<Publisher> doSelectAll() throws TorqueException
{
Criteria crit = new Criteria();
return doSelect(crit);
@@ -655,10 +588,10 @@ public class PublisherPeer
</p>
<source><![CDATA[
-package com.kazmier;
+package org.apache.torque.tutorial;
import java.util.*;
-import com.kazmier.om.*;
+import org.apache.torque.tutorial.om.*;
import org.apache.torque.Torque;
import org.apache.torque.util.Criteria;
@@ -671,7 +604,9 @@ public class Bookstore
/*
* Initializing Torque
*/
+ TODO read from classpath
Torque.init("torque.properties");
+ TODO init logging
/*
* Creating new objects. These will be inserted into your database
@@ -719,7 +654,7 @@ public class Bookstore
* stdout using our helper method defined in BookPeer (doSelectAll).
*/
System.out.println("Full booklist:\n");
- List booklist = BookPeer.doSelectAll();
+ List<Book> booklist = BookPeer.doSelectAll();
printBooklist(booklist);
/*
@@ -780,11 +715,10 @@ public class Bookstore
/*
* Helper method to print a booklist to standard out.
*/
- private static void printBooklist(List booklist)
+ private static void printBooklist(List<Book> booklist)
{
- for (Iterator i = booklist.iterator(); i.hasNext();)
+ for (Book book : books)
{
- Book book = (Book) i.next();
System.out.println(book);
}
}
@@ -792,10 +726,10 @@ public class Bookstore
]]></source>
<p>
- Save this code in the <em>src/java</em>
+ Save this code in the <em>src/main/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>
+ placed in <em>src/main/java/com/kazmier</em>
directory because of its package definition. Your
application might go elsewhere depending on the
package that you've selected.
@@ -811,7 +745,9 @@ public class Bookstore
application.
</p>
<p>
- Next we will look <a href="step6.html">Compiling and Running the Sample Application</a>.
+ Next we will look at Compiling and Running the Sample Application.
+ Maven users please look <a href="step6-maven.html">here</a>, and ant users
+ please look <a href="step6-ant.html">here</a>
</p>
</section>
Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-maven.xml (from r983438, db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-maven.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-maven.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6.xml&r1=983438&r2=987386&rev=987386&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-maven.xml Fri Aug 20 06:28:44 2010
@@ -30,44 +30,51 @@
<section name="Step 6: Compiling and Running the sample application">
-<subsection name="Compiling the sample application">
+<subsection name="Setting up the classpath">
<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.
+ The libraries which the generated classes depend on
+ are specified in the file <em>pom.xml</em>
+ in the top level directory of the project.
+ You already created this file in step 1 of the
+ tutorial; and it already contains the dependencies
+ to the Torque runtime and the mysql driver,
+ so nothing needs to be changed there.
</p>
+
<p>
- First, we need to tell maven where the java source
- files are located. To do this, add the following section
- just after the <code><dependencies></code> of your
- <em>project.xml</em> which you created sooner on in the
- top level directory of your project:
+ <b>
+ Note: There is no need to include the torque-generator
+ or torque-templates dependencies in your project.
+ </b>
</p>
-<source><![CDATA[
- <build>
- <sourceDirectory>src/java</sourceDirectory>
- </build>
-]]></source>
+</subsection>
+
+
+<subsection name="Building the sample application">
<p>
- Afterwards, you can compile your jave source files
+ Now that you've generated your object model with
+ Torque, and created a sample application, you are
+ now ready to compile and build everything. Again, Maven is used
+ to control the build process.
+ You can build your application
by typing the following in the top-level directory
of your project:
</p>
<source><![CDATA[
-maven java:compile
+mvn package
]]></source>
<p>
If you've done everything correctly, this should
- build without any errors. All of the resulting Java
- class files are placed in the
- <em>target/classes</em> directory. If the compiler
- misses any external libraries, review the
+ build without any errors. This means all of the source files
+ will have been compiled to the target/classes folder
+ and all libraries on which your application depends on
+ will have been copied to the target/dependency folder.
+ If the compiler misses any external libraries, review the
<dependencies> section in your
<em>project.xml</em>. Should you
encounter other errors, go back and review your
@@ -82,63 +89,23 @@ maven java:compile
Before you run the sample application, you must
first set your classpath (this was done
automatically for you by Maven when you
- compiled). The classpath must include: all of the
- jars denoted in the <dependencies> section
- of your <em>project.xml</em>, and all of your
- application and object model classes located in
- <em>target/classes</em>.
-</p>
-
-<p>
- Before compiling your application,
- maven will have downloaded all libraries
- your project depends on to the local maven repository.
- Gathering them from there is a cumbersome process.
- To ease copying them into one place, we modify
- Maven's build process a little.
- For this, you need to create a new file called
- <em>maven.xml</em> in the top-level directory
- of your project. It needs to have the
- following content:
-</p>
-
-<source><![CDATA[
-<project xmlns:java="java" xmlns:deploy="deploy">
- <postGoal name="java:compile">
- <!-- include listed dependencies -->
- <deploy:copy-deps todir="${maven.build.dir}/lib"/>
- <!-- include torque.properties -->
- <copy file="src/conf/torque.properties" todir="${maven.build.dir}" />
- </postGoal>
-</project>
-]]></source>
-
-<p>
- After creating the file, re-run
+ compiled). The classpath must include most
+ of the jars in the target/dependency folder
+ (There are some jars which are transitive dependencies to other jars
+ which are not used, but there is no harm in including these).
+ The classpath alsmo must include all of your application
+ and object model classes located in <em>target/classes</em>.
+ To run the application, change into the target directory
+ of the application and type
</p>
<source><![CDATA[
-maven java:compile
-]]></source>
+linux:
+java -cp classes:dependency/commons-dbcp-1.2.2.jar:dependency/commons-collections-3.2.jar:dependency/commons-configuration-1.4.jar:dependency/commons-lang-2.3.jar:dependency/commons-logging-1.1.jar:dependency/commons-pool-1.3.jar:dependency/log4j-1.2.11.jar:dependency/mysql-connector-java-5.0.4.jar:dependency/torque-runtime-4.0-alpha1-SNAPSHOT.jar:dependency/village-3.3.jar org.apache.torque.tutorial.Bookstore
-<p>
- Now change into the target directory. In addition
- to the <em>classes</em> subdirectory which was
- already created in the first compilation run,
- you see that maven has generated an additional
- <em>lib</em> directory which contains the needed
- libraries, and that maven also copied the
- Torque.properties file here.
-</p>
+windows:
+java -cp classes;dependency/commons-dbcp-1.2.2.jar;dependency/commons-collections-3.2.jar;dependency/commons-configuration-1.4.jar;dependency/commons-lang-2.3.jar;dependency/commons-logging-1.1.jar;dependency/commons-pool-1.3.jar;dependency/log4j-1.2.11.jar;dependency/mysql-connector-java-5.0.4.jar;dependency/torque-runtime-4.0-alpha1-SNAPSHOT.jar;dependency/village-3.3.jar org.apache.torque.tutorial.Bookstore
-<p>
- Now everything is in one place, and you can start the
- application by typing (note:exchange the mysql-connector-java-5.0.4.jar
- by the datatbase driver jar you are using)
-</p>
-
-<source><![CDATA[
-java -cp classes:lib/avalon-framework-api-4.3.jar:lib/commons-beanutils-core-1.7.0.jar:lib/commons-collections-3.2.jar:lib/commons-configuration-1.4.jar:lib/commons-dbcp-1.2.2.jar:lib/commons-lang-2.3.jar:lib/commons-logging-1.1.jar:lib/commons-pool-1.3.jar:lib/jcs-1.3.jar:lib/mysql-connector-java-5.0.4.jar:lib/torque-3.3.jar:lib/village-3.3.jar com.kazmier.Bookstore
]]></source>
<p>
@@ -200,7 +167,7 @@ java -cp classes:lib/avalon-framework-ap
<section name="Where to Go From Here">
<p>
- Congratulations! You have completed the Torque
+ Congratulations! You have completed the Torque ORM
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
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org