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. Some hints
about this can be found in the
User Guide.
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
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.
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:
maven torque:create-db
Note that creating the database might not work for some databases or the database user configured in the generator properties might not have the necessary permissions to do so. If you encounter problems in this step, skip it 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 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.
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.