CIS-764 Paper
Database Systems Engineering
Jakarta Torque
Submitted by
Deepti Gupta
Master of Software Engineering
Kansas State University
1
TABLE OF CONTENTS
1.
Introduction ......................................................................................................... 3
2.
Object Relational Mapping Tools ....................................................................... 3
3.
Jakarta Torque ..................................................................................................... 3
3.1 Torque Overview ...................................................................................... 3
3.2 Supported RDBMS ................................................................................... 3
3.3 Obtaining Torque ...................................................................................... 4
3.4. Configuring Torque ................................................................................. 4
3.4.1 Torque Generator Properties ............................................................. 5
3.4.2 Torque database schema file ............................................................. 5
3.4.3 Torque runtime properties................................................................. 6
3.5 Invoking Torque........................................................................................ 7
3.6 Writing an application............................................................................... 9
3.6.1 Inserting Rows ................................................................................... 9
3.6.2 Selecting Rows................................................................................... 9
3.6.3 Deleting Rows .................................................................................... 9
4.
Conclusion…………………………………………………………………… 10
5.
References……………………………………………………………………..11
2
1. Introduction
Object-relational mapping is the process of transforming between object and relational
modeling approaches and between the systems that support those approaches. It is a
technique of mapping relational rows from a relational database to objects in memory
where they can be manipulated by an object-oriented program.
2. Object Relational Mapping Tools
There are a large and growing number of projects that map relational databases into
object models. This paper provides a review of one such tool – Jakarta Torque
3. Jakarta Torque
3.1. Torque Overview
Torque is a persistence layer. Torque was developed as part of the Jakarta Turbine
Framework - a servlet based framework that allows Java developers to quickly build
web applications. Torque is now decoupled and can be used by itself.
Torque consists of two main components:
Generator - The Torque generator uses a single XML database schema file to
generate the SQL for the target database and Torque's Peer-based object relational
model. The generator can be executed an Ant build file.
Runtime - The Torque runtime is required in order to compile and use the classes
produced by the generator.
3.2. Supported RDBMS
Torque supports the following relational databases
RDBMS
Driver
Axion
org.axiondb.jdbc.AxionDriver
Cloudscape COM.cloudscape.core.JDBCDriver
3
DB2
COM.ibm.db2.jdbc.{app|net}.DB2Driver
DB2/AS400 com.ibm.as400.access.AS400JDBCDriver
Hypersonic
org.hsql.jdbcDriver
Informix
com.informix.jdbc.IfxDriver
InstantDB
org.enhydra.instantdb.jdbc.idbDriver
Interbase
interbase.interclient.Driver
MS Access
sun.jdbc.odbc.JdbcOdbcDriver
MS SQL
com.microsoft.jdbc.sqlserver.SQLServerDriver
MySQL
org.gjt.mm.mysql.Driver
Oracle
oracle.jdbc.driver.OracleDriver
Postgres
org.postgresql.Driver
SapDB
com.sap.dbtech.jdbc.DriverSapDB
Sybase
com.sybase.jdbc2.jdbc.SybDriver
Weblogic
weblogic.jdbc.pool.Driver
In case a certain RDBMS is not supported, an application developer can write his
own DB adapters for the RDBMS.
3.3. Obtaining Torque
Torque
and
its
generator
can
be
downloaded
from
http://db.apache.org/torque/download.html
3.4. Configuring Torque
The following section outlines the necessary steps needed to define the database
schema and configure Torque to use the schema. Torque will create the object
model and all of the Java classes that support it. In addition, Torque can generate
and execute all of the appropriate SQL commands needed to create the database.
4
This requires one to configure Torque by editing 3 files
1. Torque Generator properties – build.properties
2. Torque database schema file – torque-schema.xml
3. Torque runtime properties – torque.properties
3.4.1. Torque Generator Properties
These properties are set in the build.properties file. They affect how Torque
generates Java and SQL code.
Some of the important properties are listed below
Property
Description
Basic Properties
torque.project
torque.database
torque.targetPackage
The name of the project Torque will generate code
for.
The target database. Supported values are: axion,
cloudscape, db2, db2400, hypersonic, interbase,
mssql, mysql, oracle, postgresql, sapdb, and sybase.
The Java package that Torque will put the generated
classes in.
Database Settings
torque.database.createUrl
torque.database.buildUrl
torque.database.url
torque.database.driver
torque.database.user
torque.database.password
The JDBC URL that Torque can use to create and
drop databases if instructed to do so.
The JDBC URL that will be used to access the
database.
This should contain the same value as
buildDatabaseURL.
The JDBC database driver to use when connecting to
your database.
The administrative username that has sufficient
privileges to create and drop databases and tables
that Torque executes at build time.
The administrative password for the supplied
username.
3.4.2. Torque database schema file
The second file that must be edited to configure Torque is the database schema.
The database schema is an XML file that represents the SQL database in Torque.
5
This is where the tables, column names and types, as well as the keys used to
index the tables are defined.
Example schema file with the database name, two tables: book and author
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE database SYSTEM
“http://db.apache.org/torque/dtd/database_3_1.dtd">
<database
name="bookstore"
defaultIdMethod="idbroker">
<table name="book" description="Book Table">
<column
name="book_id"
required="true"
primaryKey="true"
type="INTEGER"
description="Book Id"/>
<column
name="title"
required="true"
type="VARCHAR"
size="255"
description="Book Title"/>
<column
name="author_id"
required="true"
type="INTEGER"
description="Foreign Key Author"/>
<foreign-key foreignTable="author">
<reference
local="author_id"
foreign="author_id"/>
</foreign-key>
</table>
</database>
3.4.3. Torque runtime properties
The last step in the configuration of Torque is the Torque run-time properties.
These properties are used when the application is executing the object model code
6
generated by Torque. The run-time properties control logging and database
parameters such as drivers, usernames, and passwords
E.g.
torque.database.default = bookstore
torque.database.bookstore.adapter = mysql
torque.bookstore.connection.driver = org.gjt.mm.mysql.Driver
torque.bookstore.connection.url= jdbc:mysql://localhost:3306/bookstore
torque.bookstore.connection.user = user
torque.bookstore.connection.password = password
3.5. Invoking Torque
With the configuration of Torque completed, the object model can be generated to
support the database, and optionally create the database and all of its associated
tables. Ant can be used to do this. One can also generate HTML documentation
for the database schema.
Generating the object model
Use Ant along with the build.xml file to generate the object model
Creating the SQL databases and tables
The command ant create-db can be used for this purpose
Generating the HTML documentation
The command ant doc can be used for this purpose
The following snapshot shows the HTML output of the example schema for the
tables: book, author and publisher.
7
Generated classes:
The book table, defined in the database schema presented earlier, will result in the
following classes:
Book, BookPeer, BaseBook, and BaseBookPeer.
Book and BookPeer are subclasses of BaseBook and BaseBookPeer respectively.
The two Base classes (BaseBook and BaseBookPeer) contain Torque-generated
logic and should not be modified because Torque will overwrite the changes when
the object model is re-generated. Any business logic should be placed in the Book
and BookPeer classes if required.
8
3.6. Writing an application
3.6.1. Inserting Rows
Inserting rows into tables is easy with Torque. One needs to instantiate a new
Data Object of the appropriate class, set its properties using the mutators named
after the table's columns, then invoke the Data Object's save method.
E.g.
Book effective = new Book();
effective.setTitle("Effective Java");
effective.save();
3.6.2. Selecting Rows
Selecting rows from the database is just as easy as inserting rows. The Peer class
associated with a table defines a static method called doSelect which is used to
pull data out of the table. The argument to doSelect is a Criteria object. It is this
object that specifies the criteria to be used when selecting data from the database.
As a result of the query, doSelect returns a List of Data Objects representing the
rows of data selected.
Criteria crit = new Criteria();
crit.add(BookPeer.title, "Effective Java");
List books = BookPeer.doSelect(crit);
This selects the book with the title “Effective Java”
3.6.3. Deleting Rows
Deleting rows from a table is easy as well. The Peer class defines a static method
doDelete which can be used for this purpose. Similar to the other Peer methods,
doDelete may be passed a Criteria object or a Data Object to specify which row
or rows to delete.
Criteria crit = new Criteria();
crit.add(BookPeer.title, "Effective Java");
BookPeer.doDelete(crit);
This deletes the book with the title “Effective Java”
9
4. Conclusion
Torque is definitely associated with a learning curve. But when one has learnt about
the ways of configuring and invoking torque, it proves to be a good object relational
mapping tool. An object oriented application can use torque as its persistence layer
and can then manipulate the relational rows and columns from the relational database
as objects in memory. The application does not need to deal with SQL statements.
Object relational mapping is a clean way of accessing and persisting values to a
relational table.
10
5. References

http://db.apache.org/torque/index.html
1. User Guide
2. Torque tutorial
3. Downloads
4. Miscellaneous Information

http://www.developer.com/java/other/article.php/10936_1457081_1 - Using the
Torque Object Mapper
11