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 autogenerated
MapBuilder
classes. This happens automatically,
so usually you need not bother about it.
The detailed procedure is the following: 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.
This means that 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, call the Database Map's initialize() method. This method triggers a generated class to insert all tables into the database map.
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).
Previously, Torque provided an internal map between many Drivers
and a set of adapter classes which are used to account for
differences among databases.
This arrangement is no longer possible using DataSource
,
so the adapter must be given in the configuration.
The adapter property is given as:
torque.database.bookstore.adapter=mysql
The valid values are:
|
|
|
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
Torque can use any connection pool implementing the interface
DataSource
. Torque expects a factory that can return a
DataSource
and 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.
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.
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
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).
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).
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