Step 2: Configuring Torque

The following section outlines the necessary steps to define your database schema and configure Torque to use your schema. Upon completion, you'll be able to use Torque to create your object model and all of the Java classes that support it. In addition, Torque can generate and execute all of the appropriate SQL commands to create your database, freeing you from having to do it manually.

To accomplish all of the above, you only need to create/edit three files: the Torque generator properties, the Torque database schema, and the Torque run-time properties. Each of these files is covered in the following sections.

Torque Generator Properties

Torque is a system that literally generates Java source/class files representing your object model, SQL statements for your specific database, and documentation. To accomplish these tasks, it uses Maven and the Torque maven-plugin to drive the Torque generator. You configure the generator by setting properties in the project.properties file in root directory of your project - this is the file that we will edit first.

For a reference as to what each property, and others, controls, please see the properties reference.

Setting these properties correctly is very important. These enable Torque 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 these values.

Customizing the Generator Templates

The object model class files generated by Torque are produced using a set of Velocity templates that are included in the torque-gen jar file. If you want to customise the templates that are used to generate your object model class files you can either build your own customised version of the torque-gen jar file and install it in your local Maven repository or use additional properties to tell the maven-plugin where to find your customised templates.

Torque Database Schema

The second file that you must edit to configure Torque is the database schema. The database schema is an XML file that represents your SQL database in Torque. This is where you define all of your tables, column names and types, as well as the keys used to index these tables.

