turbine-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steve Davis" <steve.da...@digitalevergreen.com>
Subject torque outside turbine - detailed example (long)
Date Tue, 25 Sep 2001 05:37:00 GMT
I spent the day today figuring out how to use Torque a stand alone
(non-turbine) application.  It was not hard once I figured out
where all the config files were and how to initialize torque without
using turbine.  I was documenting it for myself so I wouldn't forget
and decided to expand my notes a little bit and put it out to the
mailing list in the hopes that other new users might find it helpful.  

Let me preface by saying I am not real experienced in using databases 
or torque so I am sure there are better ways to do things or things 
I might have left out. But I tried to be detailed in all my steps and
this test worked for me.  If anyone wants to use this as a starting
point and expand on it or xdoc it, feel free. I did this under Redhat 
Linux 7.1 using the bash shell.  Windows users adjust the commands 
accordingly.

Almost everything in here assumes that you have the ant and cvs 
commands in your PATH enviroment variable.


Step 1) Build torque
---------------------
Download torque source. I do all my downloads under a directory called
projects.

> cd  ~/projects
> cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login 
> CVS password: anoncvs
> cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout
jakarta-turbine-torque  

Under the jakarta-turbine-torque directory there is a README.txt that
says
you must rename the build.properties.sample file to build.properties.
There 
is no build.properties.sample file but there is a default.properties
file. 
I made the assumption that this is the file intended and copied
default.properties 
to build.properties.

Inside build.properties you need to define 

  velocity.jar
  xerces.jar
  village.jar
  log4j.jar
  jdbc.jar
  junit.jar
  commons-collections.jar
  commons-util.jar

to point to the appropriate jar files.  I am still not sure why the jars
are 
not available under the lib directory of the jakarta-turbine-torque cvs
tree. 
You could take the time to download all the source for these jars and
build 
them. I started down this road but that required me to find all the jars
or 
source for the jars that these jars are dependent on... and so on.
Instead 
I looked around and was able to get all but the last 2 jars from the 
jakarta-turbine-2 cvs repository. Use the following cvs command to just 
checkout the lib directory from jakarta-turbine-2 project.

> cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout
jakarta-turbine-2/lib/

For the commons jars I had to get the project source from cvs and build
the jars

> cd ~/projects
> cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout
jakarta-commons 
> cd jakarta-commons/collections
> ant dist

NOTE: must have a xerces jar in your classpath for compile to work.
These 
steps generate the commons-collections.jar under the 
jakarta-commons/collections/dist directory.
This also assumes that you are still logged into the cvs server. If not,
then
relogin.

> cd ~/projects
> cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout
jakarta-commons-sandbox
> cd jakarta-commons-sandbox/util
> ant

NOTE: must have a xerces jar in your classpath for compile to work.
These steps 
generate the commons-util-0.1-dev.jar under the
jakarta-commons-sandbox/util 
directory.

I copied all the jars to a common lib directory and defined lib.repo to
be this
directory inside the ~projects/jakarta-turbine-torque/build.properties
file.

My final ~projects/jakarta-turbine-torque/build.properties file was as
follows:

#####################################################################
#---------------- Start File ----------------------------------------
#####################################################################
# -------------------------------------------------------------------
# B U I L D  P R O P E R T I E S
# -------------------------------------------------------------------
# These properties are used by the Torque build, you may override
# any of these default values by placing property values in
# your ${user.home}/build.properties file.
# -------------------------------------------------------------------

name = Torque
project = torque
version = 1.0
package = org.apache.${project}
final.name = ${project}-${version}

build.dir = ./bin
build.src = ${build.dir}/src
build.dest = ${build.dir}/classes
build.test = ${build.dir}/test
src.dir = ./src
test.dir = ${src.dir}/test

docs.src = ./xdocs
docs.dest = ./docs
javadoc.destdir = ./docs/api
jakarta.site2 = ../jakarta-site2

year = 1999-2001
debug = on
optimize = off
deprecation = off

# You must set these values here, or in your
# ${user.home}/build.properties file in order
# to build Torque:

