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/23 22:19:23 UTC
svn commit: r988290 - in
/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm:
step1-ant.xml step3-ant.xml step6-ant.xml
Author: tfischer
Date: Mon Aug 23 20:19:22 2010
New Revision: 988290
URL: http://svn.apache.org/viewvc?rev=988290&view=rev
Log:
Added a first version of the ant part of the tutorial
Added:
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-ant.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-ant.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-ant.xml
Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-ant.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-ant.xml?rev=988290&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-ant.xml (added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step1-ant.xml Mon Aug 23 20:19:22 2010
@@ -0,0 +1,216 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<document>
+ <properties>
+ <title>Torque ORM Tutorial - Step 1: Configuring the Torque generation process using Ant</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: Configuring the Torque generation process">
+
+<p>
+ The following section outlines the necessary steps to
+ configure a Torque-based ORM project using ant.
+ For this, you need to create ant's build.xml file
+ and make the necessary libraries available.
+ 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>
+ 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="Ant build file">
+
+<p>
+ As a starting point for the build file in your project,
+ use the following template and save it
+ as build.xml in the project's base directory.
+ Then edit it to reflect your specific needs (
+ typically you need to change the database urls,
+ the database host, the database user and password):
+</p>
+
+<source><![CDATA[
+<?xml version="1.0"?>
+<project name="Torque" default="main" basedir=".">
+
+ <path id="ant-classpath">
+ <fileset dir="lib/ant">
+ <include name="*.jar"/>
+ </fileset>
+ </path>
+
+ <path id="runtime-classpath">
+ <fileset dir="lib/runtime">
+ <include name="*.jar"/>
+ </fileset>
+ </path>
+
+ <taskdef
+ name="torque-generator"
+ classpathref="ant-classpath"
+ classname="org.apache.torque.ant.task.TorqueGeneratorTask"/>
+
+ <target name="generate"
+ description="==> generates sql + om classes">
+ <torque-generator
+ packaging="classpath"
+ configPackage="org.apache.torque.templates.om"
+ sourceDir="src/main/schema">
+ <option key="torque.om.package" value="org.apache.torque.tutorial.om"/>
+ <option key="torque.database" value="mysql"/>
+ </torque-generator>
+ <torque-generator
+ packaging="classpath"
+ configPackage="org.apache.torque.templates.sql"
+ sourceDir="src/main/schema"
+ newFileTargetDir="target/generated-sql">
+ <option key="torque.database" value="mysql"/>
+ </torque-generator>
+ </target>
+
+ <target name="compile">
+ <mkdir dir="target/classes"/>
+ <javac debug="on" source="1.5" destdir="target/classes">
+ <src path="src/main/java"/>
+ <src path="src/main/generated-java"/>
+ <src path="target/generated-sources"/>
+ <classpath refid="runtime-classpath"/>
+ </javac>
+ <copy todir="target/classes">
+ <fileset dir="src/main/resources"/>
+ </copy>
+ </target>
+
+ <target name="execute-sql">
+ <sql classpathref="ant-classpath"
+ driver="org.gjt.mm.mysql.Driver"
+ url="jdbc:mysql://localhost:3306/bookstore"
+ userid="root"
+ password="mysql"
+ onerror="continue"
+ src="target/generated-sql/schema.sql"
+ />
+ </target>
+
+ <target name="clean">
+ <delete dir="target" />
+ </target>
+
+ <target name="main" description="build all" depends="generate, compile">
+ </target>
+</project>
+]]></source>
+
+<p>
+ This build file 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 definition configuration of the Torque ant task
+ </li>
+ <li>
+ The configuration of ant's SQL task
+ (needed if you want to execute the generated SQL using ant)
+ </li>
+ <li>
+ The configuration of the java compiler
+ (needed when you compile the generated java sources)
+ </li>
+ <li>
+ The configuration of the clean target (removes the compiled classes,
+ some generated classes and the generated SQL).
+ </li>
+ <li>
+ The configuration of the main target (generates classes and SQL
+ and compiles the java classes).
+ </li>
+</ul>
+<p>
+ A correct ant build file 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="Library set-up">
+<p>
+ For the Torque generator and SQL ant tasks to work correctly,
+ you need to provide them with some addidional libraries.
+ This is done as follows:
+</p>
+<ul>
+ <li>
+ Create the directory lib/ant in your project.
+ </li>
+ <li>
+ Download the binary distribution of torque-ant-tasks
+ and put all libraries from the lib directory
+ in the lib/ant directory of your project.
+ </li>
+ <li>
+ Download the appropriate mysql driver jar, e.g. from
+ <a href="http://repo1.maven.org/maven2/mysql/mysql-connector-java/">here</a>
+ and add the jar to the lib/ant directory of your project.
+ </li>
+</ul>
+
+</section>
+
+<section name="Where to next">
+
+ <p>
+ This completes the configuration of the Torque ant tasks
+ (and other settings to be made in the build.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/TutorialUserCommentsStep2">User comments</a>
+ for this step
+</section>
+
+ </body>
+</document>
Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-ant.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-ant.xml?rev=988290&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-ant.xml (added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step3-ant.xml Mon Aug 23 20:19:22 2010
@@ -0,0 +1,190 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<document>
+ <properties>
+ <title>Torque Tutorial - Step 3: Invoking the Torque Ant task</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 Ant Task">
+
+<p>
+ With the creation of the build file 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>
+ The generation of your object model will produce
+ 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 via maven as demonstrated
+ later in this tutorial).
+</p>
+
+<p>
+ The object model consists of four classes for each
+ table in your schema. For example, the
+ <em>author</em> table, defined in this tutorial,
+ will result in the following four classes:
+ <em>Author</em>, <em>AuthorPeer</em>,
+ <em>BaseAuthor</em>, and <em>BaseAuthorPeer</em> (a
+ discussion on the use of these classes is deferred
+ until we write our sample application).
+</p>
+
+<p>
+ To generate your object model and the associated SQL, type the
+ following command in your top-level project directory:
+</p>
+
+<source><![CDATA[
+ant generate
+]]></source>
+
+<p>
+ A successful build will be indicated by the
+ ‘BUILD SUCCESSFUL’ message.
+</p>
+
+<p>
+ 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 the target directory
+ which can be deleted for a clean build.
+ The other classes can be edited once generated
+ and will not be overwritten if they exist, so they reside in the
+ src tree.
+ All generated classes will be in a directory hierarchy matching that of the
+ <code>torque.om.package</code> option you
+ specified in <em>build.xml</em>.
+</p>
+
+<p>
+ The generated SQL files are located in the
+ <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
+ instead of <em>.xml</em> extension. The contents of
+ these files are the SQL commands that can be used to
+ manually or automatically (see next section) create
+ your database tables.
+</p>
+
+<p>
+ If you encounter errors while building, it is more
+ than likely a formatting error of your database
+ schema file or the ant build file, or a missing library.
+ Check again the contents of these files and the lib/ant directory.
+</p>
+
+</section>
+
+<section name="Creating the Database Tables">
+
+<p>
+ As mentioned previously, Torque can automatically
+ create the database tables for you.
+ However, you must first make sure
+ that the appropriate database driver can be accessed by ant.
+ We already did that by adding the mysql driver jar
+ to the lib/ant directory of your project.
+</p>
+
+<subsection name="Creating the tables">
+
+<p>
+ 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>
+ 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[
+ant execute-sql
+]]></source>
+
+<p>
+ 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> 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 ant, you can also execute the SQL script
+ generated in the directory <em>target/generated-sql</em>
+ manually.
+</p>
+
+</subsection>
+
+</section>
+
+<section name="Where to next">
+
+ <p>
+ Now that you have generated all of your object model
+ classes and created your database, you are ready to
+ build your first Torque application.
+ </p>
+ <p>
+ Next we will look <a href="step4.html">Configuring the Torque Runtime</a>.
+ </p>
+
+</section>
+
+<section name="User Comments">
+ <a href="http://wiki.apache.org/db-torque/TutorialUserCommentsStep3">User comments</a>
+ for this step
+</section>
+
+ </body>
+</document>
Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-ant.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-ant.xml?rev=988290&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-ant.xml (added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step6-ant.xml Mon Aug 23 20:19:22 2010
@@ -0,0 +1,183 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<document>
+ <properties>
+ <title>Torque Tutorial - Step 6 - Compiling and Running the Sample Application</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 6: Compiling and Running the sample application using ant">
+
+<subsection name="Setting up the classpath">
+
+<p>
+ The libraries which the generated classes depend on
+ can be found in the binary distribution of the torque-runtime module.
+ To add these dependencies to your project,
+ create the directory lib/runtime
+ in the top level directory of the project.
+ Add all libraries from the lib dir of the torque-runtime binary distribution
+ and also the torque-runtime.jar from there.
+ Additionally copy the mysql driver jar from lib/ant to lib/runtime.
+</p>
+
+<p>
+ <b>
+ Note: There is no need to include the torque-generator
+ or torque-templates dependencies in your project.
+ </b>
+</p>
+
+</subsection>
+
+
+<subsection name="Building the sample application">
+
+<p>
+ 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, ant 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[
+ant
+]]></source>
+
+<p>
+ If you've done everything correctly, this should
+ build without any errors. This means all of the source files
+ will have been compiled to the target/classes folder.
+ If the compiler misses any external libraries, review your
+ application code and the libraries in lib/runtime.
+</p>
+
+</subsection>
+
+<subsection name="Running the sample application">
+
+<p>
+ Before you run the sample application, you must
+ first set your classpath. The classpath must include most
+ of the jars in the lib/runtime 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 almo must include all of your application
+ and object model classes located in <em>target/classes</em>.
+ To run the application, change into the root directory
+ of the application and type
+</p>
+
+<source><![CDATA[
+linux:
+java -cp target/classes:lib/runtime/commons-beanutils-1.7.0.jar:lib/runtime/commons-dbcp-1.2.2.jar:lib/runtime/commons-collections-3.2.jar:lib/runtime/commons-configuration-1.4.jar:lib/runtime/commons-lang-2.3.jar:lib/runtime/commons-logging-1.1.jar:lib/runtime/commons-pool-1.3.jar:lib/runtime/log4j-1.2.11.jar:lib/runtime/mysql-connector-java-5.0.4.jar:lib/runtime/torque-runtime-4.0-alpha1-SNAPSHOT.jar:lib/runtime/village-3.3.jar org.apache.torque.tutorial.Bookstore
+
+windows:
+java -cp target/classes;lib/runtime/commons-beanutils-1.7.0.jar;lib/runtime/commons-dbcp-1.2.2.jar;lib/runtime/commons-collections-3.2.jar;lib/runtime/commons-configuration-1.4.jar;lib/runtime/commons-lang-2.3.jar;lib/runtime/commons-logging-1.1.jar;lib/runtime/commons-pool-1.3.jar;lib/runtime/log4j-1.2.11.jar;lib/runtime/mysql-connector-java-5.0.4.jar;lib/runtime/torque-runtime-4.0-alpha1-SNAPSHOT.jar;lib/runtime/village-3.3.jar org.apache.torque.tutorial.Bookstore
+
+]]></source>
+
+<p>
+ If all goes well, you should see the following
+ output:
+</p>
+
+<source><![CDATA[
+ Full booklist:
+
+ Title: TCP/IP Illustrated, Volume 1
+ ISBN: 0-201-63346-9
+ Publisher: Addison Wesley Professional
+ Author: Stevens, W.
+
+ Title: Effective Java
+ ISBN: 0-618-12902-2
+ Publisher: Addison Wesley Professional
+ Author: Bloch, Joshua
+
+ Booklist (specific ISBN):
+
+ Title: TCP/IP Illustrated, Volume 1
+ ISBN: 0-201-63346-9
+ Publisher: Addison Wesley Professional
+ Author: Stevens, W.
+
+ Booklist (authors swapped):
+
+ Title: TCP/IP Illustrated, Volume 1
+ ISBN: 0-201-63346-9
+ Publisher: Addison Wesley Professional
+ Author: Bloch, Joshua
+
+ Title: Effective Java
+ ISBN: 0-618-12902-2
+ Publisher: Addison Wesley Professional
+ Author: Stevens, W.
+
+ Booklist (should be empty):
+]]></source>
+
+<p>
+ If your application throws an exception, it could be
+ for one of many reasons, most of which are not very
+ descriptive unfortunately. Do not be discouraged if your
+ application does not run the first time. Carefully
+ retrace all of the steps outlined in this tutorial.
+ If you are still not able to get your application to
+ run, use the Torque user
+ <a href="../../../mail-lists.html">mailing list</a> to your
+ advantage.
+</p>
+
+</subsection>
+
+</section>
+
+<section name="Where to Go From Here">
+
+<p>
+ 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
+ seeking additional information, there are several other
+ documents on this site that can provide details on
+ various subjects. Lastly, the source code is an
+ invaluable resource when all else fails to provide
+ answers!
+</p>
+
+</section>
+
+<section name="User Comments">
+ <a href="http://wiki.apache.org/db-torque/TutorialUserCommentsStep6">User comments</a>
+ for this step
+</section>
+
+ </body>
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org