Torque Directory Structure

Here is what the Torque directory structure looks like in SVN:

    db-torque/
      profile/         <--- testing profiles
      src/             <--- sources
        conf/          <--- runtime configuration
        generator/     <--- home of torque-gen
          src/         <--- sources
            conf/      <--- generator configuration and ant buildfile
            dtd/       <--- DTD for schema.xml files
            java/      <--- java sources for generator
            schema/    <--- needed schema files (IDBroker)
            templates/ <--- templates for sql- and om- generation
            test/      <--- junit tests
          xdocs/       <--- docs for generator in anakia xml format
        java/          <--- java sources for runtime
        maven-plugin   <--- home of maven-plugin
          xdocs/       <--- docs for maven-plugin in anakia xml format
        rttest/        <--- sources for the runtime tests
        test/          <--- junit tests
      xdocs/           <--- docs for runtime in anakia xml format
      

Building from SVN

The Torque build process uses Maven. Before you begin, you'll need to check out the db-torque SVN repository (if you are not familiar with the Apache SVN repositories, please refer to the documentation). Specific information for Torque is available on the Source Repository page.

To build the Torque generator jar, first execute maven jar:install in the src/generator/src/templates directory to install a copy of the templates jar in your local Maven repository. Note that maven jar:jar does not suffice here because the main generator jar depends upon the template jar. Afterwards, execute maven jar:jar in the src/generator directory to build the generator jar (maven jar:install to install a copy of the jar in your local Maven repository).

To build and install the Torque maven-plugin execute maven plugin:install in the src/maven-plugin directory.

To build the Torque runtime jar execute maven jar:jar in the root directory of the project (maven jar:install to install a copy of the jar in your local Maven repository).

Testing

You must define a profile in your ${user.home}/build.properties file

    torque.testProfile=profile/oracle.profile
      

Edit the profile to match your database settings. To start the runtime tests simply type:

    maven runtime:test
      

Please report any problems to the torque-dev mailing list.

Initialisation of the Torque Runtime

This section is meant to to provide some insight into the initialisation procedure of Torque. On initialisation, Torque needs to provide the following resources to work properly

  • The name of the default database, configured by the key torque.database.default
  • The adapters, configured by the keys torque.database.<databaseName>.adapter
  • The DataSourceFactories, configured by the keys torque.dsfactory.<databaseName>.<property>. For some DataSourceFactories, default values can be defined under torque.defaults.<property>.
  • The Database maps. Each peer class registers its Map builder with the Torque runtime when the Base Peer Class is loaded (Usually, a peer class is loaded if one of the constants for a column name is accessed, or a method is called). If Torque is already initialized when the Peer class is loaded (this is usually the case) the Map Builder builds the database map instantly and makes it avaliable to Torque. If Torque is not yet initialized, the Peer class stores the Map Builder with Torque, which builds the database Map when Torque is initialized.
  • The managers. These are not used in most setups.

Internal resources used by the Torque Runtime

Default database name

Torque can be used with several databases at once. The resources for each database are usually kept in Maps where the key is the name of the database. To make things easier for people who use only one database, Torque supports the notion of a default database. This allows it to provide convenience methods like Torque.getConnection() where no database name must be specified. These methods refer to the default database, in contrast to e.g. Torque.getConnection(String) where the name of the database must be supplied explicitly.

Adapters

Although all databases supported by Torque understand SQL, there are differences in the behaviour of the databases which the Torque runtime needs to know about. For example, the standard (String) format of a date object in an oracle9i database is different from a postgresql database. The adapter for a database provides the necessary methods to hide such differences from the user. For example, the adapter provides a method to create a String in the database's preferred format from a Date object.

Adapters are subclasses of the org.apache.torque.adapter.DB class. The adapters are stored in the private map TorqueInstance.apdapterMap; the key of the map is the name of the database (e.g. "bookstore"), and the value of the map is the adapter. The adapter for a given key can be retrieved via the method Torque.getDB(key).

DataSourceFactories

To access a database, a connection must be made to the database. A DataSource is an object which can provide Connections to the database. A DataSourceFactory is used to configure and provide one DataSource.

DataSourceFactories must implement the interface org.apache.torque.dsfactory.DataSourceFactory. The DataSourceFactories are stored in the private map TorqueInstance.dsFactoryMap; the key of the map is the name of the database (e.g. "bookstore"), and the value of the map is the DataSourceFactory. The DataSourceFactory for a given key can not be retrieved by a public method; however, a connection from the DataSource for the DataSourceFactory for a given key can be obtained by Torque.getConnection(key);

Database maps

Torque sometimes needs to know internals about the structure of the database, e.g. which table contains which columns etc. This knowledge is kept in the database maps.

Database Maps are instances of the class org.apache.torque.map.DatabaseMap. They are kept in the instance variable TorqueInstance.dbMaps. The Map for the database with the name key can be retrieved by the method Torque.getDatabaseMap(key).