lib.repo = /usr/local/java/lib
velocity.jar = ${lib.repo}/velocity-1.2-dev.jar
xerces.jar = ${lib.repo}/xerces-1.3.0.jar
village.jar = ${lib.repo}/village-1.5.3-dev.jar
log4j.jar = ${lib.repo}/log4j-1.1.jar
commons-collections.jar = ${lib.repo}/commons-collections.jar
commons-util.jar = ${lib.repo}/commons-util-0.1-dev.jar
jdbc.jar = ${lib.repo}/jdbc2_0-stdext.jar
junit.jar = ${lib.repo}/junit-3.2.jar
#####################################################################
#---------------- End File ----------------------------------------
#####################################################################


Now that we have all the needed jars that torque depends on,
go into jakarta-turbine-torque directory and build torque

> cd ~/projects/jakarta-turbine-torque
> ant dist

This creates ~/projects/jakarta-turbine-torque/bin directory
which contains all the parts need to use torque. It also includes
torque-1.0.zip which has everything you need nicely bundled up
to allow your to relocate it where ever you want.


Step 2) Deploy torque
----------------------
Unpack torque-1.0.zip where you want to develop your app. For me
once again it was under my projects directory

> cd ~/projects
> unzip ./jakarta-turbine-torque/bin/torque-1.0.zip

This will build a ~/projects/torque directory. Inside this directory
is the build.properties and build.xml files. For some reason the 
permissions were all screwed up in this unpacked torque directory. 
I had to fix these permissions to allow me read/write/execute access 
to the subdirectories.


Step 3) Create your project configuration files.
----------------------------------------------------------------------
Edit ~/projects/torque/build.properties.  I changed the project name 
to be "my-test".  My database was mysql which is the default so I 
did not change that.  I changed the targetPackage to be my java package 
name "com.digitalevergreen.mytest.om". I set databaseUser and
databasePassword 
to be my mysql admin user id and password. I changed the databaseUrl 
to create a table called MY_TEST_DB. Instead of listing out the whole 
file, I will only list the lines I changed in build.properties.

   project=my-test
   targetPackage=com.digitalevergreen.mytest.om
   databaseUrl = jdbc:mysql://127.0.0.1/MY_TEST_DB
   databaseUser = adminuser
   databasePassword = adminpassword


Because I changed my project name to my-test I have to create a
file called my-test-schema.xml under the ~/projects/torque/schema
directory. This will contain the xml definition of our objects 
and database. 

For my example test case I chose a book catalog. My schema contains 
three tables. I have a table that contains author information (first, 
middle and last name), a table that contains publisher information
(name), 
and the last table contains book information (Title, copyright info, and

ISBN). The author id, and publisher id will be foreign keys in the 
book table. My schema xml is shown below

<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>
<!DOCTYPE app-data SYSTEM
"http://jakarta.apache.org/turbine/dtd/database.dtd">
<!-- =============================================================== -->
<!-- ====================  START SCHEMA ============================ -->
<!-- =============================================================== -->
<app-data>
                
<database>
  <table name="BOOK">
    <column name="BOOK_ID" required="true" autoIncrement="true"
            primaryKey="true" type="INTEGER" javaName="Id"/>
    <column name="TITLE" required="true" type="VARCHAR" size="255"/>
    <column name="COPYRIGHT" type="VARCHAR" size="255"/>
    <column name="ISBN" type="VARCHAR" size="24" javaName="ISBN"/>
    <column name="PUBLISHER_ID" type="INTEGER"/>
    <column name="AUTHOR_ID" type="INTEGER"/>
 
    <foreign-key foreignTable="PUBLISHER">
        <reference local="PUBLISHER_ID" foreign="PUBLISHER_ID"/>
    </foreign-key>
 
    <foreign-key foreignTable="AUTHOR">
        <reference local="AUTHOR_ID" foreign="AUTHOR_ID"/>
    </foreign-key>
  </table>
 
  <table name="PUBLISHER">
    <column name="PUBLISHER_ID" required="true" primaryKey="true"
            type="INTEGER" autoIncrement="true" javaName="Id"/>
    <column name="NAME" type="VARCHAR" size="128" />
  </table>
 
  <table name="AUTHOR">
    <column name="AUTHOR_ID" required="true" primaryKey="true"
            type="INTEGER" autoIncrement="true" javaName="Id"/>
    <column name="FIRST_NAME" type="VARCHAR" size="128" />
    <column name="MIDDLE_NAME" type="VARCHAR" size="128" />
    <column name="LAST_NAME" type="VARCHAR" size="128" />
  </table>
 
