db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r988290 - in /db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm: step1-ant.xml step3-ant.xml step6-ant.xml
Date Mon, 23 Aug 2010 20:19:23 GMT
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
+  &#145;BUILD SUCCESSFUL&#146; 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
+  &#145;BUILD SUCCESSFUL&#146;.  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


Mime
View raw message