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