The following section outlines the necessary steps to define your database schema and configure Torque to use your schema. Upon completion, you'll be able to use Torque to create your object model and all of the Java classes that support it. In addition, Torque can generate and execute all of the appropriate SQL commands to create your database, freeing you from having to do it manually.
To accomplish all of the above, you only need to create/edit three files: the Torque generator properties, the Torque database schema, and the Torque run-time properties. Each of these files is covered in the following sections.
Torque is a system that literally generates Java source/class files representing your object model, SQL statements for your specific database, and documentation. To accomplish these tasks, it uses Maven and the Torque maven-plugin to drive the Torque generator. You configure the generator by setting properties in the project.properties file in root directory of your project - this is the file that we will edit first.
For a reference as to what each property, and others, controls, please see the properties reference.
Setting these properties correctly is very important. These enable Torque to generate all of the required sources and SQL for your specific database. If you experience problems later in this tutorial, it would be wise to double-check these values.
The object model class files generated by Torque are produced using a set of Velocity templates that are included in the torque-gen jar file. If you want to customise the templates that are used to generate your object model class files you can either build your own customised version of the torque-gen jar file and install it in your local Maven repository or use additional properties to tell the maven-plugin where to find your customised templates.
The second file that you must edit to configure Torque is the database schema. The database schema is an XML file that represents your SQL database in Torque. This is where you define all of your tables, column names and types, as well as the keys used to index these tables.
By default your database schema file should be located in the
schema directory under the base of your project, but
you can tell Torque where to find it using the
torque.schema.dir
property in
project.properties
(the torque.home
property can also be used to point to the parent of the
schema directory. Here you will
create two XML files: id-table-schema.xml and
project-schema.xml. The
id-table-schema.xml file is used internally
by Torque's IDBroker service (which is a database
independent method for generating unique IDs).
project-schema.xml is where you'll define
your database schema. Historically, the name of
your database schema file was required to be in the
format of name-schema.xml where
name was the same as the project
property defined in project.properties;
otherwise, Torque was not able to find your
database schema file. This is no longer the case,
name is no longer restricted to the project
name. However, it must end with
‘-schema.xml’ because Torque will only
generate object models for files ending with that
pattern.
For this tutorial, we will use a simple database that might be used to support a bookstore application. The database will contain three tables: author, publisher, and book. The first table will contain author information (first and last name). The second table will contain publisher information (name). And the third table will contain book information (title, and ISBN). The author id and publisher id will be foreign keys in the book table. The schema representation for this database is as follows:
Edit project-schema.xml to reflect the above database schema. If you would rather create your own schema file, be sure the filename ends in ‘-schema.xml’, and delete project-schema.xml because Torque will generate an object model for that file as well. Do not delete id-table-schema.xml if you plan on using Torque's IDBroker service, which is used in this tutorial.
There are several items of importance to note. The database element's name attribute must be the same as the database name specified by the databaseUrl property in project.properties; likewise, the run-time properties (described in the next section) should also reflect this value. Failure to do so will prevent Torque from creating your database tables (if instructed to do so) or prevent your object model from working properly.
Another item of importance is the database element's defaultIdMethod attribute. This attribute specifies the default method that Torque will use to generate IDs for primary keys (columns with the primaryKey attribute set to true: book_id, publisher_id, and author_id) in your database tables. There are several possible values:
Property | Description |
---|---|
idbroker | Instructs Torque to use its IDBroker service to generate IDs in a database agnostic manner. This is the method that will be used in this tutorial. |
native | Instructs Torque to use the underlying database's mechanism to generate IDs (varies per database). |
none | Instructs Torque to not generate IDs. This can be useful in some situations (an example is described below). |
autoincrement | This method has been deprecated. Use the native method instead. |
sequence | This method has been deprecated. Use the native method instead. |
The defaultIdMethod selected will be used for all tables in your schema unless an individual table element contains the idMethod attribute, in which case, its value will override the defaultIdMethod. idMethod takes the same values as defaultIdMethod.
One common reason that a table might override the defaultIdMethod is when a table is composed only of foreign keys (i.e. a ‘junction entity’ in database-speak). In this case, all columns should be defined as primary keys because they are all needed to declare a row as unique. However, Torque should not generate primary key IDs for objects in this table because the objects that compose the table already have primary key IDs. Thus, the idMethod attribute of the table must be set to none. For example, if the book table defined above did not have any additional attributes other than a publisher_id and author_id, the schema for the book table should be defined as:
Another common mistake is to forget that XML is case-sensitive. All of the elements and attributes must be specified according to the DTD for the database schema. In addition, you must include the XML declaration and DTD specification in your database schema file. Failure to do so can result in errors.
Finally, you must also edit (or add if its not present) the name attribute to the database element in id-table-schema.xml. The value should be identical to the value in your database schema file. This will instruct Torque to create id-table in the same database as your schema. Below is the file used in this example:
Torque uses the database schema files to generate your object model and Java classes to support it. In addition, Torque generates SQL that can be used to create your databases and tables from these schemas. In the next section, we will conclude the configuration of Torque by editing the Torque run-time properties. For additional information on the XML elements and attributes, please refer to the Torque Schema Reference.
The last step in the configuration of Torque are the Torque run-time properties. As the name suggests, these properties are used when your application is executing the object model code generated by Torque. The run-time properties control logging and database parameters such as drivers, usernames, and passwords. These properties can be saved in any file because your application must explicitly initialize Torque (as you'll see later in this tutorial).
The runtime distribution archive includes an Ant build file that can be used to generate your Torque runtime configuration. When you unpack the archive you will see the following:
To generate Torque.properties for your project you can edit the input
properties in master/default.properties
and then run
ant
to regenerate Torque.properties
. Note that
the sample and generated Torque.properties
file contains
a good amount of information regarding the available Torque run-time
properties.
For simplicity, we'll just create our own Torque.propereties
file (again, this tutorial will guide you through the bare minimum to
get your application up and running). Create a new file
called Torque.properties in the top-level directory of your
project and add the following lines to it:
We are using the commons-dbcp for our connection pool - see
Pool-config Howto
details of the available DataSource
factories.
Property | Description |
---|---|
torque.database.default | Torque has the ability to use multiple databases. This property specifies which database is to be used as the default. |
torque.database.XXX.adapter | Torque has the ability to deal with multiple database systems. This property specifies the database adapter to use. |
torque.dsfactory.XXX.factory | The factory class that will be used to provide database connections. |
torque.dsfactory.XXX.connection.driver | The JDBC database driver to use when connecting to your database. |
torque.database.XXX.connection.url | The URL that will be used to access your database. Torque's generated object model will perform all database operations using this URL. This value should reflect the database name specified in your database schema file (see the database element's name attribute). |
torque.database.XXX.connection.username | The username that has sufficient privileges to access your database. This user does not require privileges to create and drop tables, unlike the username that was specified in project.properties. |
torque.database.XXX.connection.password | The password for the specified username. |
It is worth re-iterating that these run-time properties are not used by Torque when generating your object model and creating your database. They are used only by the application utilizing the Torque-generated object model classes at run-time.
To have any logging messages sent to the console add the following
to a file named log4j.properties
and place this in
your classpath (putting it in your target/classes
will do the trick).
Property | Description |
---|---|
log4j.rootCategory |
Torque uses
Commons
Logging, which in turn by default uses
Log4J
for a logging. This parameter configures
the Log4J system to log all messages but debug messages (use
DEBUG rather than INFO to have get
the debug messages too).
|
log4j.appender.default | Configures Log4J to send all logging messages to the console. Log4J can just as easily send all logging to a file or a syslog server. |
log4j.appender.default.layout | Log4J logs messages using a layout. Layouts can be very simple or complicated. This tutorial uses the very rudimentary SimpleLayout. |
In order to be able to compile and use the generated class files it is
necessary to include the Torque runtime jar file and jar files for all of
the necessary dependencies in the classpath of your project. The necessary
jars are included in the torque/lib
directory of the Torque
runtime. If you are using Maven to build your project it may be easiest to
copy the necessary dependencies from the
Torque
runtime POM.
Note: There is no need to include the torque-gen jar file in your project classath, including it may adversly affect the logging configuration of your application.
That completes the configuration of Torque. You are now ready to start building your object model and creating your database.
Next we will look Invoking Torque.