org.apache.torque
Class Torque

java.lang.Object
  org.apache.torque.Torque

public class Torque
extends java.lang.Object

A static facade wrapper around the Torque implementation (which is in TorqueInstance).

Version:

$Id: Torque.java 493449 2007-01-06 11:46:50Z tv $

Author:

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

Field Summary

static java.lang.String	CACHE_KEY property to determine whether caching is used.
static java.lang.String	DATABASE_DEFAULT Deprecated. is not used any more. Use DATABASE_KEY and DEFAULT_KEY instead
static java.lang.String	DATABASE_KEY The prefix for configuring the database adapters and the default database.
static java.lang.String	DEFAULT_KEY The key used to configure the name of the default database.
static java.lang.String	MANAGER_PREFIX A prefix for Manager properties in the configuration.
static java.lang.String	MANAGER_SUFFIX A Service property determining its implementing class name .
static java.lang.String	TORQUE_KEY The prefix for all configuration keys used by Torque.

Constructor Summary

Torque()
C'tor for usage with the Stratum Lifecycle.

Method Summary

static void	closeConnection(java.sql.Connection con) Closes a connection.
static org.apache.commons.configuration.Configuration	getConfiguration() Get the configuration for this component.
static java.sql.Connection	getConnection() This method returns a Connection from the default pool.
static java.sql.Connection	getConnection(java.lang.String name) This method returns a Connecton using the given database name.
static java.sql.Connection	getConnection(java.lang.String name, java.lang.String username, java.lang.String password) This method returns a Connecton using the given parameters.
static Database	getDatabase(java.lang.String name) Returns the database for the given key.
static DatabaseMap	getDatabaseMap() Returns the default database map information.
static DatabaseMap	getDatabaseMap(java.lang.String name) Returns the database map information.
static java.util.Map	getDatabases() Returns a Map containing all Databases registered to Torque.
static DB	getDB(java.lang.String name) Returns database adapter for a specific connection pool.
static java.lang.String	getDefaultDB() Returns the name of the default database.
static TorqueInstance	getInstance() Retrieves the single TorqueInstance used by this class.
static AbstractBaseManager	getManager(java.lang.String name) This method returns a Manager for the given name.
static 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.
static MapBuilder	getMapBuilder(java.lang.String className) Get a MapBuilder
static java.lang.String	getSchema(java.lang.String name) This method returns the current schema for a database connection
static void	init(org.apache.commons.configuration.Configuration conf) Initialization of Torque with a properties file.
static void	init(java.lang.String configFile) Initialization of Torque with a properties file.
static boolean	isInit() Determine whether Torque has already been initialized.
static void	registerMapBuilder(MapBuilder builder) Register a MapBuilder
static void	registerMapBuilder(java.lang.String className) Register a MapBuilder
static void	setConfiguration(org.apache.commons.configuration.Configuration conf) Sets the configuration for Torque and all dependencies.
static void	setInstance(TorqueInstance instance) Sets the single TorqueInstance used by this class.
static void	setSchema(java.lang.String name, java.lang.String schema) Sets the current schema for a database connection
static void	shutdown() Shuts down the service.

Methods inherited from class java.lang.Object

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

Field Detail

TORQUE_KEY

public static final java.lang.String TORQUE_KEY

The prefix for all configuration keys used by Torque.

See Also:

Constant Field Values

DATABASE_KEY

public static final java.lang.String DATABASE_KEY

The prefix for configuring the database adapters and the default database.

See Also:

Constant Field Values

DEFAULT_KEY

public static final java.lang.String DEFAULT_KEY

The key used to configure the name of the default database.

See Also:

Constant Field Values

DATABASE_DEFAULT

public static final java.lang.String DATABASE_DEFAULT

Deprecated. is not used any more. Use DATABASE_KEY and DEFAULT_KEY instead

Name of property that specifies the default map builder and map.

See Also:

Constant Field Values

MANAGER_PREFIX

public static final java.lang.String MANAGER_PREFIX

A prefix for Manager properties in the configuration.

See Also:

Constant Field Values

MANAGER_SUFFIX

public static final java.lang.String MANAGER_SUFFIX

A Service property determining its implementing class name .

See Also:

Constant Field Values

CACHE_KEY

public static final java.lang.String CACHE_KEY

property to determine whether caching is used.

See Also:

Constant Field Values

Constructor Detail

Torque

public Torque()

C'tor for usage with the Stratum Lifecycle. TODO: Should be made private or protected once Stratum is removed.

Method Detail

getInstance

public static TorqueInstance getInstance()

Retrieves the single TorqueInstance used by this class.

Returns:

Our singleton.

setInstance

public static void setInstance(TorqueInstance instance)

Sets the single TorqueInstance used by this class. This is used by the Avalon component to make sure that only one instance of Torque exists

Parameters:

instance - Our singleton.

init

public static 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 static void init(org.apache.commons.configuration.Configuration conf)
                 throws TorqueException

Initialization of Torque with a properties file.

Parameters:

conf - The Torque configuration.

Throws:

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

isInit

public static boolean isInit()

Determine whether Torque has already been initialized.

Returns:

true if Torque is already initialized

setConfiguration

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

Sets the configuration for Torque and all dependencies.

Parameters:

conf - the Configuration

getConfiguration

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

Get the configuration for this component.

Returns:

the Configuration

getManager

public static 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 static 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 static 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 static 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 static 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.

registerMapBuilder

public static void registerMapBuilder(java.lang.String className)

Register a MapBuilder

Parameters:

className - the MapBuilder

registerMapBuilder

public static void registerMapBuilder(MapBuilder builder)

Register a MapBuilder

Parameters:

builder - the instance of the MapBuilder

getMapBuilder

public static 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 static java.sql.Connection getConnection()
                                         throws TorqueException

This method returns a Connection from the default pool.

Returns:

The requested connection.

Throws:

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

getConnection

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

This method returns a Connecton using the given database name.

Parameters:

name - The database name.

Returns:

a database connection

Throws:

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

getConnection

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

This method returns a Connecton 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 static DB getDB(java.lang.String name)
                throws TorqueException

Returns database adapter for a specific connection pool.

Parameters:

name - A pool name.

Returns:

The corresponding database adapter.

Throws:

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

getDefaultDB

public static 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 static void closeConnection(java.sql.Connection con)

Closes a connection.

Parameters:

con - A Connection to close.

setSchema

public static 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 static 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 static Database getDatabase(java.lang.String name)
                            throws TorqueException

Returns the database for the given key.

Parameters:

name - The database name.

Returns:

the Database for the given name, or null if no database exists for the given name.

Throws:

TorqueException - if Torque is not yet initialized.

getDatabases

public static 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. However, Databases should be initialized in the init() method, so this will not happen if Torque is used properly.

Returns:

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

Throws:

TorqueException - if Torque is not yet initialized.