</database>
 
</app-data>     
<!-- =============================================================== -->
<!-- ====================  END SCHEMA ============================== -->
<!-- =============================================================== -->


Step 4) Run Torque to build your source files
------------------------------------------------------
Run torque to build the object model and map source files.

> cd ~/projects/torque
> ant

Hopefully you will then see output similar to 


> Searching for build.xml ...
> Buildfile: /home/sdavis/projects/torque/build.xml
> 
> main:
> 
> init-tasks:
> 
> project-sql:
> +------------------------------------------+
> |                                          |
> | Generating SQL for YOUR Turbine project! |
> | Woo hoo!                                 |
> |                                          |
> +------------------------------------------+
> /home/sdavis/projects/torque/src/sql/report.my-test.sql.generation
> Resolver: used database.dtd
> 
> init-tasks:
> 
> project-om:
> +------------------------------------------+
> |                                          |
> | Generating Peer-based Object Model for   |
> | YOUR Turbine project! Woo hoo!           |
> |                                          |
> +------------------------------------------+
> /home/sdavis/projects/torque/src/java/report.my-test.om.generation
> Resolver: used database.dtd
> Resolver: used database.dtd
>  
> BUILD SUCCESSFUL
>  
> Total time: 9 seconds 

If you did see this then you should have java source files under 
~projects/torque/src/java/com/digitalevergreen/mytest/om/ 
directory that are similar to the following:

-rw-r--r--    1 sdavis   users         509 Sep 24 23:27 Author.java
-rw-r--r--    1 sdavis   users         629 Sep 24 23:27 AuthorPeer.java
-rw-r--r--    1 sdavis   users       15331 Sep 24 23:27 BaseAuthor.java
-rw-r--r--    1 sdavis   users       14828 Sep 24 23:27
BaseAuthorPeer.java
-rw-r--r--    1 sdavis   users       15731 Sep 24 23:27 BaseBook.java
-rw-r--r--    1 sdavis   users       19104 Sep 24 23:27
BaseBookPeer.java
-rw-r--r--    1 sdavis   users       13240 Sep 24 23:27
BasePublisher.java
-rw-r--r--    1 sdavis   users       13994 Sep 24 23:27
BasePublisherPeer.java
-rw-r--r--    1 sdavis   users         505 Sep 24 23:27 Book.java
-rw-r--r--    1 sdavis   users         625 Sep 24 23:27 BookPeer.java
drwxr-xr-x    2 sdavis   users        4096 Sep 24 23:27 map
-rw-r--r--    1 sdavis   users         515 Sep 24 23:27 Publisher.java
-rw-r--r--    1 sdavis   users         635 Sep 24 23:27
PublisherPeer.java

Step 5) Create the database and tables
--------------------------------------------------------------
I thought there was a way to have torque automatically create the 
database but I could not figure out how to make it do that. I manually 
created the database and then used the torque generated sql statements 
to set up the tables.

> cd ~/projects/torque/src/sql
> mysql -u <user id> -p<password> mysql
mysql> create database MY_TEST_DB;
mysql> quit
> mysql -u <user_id> -p<password> MY_TEST_DB < my-test-schema.sql 


Step 6) Make it all usable in a stand alone program
--------------------------------------------------------------
Ok, all that was great. We have a bunch of java source files and a
database to go with them.  How do we use it?  It actually turned out
to be pretty easy once I tracked down the initialization requirements
in the Torque code.  Torque only requires you to initialize the 
database info... but you will get system out errors from log4j if you
don't initialize it also. I created the following properties file in 
~/projects/torque/mytest.properties.


