Torque ORM Tutorial - Step 1: Configuring the Torque generation process using Ant

Delivered-To: mailing list torque-dev@db.apache.org Received: (qmail 4471 invoked by uid 500); 23 Aug 2010 20:21:01 -0000 Received: (qmail 4468 invoked by uid 99); 23 Aug 2010 20:21:01 -0000 Received: from Unknown (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 23 Aug 2010 20:21:01 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 23 Aug 2010 20:20:42 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 546392388A3B; Mon, 23 Aug 2010 20:19:23 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: torque-commits@db.apache.org From: tfischer@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20100823201923.546392388A3B@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 @@ + + + + + + Torque ORM Tutorial - Step 1: Configuring the Torque generation process using Ant + Pete Kazmier + Scott Eade + Thomas Fischer + + + +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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): +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + +

+ This build file contains the following definitions: +

+ 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) +
+ The definition configuration of the Torque ant task +
+ The configuration of ant's SQL task + (needed if you want to execute the generated SQL using ant) +
+ The configuration of the java compiler + (needed when you compile the generated java sources) +
+ The configuration of the clean target (removes the compiled classes, + some generated classes and the generated SQL). +
+ The configuration of the main target (generates classes and SQL + and compiles the java classes). +

+ 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. +

+ +

+ 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: +

+ Create the directory lib/ant in your project. +
+ Download the binary distribution of torque-ant-tasks + and put all libraries from the lib directory + in the lib/ant directory of your project. +
+ Download the appropriate mysql driver jar, e.g. from + here + and add the jar to the lib/ant directory of your project. +

+ +

+ This completes the configuration of the Torque ant tasks + (and other settings to be made in the build.xml). +

+ Next we will look at + Defining the database schema. +

+ +

+ User comments + for this step +

+ + + 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 @@ + + + + + + Torque Tutorial - Step 3: Invoking the Torque Ant task + Pete Kazmier + Scott Eade + Thomas Fischer + + + +

+ +

+ 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. +

+ +

+ 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). +

+ +

+ The object model consists of four classes for each + table in your schema. For example, the + author table, defined in this tutorial, + will result in the following four classes: + Author, AuthorPeer, + BaseAuthor, and BaseAuthorPeer (a + discussion on the use of these classes is deferred + until we write our sample application). +

+ +

+ To generate your object model and the associated SQL, type the + following command in your top-level project directory: +

+ + + +

+ A successful build will be indicated by the + ‘BUILD SUCCESSFUL’ message. +

+ +

+ The generated Java source files are located in the + target/generated-sources (BaseXXX) + and src/main/generated-java (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 + torque.om.package option you + specified in build.xml. +

+ +

+ The generated SQL files are located in the + target/generated-sql directory. + For each database schema in your + src/schema directory, there will be a + corresponding file with a .sql extension + instead of .xml 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. +

+ +

+ 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. +

+ +

+ 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. +

+ + + +

+ 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: +

+ + create database bookstore; + + +

+ 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: +

+ + + +

+ 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 + bookstore-schema.xml defined in this + tutorial should have created the following tables: + author, book, + and publisher. +

+ +

+ If you have difficulties in creating the tables + using ant, you can also execute the SQL script + generated in the directory target/generated-sql + manually. +

+ + + +

+ +

+ Now that you have generated all of your object model + classes and created your database, you are ready to + build your first Torque application. +

+ Next we will look Configuring the Torque Runtime. +

+ +

+ User comments + for this step +

+ + + 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 @@ + + + + + + Torque Tutorial - Step 6 - Compiling and Running the Sample Application + Pete Kazmier + Scott Eade + Thomas Fischer + + + + +

+ + + +

+ 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. +

+ +

+ + Note: There is no need to include the torque-generator + or torque-templates dependencies in your project. + +

+ + + + + + +

+ 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: +

+ + + +

+ 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. +

+ + + + + +

+ 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 target/classes. + To run the application, change into the root directory + of the application and type +

+ + + +

+ If all goes well, you should see the following + output: +

+ + + +

+ 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 + mailing list to your + advantage. +

+ + + +

+ +

+ 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! +

+ +

+ User comments + for this step +

+ + + --------------------------------------------------------------------- To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org For additional commands, e-mail: torque-dev-help@db.apache.org