+ 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. +

+ +

+ + +

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

+ + +