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.
To generate your object model and the associated SQL, type the following command in your top-level project directory:
ant generate
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
torque.om.package 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.