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 - see the
User Guide.
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:
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. Validating the file against the provided DTD will help ensure that it will be processed correctly.
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:
To create your tables, type the following commands in the top-level directory of your project:
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.