Step 3: Invoking Torque

With the configuration of Torque completed, you can now generate the object model to support your database, and optionally create your database and all of its associated tables. As mentioned earlier in this tutorial, Torque utilizes Maven to perform these tasks. 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 User Guide. 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:

Upon a successful build, indicated by the ‘BUILD SUCCESSFUL’ message, you will find the generated class files within the src directory of your project (this is the default, you can alter where the files are generated to using the torque.home, torque.output.dir and/or torque.java.dir properties in your project.properties file - see the properties reference for more detail).

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

The SQL files are located in the sql directory. For each database schema in your 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.

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. Validating the file against the provided DTD will help ensure that it will be processed correctly.

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 project.properties) is in your classpath so that Torque can connect to your database and execute the generated SQL commands. The easiest way to accomplish that is to add your database driver as a dependency in your project (add it to your project.xml.

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:

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

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 encounter errors while creating your database, it is more than likely a misconfiguration of your project.properties. Another common problem is that the user specified in the project.properties does not have sufficient privilege to create databases and tables. In either case, refer to the section above that explains the project.properties file.

Where to next

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

Next we will look Writing a Sample Application.