Initialisation

Torque is initialized by calling one of the Torque.init() methods. Torque must be initialized before it is used, and it must not be initialized more than once.

When calling one of the Torque.init() methods, you must supply either the path to a configuration file or the configuration itself. The configuration must contain a valid DataSource, a default database handle, and an adapter for each DataSource. For details, see the section Configuration below.

Upon initialisation, also the runtime model of the database, i.e. the DatabaseMaps, are built by generated MapBuilder classes. This happens automatically, so usually you need not bother about it.

Also, a runtime model of the database (accessible via the methods Torque.getDatabaseMap()) is built during Torque startup: Each peer class constructs its runtime model when the Base Peer Class is loaded and registers the table model with the corresponding database model in the Torque runtime. (Usually, a peer class is loaded if one of the constants for a column name is accessed, or a method is called). If the property torque.om.generateMapInit was set to true while generating the torque classes, the map builder will then also load the peer classes for all other tables in the same database, which will register all tables in the database.

This means that possibly you will not see a table in the database map if its peer class is not loaded. If you want to make sure that all tables appear in the Database map, set the property torque.om.generateMapInit to true when generating the torque classes, and then call the initDatabaseMap() method of any generated peer class.

Configuration

Database handles

A database handle is the name attribute that was used in the <database> tag of the schema.xml file. If the name attribute is not used, then the handle would be 'default'.

In all examples that follow we will use the handle 'bookstore'. As Torque has the ability to use multiple databases you can tell it which one to use by default thus:

torque.database.default=bookstore

The handle name 'default' is reserved, as Torque uses it as a reference to the default database. So you should not define the handle 'default' yourself (but of course you can use it e.g. in generated code).

Database Adapters

For each database handle, an adapter must be configured (adapters are used to account for differences among databases). The adapter property is given as:

torque.database.bookstore.adapter=mysql

The valid values are:

  • derby
  • hsqldb
  • mssql
  • mysql
  • oracle
  • postgresql

For application in environments that should support different databases, you can use the special adapter auto, which tries to detect the correct adapter type from JDBC metadata.

If you want to use a custom adapter that is not supplied by Torque, you need to choose a custom key (not one of the above) and specify the class of the adapter. For example, if the adapter class is com.acme.DBMyAdapter, you could use the following snippet in your configuration file:

torque.database.bookstore.adapter=myadapter
torque.database.bookstore.adapter.myadapter.className=com.acme.DBMyAdapter
      

Connection pool

Torque can use any connection pool implementing the interface DataSource. Torque expects a factory that can return a DataSource which can be configured using Torque's configuration file.

Torque provides factories to use the commons-dbcp pools as well as a general factory that uses JNDI to retrieve the DataSource. The JNDI factory looks up a DataSource bound to JNDI; it also provides a simple property file based way to configure and deploy most DataSource's, though in many cases a pool may already be bound to JNDI and Torque only needs to use it.
See the sections SharedPoolDataSourceFactory and JndiDataSourceFactory for the most commonly used built-in data source factories in Torque.

Multiple databases

The configuration of multiple databases is very similar to the configurations described in the rest of this section, however you will need to define more than one database handle.

SharedPoolDataSourceFactory

This factory uses the SharedDataSource available in the commons-dbcp package. SharedPoolDataSourceFactory provides an easy way to configure this pool and it assumes you will have a JDBC Driver class providing the physical database connections. Again, you must let Torque know you are using this factory:

torque.dsfactory.bookstore.factory= \
  org.apache.torque.dsfactory.SharedPoolDataSourceFactory

Then there are two sets of properties related to the pool configuration and settings for making the connection to the database. The "connection" set contains all information to create a physical connection to the database:

torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.connection.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.bookstore.connection.user = root
torque.dsfactory.bookstore.connection.password = 1234

The "pool" set contains information of how the pool should handle the physical connections. See the dbcp reference for possible properties. For example, you could use:

torque.dsfactory.bookstore.pool.maxActive=30
torque.dsfactory.bookstore.pool.testOnBorrow=true
torque.dsfactory.bookstore.pool.validationQuery=SELECT 1

Torque also includes a factory for the PerUserPoolDataSource. Please see the commons-dbcp javadoc for more info.

JndiDataSourceFactory

This factory is used if the DataSource is to be available via JNDI. It is possible to use this factory to deploy a DataSource into JNDI, but in many cases for using this factory the DataSource is already deployed. This factory is specified with the following property:

torque.dsfactory.bookstore.factory = \
  org.apache.torque.dsfactory.JndiDataSourceFactory

Using JndiDataSourceFactory with pre-configured pool

In this section, it is assumed that a DataSource is available via JNDI. Usually, a J2EE environment can be configured to bind a DataSource into JNDI for further use. For example, Tomcat can bind a DataSource into JNDI, see the Tomcat Documentation for details.

If a pool is known to already be available via JNDI, only one more property is required for Torque:

torque.dsfactory.bookstore.jndi.path=jdbc/bookstore

This line defines the string that will be used to lookup the DataSource within the default JNDI InitialContext. If everything is configured and the default InitialContext contains the DataSource, this is all that is needed. The default InitialContext is chosen according to the rules given in the class's javadoc. If the default has not been configured, you can specify any other environment properties that are needed to instantiate the InitialContext as extra properties of the form, torque.jndi.<handle>.<env-var>. A couple of examples are shown below:

