Step 3: Invoking the Torque Maven Plugin
With the configuration of Maven 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:
mvn generate-sources
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 maven's target directory
which can be deleted during a maven build.
The other classes can be edited once generated
and will not be overwritten if they exist, so they reside in the
src tree which is not altered by maven.
All generated classes will be in a directory hierarchy matching that of the
torque.om.package option you
specified in pom.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 Maven 2 pom file. Check again the contents of these files.
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 maven. This is not a problem for most drivers (e.g. mysql, postgresql, derby...) but some drivers (e.g. oracle) are not available in the maven central repository and must be added to your local maven repository manually (check the maven 2 docs on how to do this.)
Specifying the driver dependency
There are two places where the database driver appears: once in the main dependencies section, and once in the dependencies of the maven sql plugin which can execute the sql generated by Torque.
The tutorial uses mysql as database, and the pom templates given in step 1 already include a mysql dependency, so the pom xml in the tutorial project can remain unchanged.
Creating the tables
To create the database tables, you first need to create the schema (mysql: 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, type the following commands in the top-level directory of your project:
maven sql:execute
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 maven, 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.