Step 3: Invoking the Torque Ant Task

With the creation of the build file and definition of the database schema completed, you can now generate the object model to support your database, and create the database tables. Each of these tasks is covered in the following sections.

The generation of your object model will produce Java source files that represent your database structure. 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 via maven as demonstrated later in this tutorial).

The object model consists of eight classes for each table in your schema. For example, the book table, defined in this tutorial, will result in the following eight classes: Book, BookPeer, BookPeerImpl, BookRecordMapper, BaseBook, BaseBookPeer, BaseBookPeerImpl, and BaseBookRecordMapper (a detailed discussion on the use of these classes is deferred until we write our sample application). See the image below for a UML class diagram of the generated classes and their relations. generated classes

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

ant generate
Hint: You have to create a build copy of your bookstore-schema.xml named schema.xml in the sourceDir (by default src/main/schema) directory!

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

The generated Java source files are located in the target/generated-sources (BaseXXX) and src/main/generated-java (other classes) directories. The locations are split because the Base classes are generated each time anew, are not intended to be edited and should not be under version control if you use a version control system. So they reside in the target directory which can be deleted for a clean build. The other classes can be edited once generated and will not be overwritten if they exist, so they reside in the src tree. All generated classes will be in a directory hierarchy matching that of the option you specified in build.xml.

The generated SQL files are located in the target/generated-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.

If you encounter errors while building, it is more than likely a formatting error of your database schema file or the ant build file, or a missing library. Check again the contents of these files and the lib/ant directory.

Creating the Database Tables

As mentioned previously, Torque can automatically create the database tables for you. However, you must first make sure that the appropriate database driver can be accessed by ant. We already did that by adding the mysql driver jar to the lib/ant directory of your project.

Creating the tables

To create the database tables, you first need to create the schema (in mysql speak: database) which you want to use for the tables. E.g. in mysql, execute the following command as root user:

  create database bookstore;

If you want to use another database user than root to create the tables, make sure that this user has sufficient privileges on the database bookstore to create tables. Alternatively, you can just use the root user to create the database tables. In both cases, check again that the username, password and url of your mysql database is correct in the build.xml, and type the following command in the top-level directory of your project:

ant execute-sql

Success will be indicated by the message 8 of 10 SQL statements executed successfully BUILD SUCCESSFUL. (Torque assumes that you already have defined a database, and performs a drop before attempting recreation. The statements dropping the foreign keys fail because the table does not exist, but this is not a problem for creating the tables. If you re-run the command, all 10 statements will execute successfully.) You can also validate that the tables were created by checking your database. For example, the bookstore-schema.xml defined in this tutorial should have created the following tables: author, book, and publisher.

If you have difficulties in creating the tables using ant, you can also execute the SQL script generated in the directory target/generated-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