By default your database schema file should be located in the schema directory under the base of your project, but you can tell Torque where to find it using the torque.schema.dir property in project.properties (the torque.home property can also be used to point to the parent of the schema directory. Here you will create two XML files: id-table-schema.xml and project-schema.xml. The id-table-schema.xml file is used internally by Torque's IDBroker service (which is a database independent method for generating unique IDs). project-schema.xml is where you'll define your database schema. Historically, the name of your database schema file was required to be in the format of name-schema.xml where name was the same as the project property defined in project.properties; otherwise, Torque was not able to find your database schema file. This is no longer the case, name is no longer restricted to the project name. However, it must end with ‘-schema.xml’ because Torque will only generate object models for files ending with that pattern.

For this tutorial, we will use a simple database that might be used to support a bookstore application. The database will contain three tables: author, publisher, and book. The first table will contain author information (first and last name). The second table will contain publisher information (name). And the third table will contain book information (title, and ISBN). The author id and publisher id will be foreign keys in the book table. The schema representation for this database is as follows:

Edit project-schema.xml to reflect the above database schema. If you would rather create your own schema file, be sure the filename ends in ‘-schema.xml’, and delete project-schema.xml because Torque will generate an object model for that file as well. Do not delete id-table-schema.xml if you plan on using Torque's IDBroker service, which is used in this tutorial.

There are several items of importance to note. The database element's name attribute must be the same as the database name specified by the databaseUrl property in project.properties; likewise, the run-time properties (described in the next section) should also reflect this value. Failure to do so will prevent Torque from creating your database tables (if instructed to do so) or prevent your object model from working properly.

Another item of importance is the database element's defaultIdMethod attribute. This attribute specifies the default method that Torque will use to generate IDs for primary keys (columns with the primaryKey attribute set to true: book_id, publisher_id, and author_id) in your database tables. There are several possible values:

PropertyDescription
idbroker Instructs Torque to use its IDBroker service to generate IDs in a database agnostic manner. This is the method that will be used in this tutorial.
native Instructs Torque to use the underlying database's mechanism to generate IDs (varies per database).
none Instructs Torque to not generate IDs. This can be useful in some situations (an example is described below).
autoincrement This method has been deprecated. Use the native method instead.
sequence This method has been deprecated. Use the native method instead.

The defaultIdMethod selected will be used for all tables in your schema unless an individual table element contains the idMethod attribute, in which case, its value will override the defaultIdMethod. idMethod takes the same values as defaultIdMethod.

One common reason that a table might override the defaultIdMethod is when a table is composed only of foreign keys (i.e. a ‘junction entity’ in database-speak). In this case, all columns should be defined as primary keys because they are all needed to declare a row as unique. However, Torque should not generate primary key IDs for objects in this table because the objects that compose the table already have primary key IDs. Thus, the idMethod attribute of the table must be set to none. For example, if the book table defined above did not have any additional attributes other than a publisher_id and author_id, the schema for the book table should be defined as:

Another common mistake is to forget that XML is case-sensitive. All of the elements and attributes must be specified according to the DTD for the database schema. In addition, you must include the XML declaration and DTD specification in your database schema file. Failure to do so can result in errors.

Finally, you must also edit (or add if its not present) the name attribute to the database element in id-table-schema.xml. The value should be identical to the value in your database schema file. This will instruct Torque to create id-table in the same database as your schema. Below is the file used in this example:

Torque uses the database schema files to generate your object model and Java classes to support it. In addition, Torque generates SQL that can be used to create your databases and tables from these schemas. In the next section, we will conclude the configuration of Torque by editing the Torque run-time properties. For additional information on the XML elements and attributes, please refer to the Torque Schema Reference.

Torque Run-Time Properties

The last step in the configuration of Torque are the Torque run-time properties. As the name suggests, these properties are used when your 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. These properties can be saved in any file because your application must explicitly initialize Torque (as you'll see later in this tutorial).

The runtime distribution archive includes an Ant build file that can be used to generate your Torque runtime configuration. When you unpack the archive you will see the following:

To generate Torque.properties for your project you can edit the input properties in master/default.properties and then run ant to regenerate Torque.properties. Note that the sample and generated Torque.properties file contains a good amount of information regarding the available Torque run-time properties.

For simplicity, we'll just create our own Torque.propereties file (again, this tutorial will guide you through the bare minimum to get your application up and running). Create a new file called Torque.properties in the top-level directory of your project and add the following lines to it:

We are using the commons-dbcp for our connection pool - see Pool-config Howto details of the available DataSource factories.

PropertyDescription
torque.database.default Torque has the ability to use multiple databases. This property specifies which database is to be used as the default.
torque.database.XXX.adapter Torque has the ability to deal with multiple database systems. This property specifies the database adapter to use.
torque.dsfactory.XXX.factory The factory class that will be used to provide database connections.
torque.dsfactory.XXX.connection.driver The JDBC database driver to use when connecting to your database.
torque.database.XXX.connection.url The URL that will be used to access your database. Torque's generated object model will perform all database operations using this URL. This value should reflect the database name specified in your database schema file (see the database element's name attribute).
torque.database.XXX.connection.username The username that has sufficient privileges to access your database. This user does not require privileges to create and drop tables, unlike the username that was specified in project.properties.
torque.database.XXX.connection.password The password for the specified username.

It is worth re-iterating that these run-time properties are not used by Torque when generating your object model and creating your database. They are used only by the application utilizing the Torque-generated object model classes at run-time.

Logging configuration

To have any logging messages sent to the console add the following to a file named log4j.properties and place this in your classpath (putting it in your target/classes will do the trick).

PropertyDescription
log4j.rootCategory Torque uses Commons Logging, which in turn by default uses Log4J for a logging. This parameter configures the Log4J system to log all messages but debug messages (use DEBUG rather than INFO to have get the debug messages too).
log4j.appender.default Configures Log4J to send all logging messages to the console. Log4J can just as easily send all logging to a file or a syslog server.
log4j.appender.default.layout Log4J logs messages using a layout. Layouts can be very simple or complicated. This tutorial uses the very rudimentary SimpleLayout.

Torque runtime and dependant libraries

In order to be able to compile and use the generated class files it is necessary to include the Torque runtime jar file and jar files for all of the necessary dependencies in the classpath of your project. The necessary jars are included in the torque/lib directory of the Torque runtime. If you are using Maven to build your project it may be easiest to copy the necessary dependencies from the Torque runtime POM.

Note: There is no need to include the torque-gen jar file in your project classath, including it may adversly affect the logging configuration of your application.

Where to next

That completes the configuration of Torque. You are now ready to start building your object model and creating your database.

Next we will look Invoking Torque.