torque.dsfactory.bookstore.jndi.java.naming.factory.initial = \
  org.apache.naming.java.javaURLContextFactory
torque.dsfactory.bookstore.jndi.java.naming.factory.url.pkgs = \
  org.apache.naming

Such environment settings will most likely not be necessary when running within a J2EE container, but they are useful in other cases.

One of the advantages of JNDI is that it supports changing the DataSource on the fly. On the other hand this means that the actual DataSource object must be looked up in the context with every database operation. To avoid this, the factory provides a simple caching mechanism, which stores the DataSource object for a configurable amount of time (im ms). The time between two lookups is specified as follows:

torque.dsfactory.bookstore.jndi.ttl=60000

This property is optional. If not specified, it defaults to 0 (no caching).

Using Torque to bind a pool to JNDI

Generally a J2EE environment such as a servlet engine or application server is expected to provide a jdbc2 compatible connection pool. If your application is not running within such an environment, or even if it is and Torque is your only use of a connection pool, Torque provides a simple properties file method of configuring a DataSource and deploying it via JNDI.

Too use this feature, you need to specify the JNDI configuration parameters as shown above, setting the factory and the JNDI path. In addition to that, you need to configure the DataSource which should be bound into JNDI. The one property that is necessary for all DataSource's is the classname of the DataSource implementation. Beyond that the properties are implementation specific, depending on the DataSource's setters for the configuration. You can specify the values for the setters as properties in the configuration file. For example, dbcp's BasicDataSource could be configured as shown below:

torque.dsfactory.bookstore.datasource.classname= \
  org.apache.commons.dbcp.BasicDataSource
torque.dsfactory.bookstore.datasource.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.datasource.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.bookstore.datasource.user = root
torque.dsfactory.bookstore.datasource.password = 1234

plus the properties for the factory and the jndi path:

torque.dsfactory.bookstore.factory = \
  org.apache.torque.dsfactory.JndiDataSourceFactory
torque.dsfactory.bookstore.jndi.path=jdbc/bookstore

Note that in dbcp 1.2.1, the SharedPoolDataSourceFactory and PerUserPoolDataSourceFactory cannot be bound into jndi (this is a dbcp problem).

Using Database Schemas (Namespaces)

Configuring Schema Names at Runtime

You can configure the default database schema (mysql-speak: "database") which is prepended to table names in the runtime either per database or as a global setting. (The old way of configuring a schema per-datasource still works but is deprecated and will be removed in the future). Defining a schema allows e.g. in oracle to access another database schema than the one of the user which connects to the database.
To configure a schema, add the following statements to the torque.properties file:

      ##
      ## Selecting a database schema for all data sources:
      ##
      
      # All data sources use the public schema unless overridden
      torque.defaults.schema = public
      
      ##
      ## Selecting the schema 'foo' for the database "bar"
      
      # use the foo database
      torque.database.bar.schema = foo
      
      

If no schema is configured in the torque properties or in other places, Torque will not qualify its table names.

Other Means to Control schemas

You can change the schema which is used for unqualified table names per-Database in the Torque Runtime. The schema name is queried dynamically whenever a Torque command accesses the database and can be changed (if you have the same table layout on multiple schemas, you can reuse your Peer classes thus reducing the number of classes used).

      /* Set the schema name for database "bar" to "foo" */
      
      Torque.setSchema("bar", "foo");
      
      /* Reset the schema names (no longer qualify
       * accesses to the tables of the "bar" database
       */
      Torque.setSchema("bar", null);
      
      /* Get the current schema for the "bar" database */
      String barSchema = Torque.getSchema("bar");
      
      

Examples

In this section, the bits explained above are assembled to full examples of configuration files for the Torque runtime. Do not forget to change the values to match your database environment.

Using SharedPoolDataSourceFactory (this example is also used in the Tutorial):

torque.database.default = bookstore
torque.database.bookstore.adapter = mysql

#Using commons-dbcp
torque.dsfactory.bookstore.factory =\
  org.apache.torque.dsfactory.SharedPoolDataSourceFactory
torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.connection.url =\
  jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.bookstore.connection.user = user
torque.dsfactory.bookstore.connection.password = password

Using JndiDataSourceFactory with externally bound DataSource:

torque.database.default = bookstore
torque.database.bookstore.adapter = mysql
torque.dsfactory.bookstore.factory =\
  org.apache.torque.dsfactory.JndiDataSourceFactory
torque.dsfactory.bookstore.jndi.path = jdbc/jndiTestDataSource

Using JndiDataSourceFactory to bind a DataSource to jndi:

torque.database.default = bookstore
torque.database.bookstore.adapter = mysql
torque.dsfactory.bookstore.factory =\
  org.apache.torque.dsfactory.JndiDataSourceFactory
torque.dsfactory.bookstore.jndi.path = jdbc/jndiTestDataSource
torque.dsfactory.bookstore.jndi.java.naming.factory.initial =\
  org.apache.naming.java.javaURLContextFactory
torque.dsfactory.bookstore.datasource.classname =\
  org.apache.commons.dbcp.BasicDataSource
torque.dsfactory.bookstore.datasource.password = mysql
torque.dsfactory.bookstore.datasource.username = root
torque.dsfactory.bookstore.datasource.driverClassName =\
  org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.datasource.url =\
  jdbc:mysql://localhost:3306/bookstore