org.apache.torque
Class Torque

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

public final class Torque
extends Object

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

Version:
$Id: Torque.java 1437968 2013-01-24 11:54:14Z tv $
Author:
Daniel Rall, Magn�s ��r Torfason, Jason van Zyl, Rafal Krzewski, Martin Poeschl, Henning P. Schmiedehausen, Kurt Schrader

Field Summary
static String CACHE_KEY
          Name of config property to determine whether caching is used.
static String DATABASE_KEY
          The prefix for configuring the database adapters and the default database.
static String DEFAULT_KEY
          The key used to configure the name of the default database.
static String DEFAULT_SCHEMA_KEY
          default schema name for the configuration
static String DEFAULTS_KEY
          "defaults" Key for the configuration
static String MANAGER_PREFIX
          A prefix for Manager properties in the configuration.
static String MANAGER_SUFFIX
          A Service property determining its implementing class name .
static String SCHEMA_KEY
          "schema" Key for the configuration
static String TORQUE_KEY
          The prefix for all configuration keys used by Torque.
static String TRANSACTION_MANAGER_KEY
          The prefix for configuring the transaction manger.
 
Method Summary
static void closeConnection(Connection con)
          Closes a connection.
static Adapter getAdapter(String name)
          Returns the database adapter for a specific database name.
static org.apache.commons.configuration.Configuration getConfiguration()
          Get the configuration for this component.
static Connection getConnection()
          This method returns a Connection from the default pool.
static Connection getConnection(String name)
          This method returns a Connecton using the given database name.
static Connection getConnection(String name, String username, String password)
          This method returns a Connecton using the given parameters.
static Database getDatabase(String name)
          Returns the database for the given key.
static DatabaseMap getDatabaseMap()
          Returns the default database map information.
static DatabaseMap getDatabaseMap(String name)
          Returns the database map information for a given database.
static Map<String,Database> getDatabases()
          Returns a Map containing all Databases registered to Torque.
static Adapter getDB(String name)
          Deprecated. use getAdapter(String) instead. This method will be removed in a future version of Torque.
static String getDefaultDB()
          Returns the name of the default database.
static TorqueInstance getInstance()
          Retrieves the single TorqueInstance used by this class.
static
<T extends AbstractBaseManager<? extends Persistent>>
T
getManager(String name)
          This method returns a Manager for the given name.
static
<T extends AbstractBaseManager<? extends Persistent>>
T
getManager(String name, String defaultClassName)
          This methods returns either the Manager from the configuration file, or the default one provided by the generated code.
static Database getOrCreateDatabase(String name)
          Returns the database for the key databaseName.
static String getSchema(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 configuration.
static void init(String configFile)
          Initialization of Torque with a path to a properties file.
static boolean isInit()
          Determine whether Torque has already been initialized.
static void registerIDBroker(IDBroker idBroker)
          Registers an id broker.
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(String name, 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 String TORQUE_KEY
The prefix for all configuration keys used by Torque.

See Also:
Constant Field Values

DATABASE_KEY

public static final String DATABASE_KEY
The prefix for configuring the database adapters and the default database.

See Also:
Constant Field Values

DEFAULT_KEY

public static final String DEFAULT_KEY
The key used to configure the name of the default database.

See Also:
Constant Field Values

SCHEMA_KEY

public static final String SCHEMA_KEY
"schema" Key for the configuration

See Also:
Constant Field Values

DEFAULTS_KEY

public static final String DEFAULTS_KEY
"defaults" Key for the configuration

See Also:
Constant Field Values

DEFAULT_SCHEMA_KEY

public static final String DEFAULT_SCHEMA_KEY
default schema name for the configuration

See Also:
Constant Field Values

MANAGER_PREFIX

public static final String MANAGER_PREFIX
A prefix for Manager properties in the configuration.

See Also:
Constant Field Values

MANAGER_SUFFIX

public static final String MANAGER_SUFFIX
A Service property determining its implementing class name .

See Also:
Constant Field Values

CACHE_KEY

public static final String CACHE_KEY
Name of config property to determine whether caching is used.

See Also:
Constant Field Values

TRANSACTION_MANAGER_KEY

public static final String TRANSACTION_MANAGER_KEY
The prefix for configuring the transaction manger.

See Also:
Constant Field Values
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(String configFile)
                 throws TorqueException
Initialization of Torque with a path to 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 configuration.

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)
                             throws TorqueException
Sets the configuration for Torque and all dependencies.

Parameters:
conf - the Configuration
Throws:
TorqueException - if the configuration does not contain any keys starting with Torque.TORQUE_KEY.

getConfiguration

public static org.apache.commons.configuration.Configuration getConfiguration()
Get the configuration for this component.

Returns:
the Configuration

getManager

public static <T extends AbstractBaseManager<? extends Persistent>> T getManager(String name)
This method returns a Manager for the given name.

Parameters:
name - name of the manager.
Returns:
The requested Manager.

getManager

public static <T extends AbstractBaseManager<? extends Persistent>> T getManager(String name,
                                                                                 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 - if Torque is not initialized.

getDatabaseMap

public static DatabaseMap getDatabaseMap(String name)
                                  throws TorqueException
Returns the database map information for a given database.

Parameters:
name - The name of the database corresponding to the DatabaseMap to retrieve, or null for the default database.
Returns:
The named DatabaseMap, not null.
Throws:
TorqueException - if Torque is not initialized and name is null.

registerIDBroker

public static void registerIDBroker(IDBroker idBroker)
Registers an id broker. If Torque is already initialized, the id broker is started. If Torque is not initialized, the id broker will be started on initialization.

Parameters:
idBroker - the id broker to register, not null.
Throws:
NullPointerException - if idBroker is null.

getConnection

public static 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 Connection getConnection(String name)
                                throws TorqueException
This method returns a Connecton using the given database name.

Parameters:
name - The database name.
Returns:
a database connection to the database with the given name.
Throws:
TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getConnection

public static Connection getConnection(String name,
                                       String username,
                                       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 to the database with the given name.
Throws:
TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getDB

@Deprecated
public static Adapter getDB(String name)
                     throws TorqueException
Deprecated. use getAdapter(String) instead. This method will be removed in a future version of Torque.

Returns the database adapter for a specific database name.

Parameters:
name - the database name, or null for the default db.
Returns:
The corresponding database adapter.
Throws:
TorqueException - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

getAdapter

public static Adapter getAdapter(String name)
                          throws TorqueException
Returns the database adapter for a specific database name.

Parameters:
name - the database name, or null for the default db.
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 static 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(Connection con)
Closes a connection.

Parameters:
con - A Connection to close.

setSchema

public static void setSchema(String name,
                             String schema)
Sets the current schema for a database connection

Parameters:
name - The database name.
schema - The current schema name.
Throws:
NullPointerException - if databaseName is null.

getSchema

public static String getSchema(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(String name)
                            throws TorqueException
Returns the database for the given key.

Parameters:
name - the key to get the database for, or null for the default database.
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.

getOrCreateDatabase

public static Database getOrCreateDatabase(String name)
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:
name - the key to get the database for, not null.
Returns:
the database associated with specified key, or the newly created database, never null.
Throws:
IllegalArgumentException - if databaseName is null.

getDatabases

public static Map<String,Database> 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.


Copyright © 2000-2013 The Apache Software Foundation. All Rights Reserved.