Step 2: Configuring the Torque generation process

The following section outlines the necessary steps to define your database schema and configure the Torque maven 1 plugin to use your schema. Upon completion, you'll be able to use the generator to create your object model and all of the Java classes that support it. In addition, the maven 1 plugin 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 need to create/edit the Torque maven 1 plugin properties file (which is providing the maven 1 plugin with the necessary information) and the Torque database schema file(s) (which contain the structure of your database). Each of these files is covered in the following sections.

As a starting point, create a directory as a base directory for your project (also called the project's top level directory), and change into that directory. All the paths in the following steps will be relative to this base directory.

Torque Maven 1 Plugin Properties

The maven 1 plugin generates Java source/class files representing your object model, SQL statements for your specific database, and documentation. You configure the maven 1 plugin by setting properties in the project.properties file in root directory of your project. As a starting point, use the following template and edit it to reflect your specific needs ( typically you need to change the database, the database urls, the database driver, the database host, the database user and password):

  # The name of the project Torque will generate code for.
  torque.project = bookstore

  # The target database platform.
  torque.database = mysql

  # The target package to put the generated classes in.
  torque.targetPackage = com.kazmier.om

  # The JDBC URL that Torque can use to create and
  # drop databases if instructed to do so.
  torque.database.createUrl = jdbc:mysql://127.0.0.1/mysql

  # The JDBC URL that will be used to create tables in your database.
  torque.database.buildUrl = jdbc:mysql://127.0.0.1/bookstore

  # The JDBC URL that will be used to access your database.
  torque.database.url = jdbc:mysql://127.0.0.1/bookstore

  # The JDBC database driver to use when connecting to your database.
  torque.database.driver = org.gjt.mm.mysql.Driver

  # The administrative username that has sufficient privileges to create
  # and drop databases and tables that Torque executes at generation time.
  torque.database.user = adminuser

  # The administrative password for the supplied username.
  torque.database.password = adminpassword

  # The hostname or IP address of your database server.
  torque.database.host = 127.0.0.1

Setting these properties correctly is very important. They 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.

The properties that can be used in the maven 1 plugin are identical to those that can be used in the ant-based generator. For a reference as to what each property, and others, controls, please see the properties reference for the Torque generator.

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 the structure of 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.

Your database schema file should be located in the src/schema directory under the base of your project. In this directory, 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. The name of your database schema file must end with ‘-schema.xml’ because Torque will only generate object models for files ending with that pattern.

In 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 stored in the file project-schema.xml, which should be created in the src/schema directory and contain the following:

<!DOCTYPE database SYSTEM
 "http://db.apache.org/torque/dtd/database_3_3.dtd">

<database
  name="bookstore"
  defaultIdMethod="idbroker">

  <table name="publisher" description="Publisher Table">
    <column
      name="publisher_id"
      required="true"
      primaryKey="true"
      type="INTEGER"
      description="Publisher Id"/>
    <column
      name="name"
      required="true"
      type="VARCHAR"
      size="128"
      description="Publisher Name"/>
  </table>
  <table name="author" description="Author Table">
    <column
      name="author_id"
      required="true"
      primaryKey="true"
      type="INTEGER"
      description="Author Id"/>
    <column
      name="first_name"
      required="true"
      type="VARCHAR"
      size="128"
      description="First Name"/>
    <column
      name="last_name"
      required="true"
      type="VARCHAR"
      size="128"
      description="Last Name"/>
  </table>
  <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="isbn"
      required="true"
      type="VARCHAR"
      size="24"
      javaName="ISBN"
      description="ISBN Number"/>
    <column
      name="publisher_id"
      required="true"
      type="INTEGER"
      description="Foreign Key Publisher"/>
    <column
      name="author_id"
      required="true"
      type="INTEGER"
      description="Foreign Key Author"/>
    <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>
</database>

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 step 4) 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:

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.

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.

To initialize the IDBroker service, create a file called id-table-schema.xml in the src/schema subdirectory of your project's base directory. It should have the following contents:

<!DOCTYPE database SYSTEM
 "http://db.apache.org/torque/dtd/database_3_2.dtd">

<database name="bookstore">
  <table name="ID_TABLE" idMethod="idbroker">
    <column
      name="ID_TABLE_ID"
      required="true"
      primaryKey="true"
      type="INTEGER"/>
    <column
      name="TABLE_NAME"
      required="true"
      size="255"
      type="VARCHAR"/>
    <column
      name="NEXT_ID"
      type="INTEGER"/>
    <column
      name="QUANTITY"
      type="INTEGER"/>
    <unique>
      <unique-column name="TABLE_NAME"/>
    </unique>
  </table>
</database>

Note that again, the name attribute to the database element has the same value as in the project-schema.xml.

For additional information on the XML elements and attributes, please refer to the Torque Schema Reference.

Where to next

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

Next we will look at Invoking the Torque Maven 1 plugin.

User Comments