org.apache.torque
Class TorqueInstance

java.lang.Object
  org.apache.torque.TorqueInstance

Direct Known Subclasses:

TorqueComponent

public class TorqueInstance
extends java.lang.Object

The core of Torque's implementation. Both the classic Torque static wrapper and the TorqueComponent Avalon implementation leverage this class.

Version:

$Id: TorqueInstance.java 571790 2007-09-01 12:40:44Z tv $

Author:

Daniel Rall, Magn?s ??r Torfason, Jason van Zyl, Rafal Krzewski, Martin Poeschl, Henning P. Schmiedehausen, Kurt Schrader, Thomas Vandahl

Constructor Summary

TorqueInstance()
Creates a new instance with default configuration.

Method Summary

void	closeConnection(java.sql.Connection con) Closes a connection.
org.apache.commons.configuration.Configuration	getConfiguration() Get the configuration for this component.
java.sql.Connection	getConnection() This method returns a Connection from the default pool.
java.sql.Connection	getConnection(java.lang.String name) Returns a database connection to the database with the key name.
java.sql.Connection	getConnection(java.lang.String name, java.lang.String username, java.lang.String password) This method returns a Connection using the given parameters.
Database	getDatabase(java.lang.String databaseName) Returns the database for the key databaseName.
DatabaseMap	getDatabaseMap() Returns the default database map information.
DatabaseMap	getDatabaseMap(java.lang.String name) Returns the database map information.
java.util.Map	getDatabases() Returns a Map containing all Databases registered to Torque.
DataSourceFactory	getDataSourceFactory(java.lang.String name) Returns the DataSourceFactory for the database with the name name.
DB	getDB(java.lang.String name) Returns the database adapter for a specific database.
java.lang.String	getDefaultDB() Returns the name of the default database.
AbstractBaseManager	getManager(java.lang.String name) This method returns a Manager for the given name.
AbstractBaseManager	getManager(java.lang.String name, java.lang.String defaultClassName) This methods returns either the Manager from the configuration file, or the default one provided by the generated code.
MapBuilder	getMapBuilder(java.lang.String className) Get a MapBuilder
java.util.Map	getMapBuilders() Get the registered MapBuilders
Database	getOrCreateDatabase(java.lang.String databaseName) Returns the database for the key databaseName.
java.lang.String	getSchema(java.lang.String name) This method returns the current schema for a database connection
void	init(org.apache.commons.configuration.Configuration conf) Initialization of Torque with a Configuration object.
void	init(java.lang.String configFile) Initialization of Torque with a properties file.
protected void	initManagerMappings(org.apache.commons.configuration.Configuration conf) Creates a mapping between classes and their manager classes.
boolean	isInit() Determine whether Torque has already been initialized.
void	registerMapBuilder(MapBuilder builder) Register a MapBuilder
void	registerMapBuilder(java.lang.String className) Register a MapBuilder
void	setConfiguration(org.apache.commons.configuration.Configuration conf) Sets the configuration for Torque and all dependencies.
void	setSchema(java.lang.String name, java.lang.String schema) Sets the current schema for a database connection
void	shutdown() Shuts down the service.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TorqueInstance

public TorqueInstance()

Creates a new instance with default configuration.

See Also:

resetConfiguration()

Method Detail

init

public void init(java.lang.String configFile)
          throws TorqueException

Initialization of Torque with a properties file.

Parameters:

configFile - The absolute path to the configuration file.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

init

public void init(org.apache.commons.configuration.Configuration conf)
          throws TorqueException

Initialization of Torque with a Configuration object.

Parameters:

conf - The Torque configuration.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

initManagerMappings

protected void initManagerMappings(org.apache.commons.configuration.Configuration conf)
                            throws TorqueException

Creates a mapping between classes and their manager classes. The mapping is built according to settings present in properties file. The entries should have the following form:

 torque.managed_class.com.mycompany.Myclass.manager= \
          com.mycompany.MyManagerImpl
 services.managed_class.com.mycompany.Myotherclass.manager= \
          com.mycompany.MyOtherManagerImpl
 

Generic ServiceBroker provides no Services.

Parameters:

conf - the Configuration representing the properties file

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

isInit

public boolean isInit()

Determine whether Torque has already been initialized.

Returns:

true if Torque is already initialized

setConfiguration

public void setConfiguration(org.apache.commons.configuration.Configuration conf)

Sets the configuration for Torque and all dependencies. The prefix TORQUE_KEY needs to be removed from the configuration keys for the provided configuration.

Parameters:

conf - the Configuration.

getConfiguration

public org.apache.commons.configuration.Configuration getConfiguration()

Get the configuration for this component.

Returns:

the Configuration

getManager

public AbstractBaseManager getManager(java.lang.String name)

This method returns a Manager for the given name.

Parameters:

name - name of the manager

Returns:

a Manager

getManager

public AbstractBaseManager getManager(java.lang.String name,
                                      java.lang.String defaultClassName)

