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
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).
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.
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
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.
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).
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);
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).