# -------------------------------------------------------------------
# Begin mytest.properties
# -------------------------------------------------------------------
# -------------------------------------------------------------------
# 
#  D A T A B A S E  S E R V I C E
#
# -------------------------------------------------------------------
# These are your database settings.  Look in the
# org.apache.turbine.util.db.pool.* packages for more information.
# The default driver for Turbine is for MySQL.
#
# The parameters to connect to the default database.  You MUST
# configure these properly.
# -------------------------------------------------------------------

services.DatabaseService.database.default=default

services.DatabaseService.database.default.driver=org.gjt.mm.mysql.Driver
services.DatabaseService.database.default.url=jdbc:mysql://localhost:330
6/MY_TEST_DB
services.DatabaseService.database.default.username=adminuser
services.DatabaseService.database.default.password=adminpassword

# The number of database connections to cache per ConnectionPool
# instance (specified per database).

services.DatabaseService.database.default.maxConnections=3

# The amount of time (in milliseconds) that database connections will be
# cached (specified per database).
#
# Default: one hour = 60 * 60 * 1000

services.DatabaseService.database.default.expiryTime=3600000

# The amount of time (in milliseconds) a connection request will have to
wait
# before a time out occurs and an error is thrown.
#
# Default: ten seconds = 10 * 1000

services.DatabaseService.database.connectionWaitTimeout=10000

# The interval (in milliseconds) between which the PoolBrokerService
logs 
# the status of it's ConnectionPools.
#
# Default: No logging = 0 = 0 * 1000

services.DatabaseService.database.logInterval=0

# These are the supported JDBC drivers and their associated Turbine
# adapter.  These properties are used by the DBFactory.  You can add
# all the drivers you want here.

services.DatabaseService.database.adapter=DBMM
services.DatabaseService.database.adapter.DBMM=org.gjt.mm.mysql.Driver

# Determines if the quantity column of the IDBroker's id_table should
# be increased automatically if requests for ids reaches a high
# volume.

services.DatabaseService.database.idbroker.cleverquantity=true

# Determines if IDBroker should prefetch IDs or not.  If set to false
# this property has the effect of shutting off the housekeeping thread
# that attempts to prefetch the id's.  It also sets the # of id's
grabbed
# per request to 1 regardless of the settings in the database.
# Default: true

services.DatabaseService.database.idbroker.prefetch=true

services.DatabaseService.earlyInit = true


# -------------------------------------------------------------------
#
#  log4j
#
# -------------------------------------------------------------------
# Need to have log4j "appenders" for Torque or log4j will generate
# system out errors.
log4j.category.org.apache.torque = INFO, torque
log4j.appender.torque = org.apache.log4j.FileAppender
log4j.appender.torque.file = ./mytest.log
log4j.appender.torque.layout = org.apache.log4j.PatternLayout
log4j.appender.torque.layout.conversionPattern = %d [%t] %-5p %c - %m%n
log4j.appender.torque.append = false

# -------------------------------------------------------------------
# End mytest.properties
# -------------------------------------------------------------------


I then created the file
~/projects/torque/src/java/com/digitalevergreen/mytest/MyTest.java
which contains code to initialize torque and run a brief test of
my test objects. Here is my test source.

//////////////////////////////////////////////////////////////////
// Begin MyTest.java source 
//////////////////////////////////////////////////////////////////
package com.digitalevergreen.mytest;

import com.digitalevergreen.mytest.om.*;
import org.apache.torque.Torque;
import org.apache.torque.util.Criteria;

import java.util.Vector;