This methods returns either the Manager from the configuration file, or the default one provided by the generated code.

Parameters:

name - name of the manager

defaultClassName - the class to use if name has not been configured

Returns:

a Manager

shutdown

public void shutdown()
              throws TorqueException

Shuts down the service. This method halts the IDBroker's daemon thread in all of the DatabaseMap's. It also closes all SharedPoolDataSourceFactories and PerUserPoolDataSourceFactories initialized by Torque.

Throws:

TorqueException - if a DataSourceFactory could not be closed cleanly. Only the first exception is rethrown, any following exceptions are logged but ignored.

getDatabaseMap

public DatabaseMap getDatabaseMap()
                           throws TorqueException

Returns the default database map information.

Returns:

A DatabaseMap.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getDatabaseMap

public DatabaseMap getDatabaseMap(java.lang.String name)
                           throws TorqueException

Returns the database map information. Name relates to the name of the connection pool to associate with the map.

Parameters:

name - The name of the database corresponding to the DatabaseMap to retrieve.

Returns:

The named DatabaseMap.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getMapBuilders

public java.util.Map getMapBuilders()

Get the registered MapBuilders

Returns:

the MapBuilder cache

registerMapBuilder

public void registerMapBuilder(java.lang.String className)

Register a MapBuilder

Parameters:

className - the MapBuilder

registerMapBuilder

public void registerMapBuilder(MapBuilder builder)

Register a MapBuilder

Parameters:

builder - the instance of the MapBuilder

getMapBuilder

public MapBuilder getMapBuilder(java.lang.String className)
                         throws TorqueException

Get a MapBuilder

Parameters:

className - of the MapBuilder

Returns:

A MapBuilder, not null

Throws:

TorqueException - if the Map Builder cannot be instantiated

getConnection

public java.sql.Connection getConnection()
                                  throws TorqueException

This method returns a Connection from the default pool.

Returns:

The requested connection, never null.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getConnection

public java.sql.Connection getConnection(java.lang.String name)
                                  throws TorqueException

Returns a database connection to the database with the key name.

Parameters:

name - The database name.

Returns:

a database connection, never null.

Throws:

TorqueException - If no DataSourceFactory is configured for the named database, the connection information is wrong, or the connection cannot be returned for any other reason.

getDataSourceFactory

public DataSourceFactory getDataSourceFactory(java.lang.String name)
                                       throws TorqueException

Returns the DataSourceFactory for the database with the name name.

Parameters:

name - The name of the database to get the DSF for.

Returns:

A DataSourceFactory object, never null.

Throws:

TorqueException - if Torque is not initiliaized, or no DatasourceFactory is configured for the given name.

getConnection

public java.sql.Connection getConnection(java.lang.String name,
                                         java.lang.String username,
                                         java.lang.String password)
                                  throws TorqueException

This method returns a Connection using the given parameters. You should only use this method if you need user based access to the database!

Parameters:

name - The database name.

username - The name of the database user.

password - The password of the database user.

Returns:

A Connection.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getDB

public DB getDB(java.lang.String name)
         throws TorqueException

Returns the database adapter for a specific database.

Parameters:

name - the name of the database to get the adapter for.

Returns:

The corresponding database adapter, or null if no database adapter is defined for the given database.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getDefaultDB

public java.lang.String getDefaultDB()

Returns the name of the default database.

Returns:

name of the default DB, or null if Torque is not initialized yet

closeConnection

public void closeConnection(java.sql.Connection con)

Closes a connection.

Parameters:

con - A Connection to close.

setSchema

public void setSchema(java.lang.String name,
                      java.lang.String schema)
               throws TorqueException

Sets the current schema for a database connection

Parameters:

name - The database name.

schema - The current schema name.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getSchema

public java.lang.String getSchema(java.lang.String name)
                           throws TorqueException

This method returns the current schema for a database connection

Parameters:

name - The database name.

Returns:

The current schema name. Null means, no schema has been set.

Throws:

TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getDatabase

public Database getDatabase(java.lang.String databaseName)
                     throws TorqueException

Returns the database for the key databaseName.

Parameters:

databaseName - the key to get the database for.

Returns:

the database for the specified key, or null if the database does not exist.

Throws:

TorqueException - if Torque is not yet initialized.

getDatabases

public java.util.Map getDatabases()
                           throws TorqueException

Returns a Map containing all Databases registered to Torque. The key of the Map is the name of the database, and the value is the database instance.
Note that in the very special case where a new database which is not configured in Torque's configuration gets known to Torque at a later time, the returned map may change, and there is no way to protect you against this.

Returns:

a Map containing all Databases known to Torque, never null.

Throws:

TorqueException - if Torque is not yet initialized.

getOrCreateDatabase

public Database getOrCreateDatabase(java.lang.String databaseName)

Returns the database for the key databaseName. If no database is associated to the specified key, a new database is created, mapped to the specified key, and returned.

Parameters:

databaseName - the key to get the database for.

Returns:

the database associated with specified key, or the newly created database, never null.