Torque Is a Persistence Layer

CIS-764 Paper

Database Systems Engineering

Jakarta Torque

Submitted by

Deepti Gupta

Master of Software Engineering

Kansas State University

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

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

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 / The name of the project Torque will generate code for.
torque.database / The target database. Supported values are: axion, cloudscape, db2, db2400, hypersonic, interbase, mssql, mysql, oracle, postgresql, sapdb, and sybase.
torque.targetPackage / The Java package that Torque will put the generated classes in.

Database Settings

torque.database.createUrl / The JDBC URL that Torque can use to create and drop databases if instructed to do so.
torque.database.buildUrl / The JDBC URL that will be used to access the database.
torque.database.url / This should contain the same value as buildDatabaseURL.
torque.database.driver / The JDBC database driver to use when connecting to your database.
torque.database.user / The administrative username that has sufficient privileges to create and drop databases and tables that Torque executes at build time.
torque.database.password / 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. 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 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.

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.

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”

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.

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

1