public class MyTest
{
    public static void main(String[] args)
    {
        try
        {
            // Initialze Torque
            Torque.init( "./mytest.properties" );
           
            // Create some Authors
            Author de = new Author();
            de.setFirstName( "David" );
            de.setLastName( "Eddings" );
            de.save();
           
            Author tg = new Author();
            tg.setFirstName( "Terry" );
            tg.setLastName( "Goodkind" );
            tg.save();

            // Create publishers
            Publisher b = new Publisher();
            b.setName( "Ballantine" );
            b.save();

            Publisher t = new Publisher();
            t.setName( "Tor" );
            t.save();


            // Ok. For some reason even though the BaseXPeer doInsert 
            // methods return the primary key it is not set in the
            // BaseX save method so we have to "retrieve" these objects
            // from the database or we will get null value exceptions
            // when we try to use them in the book objects and do a
save.
            Criteria crit = new Criteria();
            crit.add( AuthorPeer.LAST_NAME, "Eddings" );
            Vector v = AuthorPeer.doSelect( crit );
            if ( v != null && v.size() > 0 )
                de = (Author) v.elementAt(0);

            crit = new Criteria();
            crit.add( AuthorPeer.LAST_NAME, "Goodkind" );
            v = AuthorPeer.doSelect( crit );
            if ( v != null && v.size() > 0 )
                tg = (Author) v.elementAt(0);

            crit = new Criteria();
            crit.add( PublisherPeer.NAME, "Ballantine" );
            v = PublisherPeer.doSelect( crit );
            if ( v != null && v.size() > 0 )
                b = (Publisher) v.elementAt(0);

            crit = new Criteria();
            crit.add( PublisherPeer.NAME, "Tor" );
            v = PublisherPeer.doSelect( crit );
            if ( v != null && v.size() > 0 )
                t = (Publisher) v.elementAt(0);


            // Create books
            Book wfr = new Book();
            wfr.setTitle( "Wizards First Rule" );
            wfr.setCopyright( "1994" );
            wfr.setISBN( "0-812-54805-1" );
            wfr.setPublisher( t );
            wfr.setAuthor( tg );
            wfr.save();

            Book dof = new Book();
            dof.setTitle( "Domes of Fire" );
            dof.setCopyright( "1992" );
            dof.setISBN( "0-345-38327-3" );
            dof.setPublisher( b );
            dof.setAuthor( de );
            dof.save();


            // Get and print books from db
            crit = new Criteria();
            v = BookPeer.doSelect( crit );
            for ( int i = 0; i < v.size(); i++ )
            {
                Book book = (Book) v.elementAt(i);
                System.out.println("Title: " + book.getTitle() );
                System.out.println("Author: " +
book.getAuthor().getFirstName() 
                                   + " " +
book.getAuthor().getLastName() );
                System.out.println("Publisher: " +
book.getPublisher().getName() );
                System.out.println("\n\n");
            }
        }
        catch (Exception e)
        {
            e.printStackTrace();
        }
    }
}
//////////////////////////////////////////////////////////////////
// End MyTest.java source 
//////////////////////////////////////////////////////////////////

Step 7) Build the test app
----------------------------------------------------------
The ant configuration in torque should be set up to compile all the
source. This assumes that you put your MyTest.java in the 
~/projects/torque/src directory tree. To build just do an ant compile.

> cd ~/projects/torque
> ant compile

This will place all the compiled class files under 
~/projects/torque/bin/classes

Step 8) Run the test
----------------------------------------------------------
You need to have the torque/bin/classes directory in your classpath
along with all the jars in the torque/lib directory. You also
need to have the database driver in your classpath.  I set my
classpath as follows:

>
CLASSPATH=~/projects/torque/lib/torque-1.0.jar:~/projects/torque/lib/com
mons-util-0.1-dev.jar:~/projects/torque/lib/commons-collections.jar:~/pr
ojects/torque/lib/jdbc2_0-stdext.jar:~/projects/torque/lib/log4j-1.1.jar
:~/projects/torque/lib/velocity-1.2-dev.jar:~/projects/torque/lib/villag
e-1.5.3-dev.jar:~/projects/torque/lib/xerces-1.3.0.jar:~/projects/torque
/lib/mysql_uncomp.jar:./bin/classes/; export CLASSPATH

Once this is set then run the MyTest.java main.

> cd ~/projects/torque
> java com.digitalevergreen.mytest.MyTest

You should see the following output:

> Title: Wizards First Rule
> Author: Terry Goodkind
> Publisher: Tor
> 
> 
> 
> Title: Domes of Fire
> Author: David Eddings
> Publisher: Ballantine


Pretty simple, powerful, and cool once I figured it out.
Anyway thats how I got it to work. Anyone that has suggestions
for better ways to do it please let me know.

-- Steven F. Davis

---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org


Mime
View raw message