Step 3: Invoking the Torque Maven 1 Plugin

With the configuration of the Torque Maven 1 Plugin completed, you can now generate the object model to support your database, and optionally create your database and all of its associated tables. Each of these tasks is covered in the following sections.

Note: If you are yet to jump aboard the Maven ship you can download the torque-gen archive and make use of the Ant build file build-torque.xml contained therein. See the Generator documentation for details.

Generating the Object Model and Associated SQL

The generation of your object model will produce Java source files that can be used to represent your database. These classes enable you to create, edit, delete, and select objects that represent rows in your database tables. In addition, Torque will generate SQL to create your database tables (you have the option of executing the SQL as demonstrated later in this tutorial).

The object model consists of four classes for each table in your schema. For example, the author table, defined in this tutorial, will result in the following four classes: Author, AuthorPeer, BaseAuthor, and BaseAuthorPeer (a discussion on the use of these classes is deferred until we write our sample application).

To generate your object model and the associated SQL, type the following command in your top-level project directory:

maven torque

A successful build will be indicated by the ‘BUILD SUCCESSFUL’ message.

The generated Java classes are located in the src/java directory and will be in a directory hierarchy matching that of the torque.targetPackage you specified in These are the files that will be compiled into your object model classes.

The generated SQL files are located in the target/sql directory. For each database schema in your src/schema directory, there will be a corresponding file with a .sql extension instead of .xml extension. The contents of these files are the SQL commands that can be used to manually or automatically (see next section) create your database tables.

To change the directory where the classes are generated, use the properties torque.home, torque.output.dir and/or in your file - see the properties reference for more detail).

If you encounter errors while building, it is more than likely a formatting error of your database schema file. Check the format of the file and make sure it conforms to the Torque Schema Reference.

Creating the Database and Tables

As mentioned previously, Torque can automatically create your database and all of the associated tables for you. However, you must first make sure that the appropriate database driver (the one you defined in is in your classpath so that Torque can connect to your database and execute the generated SQL commands. The easiest way to accomplish this is to add the database driver jar to your local maven repository, and specify it as a dependency in your project. This is done as follows:

Adding the driver to the maven repository

For licensing reasons, most database drivers cannot be downloaded automatically by maven. Therefore, you have to add the driver manually to your local maven repository. The local maven repository is located by default in the directory %HOMEDRIVE%%HOMEPATH%\.maven\repository in windows, and $HOME/.maven/repository in linux/unix. Change into that direcory and create a subdirectory ${groupId}/jars, where ${groupId} is typically set to the name of the database (for example, use mysql/jars for mysql). Then, download the database driver, and copy the driver jar to the subdirectory you just created.

Specifying the driver dependency

The dependencies of a project are specified in a file named project.xml in the top level directory of your project. (This is not the only use of this file, see the maven getting started guide and the Maven Project descriptor reference for more information.)

If you did not create a project.xml file yet, create it in the top level directory of your project and fill it using the following template. (If you already have a project.xml, just add the dependency.)



Replace the variables ${artifactId}, ${groupId} and ${version} by the values needed to locate the driver jar. These variables must be chosen such that the path ${repo}/${groupId}/${type}s/${artifactId}-${version}.${type} points to the driver jar you copied into the local maven repository. Here, ${repo} is the path to the local maven repository, ${type} is set to jar by default, and the other variables are set in the project.xml. If the name of the driver jar cannot be expressed as ${artifactId}-${version}.${type}, rename the driver jar in yor local maven repository.

For example, if you use the mysql 5.0.4 driver, ${artifactId} would be set to mysql-connector-java, ${groupId} would be set to mysql, and ${version} would be set to 5.0.4 in the project.xml.

Creating the database

Note: Torque will drop the database and tables that it is about to create if they exist! You should skip this step if you are working with an existing database full of data.

To create your database, type the following command in the top-level directory of your project:

maven torque:create-db

Note that creating the database might not work for some databases at all (e.g. oracle). Also, for other databases (e.g. mysql), the database user must be database administrator to be able to create the database, and often (e.g. mysql, postgresql), one must connect to a database which is different from the database which one wants to create (this is why there are different properties torque.database.createUrl and torque.database.buildUrl in the for creating the database and the tables, respectively).

If you encounter problems in this step, one possible reason might be a misconfiguration of your Another common problem is that the user specified in the does not have sufficient privilege to create a database. In either case, refer to the section above that explains the file. If the problems persist, skip this step and create the database manually.

Creating the tables

To create your tables, type the following commands in the top-level directory of your project:

maven torque:id-table-init-sql
maven torque:insert-sql

Note: if this tutorial had not utilized Torque's idbroker method (as described earlier), it would not have been necessary to execute the id-table-init-sql target.

Success will be indicated by the ‘BUILD SUCCESSFUL’ message. You can also validate this by checking your database. For example, the bookstore-schema.xml and id-table-schema.xml, defined in this tutorial, should have created a database called bookstore, with the following tables: ID_TABLE, author, book, and publisher.

If you have difficulties in creating the tables using maven, you can also execute the SQL scripts generated in the directory target/sql manually.

Where to next

Now that you have generated all of your object model classes and created your database, you are ready to build your first Torque application.

Next we will look Configuring the Torque Runtime.

User Comments

User comments for this step