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.
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 project.properties.
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 torque.java.dir
in your project.properties 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.
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 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:
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.
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.)
<project>
<pomVersion>3</pomVersion>
<groupId>torque</groupId>
<id>torque-tutorial</id>
<name>Torque</name>
<currentVersion>3.3</currentVersion>
<dependencies>
<dependency>
<artifactId>${artifactId}</artifactId>
<groupId>${groupId}</groupId>
<version>${version}</version>
</dependency>
</dependencies>
</project>
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.
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 project.properties
for creating the database and the tables,
respectively).
If you encounter problems in this step, one possible reason might be 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 a database. In either case, refer to the section above that explains the project.properties file. If the problems persist, skip this step and create the database manually.
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.
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.