Package org.apache.torque

# Klasse TorqueInstance

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

Bekannte direkte Unterklassen:
  `TorqueComponent`

public class TorqueInstance extends 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 1917245 2024-04-21 14:06:23Z tv $
Autor:
  Daniel Rall, Magnï¿½s ï¿½ï¿½r Torfason, Jason van Zyl, Rafal Krzewski, Martin Poeschl, Henning P. Schmiedehausen, Kurt Schrader, Thomas Vandahl

- ## Konstruktorübersicht

  Konstruktoren
  Konstruktor
  Beschreibung
  `TorqueInstance()`
  Creates a new instance with default configuration.

- ## Methodenübersicht

  Modifizierer und Typ
  Methode
  Beschreibung
  `void`
  `closeConnection(Connection con)`
  Closes a connection.
  `Adapter`
  `getAdapter(String name)`
  Returns the database adapter for a specific database.
  `org.apache.commons.configuration2.Configuration`
  `getConfiguration()`
  Get the configuration for this component.
  `Connection`
  `getConnection()`
  This method returns a Connection from the default pool.
  `Connection`
  `getConnection(String name)`
  Returns a database connection to the database with the key `name`.
  `Connection`
  `getConnection(String name, String username, String password)`
  This method returns a Connection using the given parameters.
  `Database`
  `getDatabase(String databaseName)`
  Returns the database for the key `databaseName`.
  `DatabaseMap`
  `getDatabaseMap()`
  Returns the database map information for the default db.
  `DatabaseMap`
  `getDatabaseMap(String name)`
  Returns the database map information for the given database name.
  `Map<String,Database>`
  `getDatabases()`
  Returns a Map containing all Databases registered to Torque.
  `DataSourceFactory`
  `getDataSourceFactory(String name)`
  Returns the DataSourceFactory for the database with the name `name`.
  `String`
  `getDefaultDB()`
  Returns the name of the default database.
  `<T extends AbstractBaseManager<? extends Persistent>>
  T`
  `getManager(String name)`
  This method returns a Manager for the given name.
  `<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.
  `Database`
  `getOrCreateDatabase(String databaseName)`
  Returns the database for the key `databaseName`.
  `<T, P extends BasePeerImpl<T>>
  P`
  `getPeerInstance(Class<T> omClass)`
  This method returns a PeerImpl for the given class.
  `String`
  `getSchema(String name)`
  This method returns the current schema for a database connection
  `void`
  `init(String configFile)`
  Initialization of Torque with a path to a properties or xml file.
  `void`
  `init(org.apache.commons.configuration2.Configuration conf)`
  Initialization of Torque with a Configuration object.
  `protected void`
  `initManagerMappings(org.apache.commons.configuration2.Configuration conf)`
  Creates a mapping between classes and their manager classes.
  `boolean`
  `isInit()`
  Determine whether Torque has already been initialized.
  `void`
  `registerIDBroker(IDBroker idBroker)`
  Registers an id broker.
  `<T> void`
  `registerPeerInstance(Class<T> omClass, BasePeerImpl<T> peerInstance)`
  This method registers a PeerImpl for a given class.
  `void`
  `setConfiguration(org.apache.commons.configuration2.Configuration conf)`
  Sets the configuration for Torque and all dependencies.
  `void`
  `setSchema(String name, String schema)`
  Sets the current schema for a database connection
  `void`
  `shutdown()`
  Shuts down Torque.

  ### Von Klasse geerbte Methoden java.lang.Object

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

- ## Konstruktordetails

  - ### TorqueInstance

    public TorqueInstance()
    Creates a new instance with default configuration.
    Siehe auch:
      - `resetConfiguration()`

- ## Methodendetails

  - ### init

    public void init(String configFile) throws TorqueException
    Initialization of Torque with a path to a properties or xml file.
    Parameter:
      `configFile` - The absolute path to the configuration file.
    Löst aus:
      `TorqueException` - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

  - ### init

    public void init(org.apache.commons.configuration2.Configuration conf) throws TorqueException
    Initialization of Torque with a Configuration object.
    Parameter:
      `conf` - The Torque configuration.
    Löst aus:
      `TorqueException` - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

  - ### initManagerMappings

    protected void initManagerMappings(org.apache.commons.configuration2.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.
    Parameter:
      `conf` - the Configuration representing the properties file
    Löst aus:
      `TorqueException` - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

  - ### isInit

    public boolean isInit()
    Determine whether Torque has already been initialized.
    Gibt zurück:
      true if Torque is already initialized

  - ### setConfiguration

    public void setConfiguration(org.apache.commons.configuration2.Configuration conf) throws TorqueException
    Sets the configuration for Torque and all dependencies. The prefix `TORQUE_KEY` will be removed from the configuration keys for the provided configuration.
    Parameter:
      `conf` - the Configuration.
    Löst aus:
      `TorqueException` - if the configuration does not contain any keys starting with `Torque.TORQUE_KEY`.

  - ### getConfiguration

    public org.apache.commons.configuration2.Configuration getConfiguration()
    Get the configuration for this component.
    Gibt zurück:
      the Configuration

  - ### getManager

    public <T extends AbstractBaseManager<? extends Persistent>> T getManager(String name)
    This method returns a Manager for the given name.
    Typparameter:
      `T` - the type of the manager class
    Parameter:
      `name` - name of the manager
    Gibt zurück:
      a Manager

  - ### getManager

    public <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.
    Typparameter:
      `T` - the type of the manager class
    Parameter:
      `name` - name of the manager.
      `defaultClassName` - the class to use if name has not been configured.
    Gibt zurück:
      a Manager

  - ### registerPeerInstance

    public <T> void registerPeerInstance(Class<T> omClass, BasePeerImpl<T> peerInstance)
    This method registers a PeerImpl for a given class.
    Typparameter:
      `T` - the type of the OM class and the type of the peerInstance class, which is of type BasePeerImpl.
    Parameter:
      `omClass` - the class of the associated OM object
      `peerInstance` - PeerImpl instance

  - ### getPeerInstance

    public <T, P extends BasePeerImpl<T>> P getPeerInstance(Class<T> omClass)
    This method returns a PeerImpl for the given class.
    Typparameter:
      `T` - the type of the OM class
      `P` - the type of the peerInstance class
    Parameter:
      `omClass` - the class of the associated OM object
    Gibt zurück:
      a PeerImpl instance

  - ### shutdown

    public void shutdown() throws TorqueException
    Shuts down Torque. This method halts the IDBroker's daemon thread in all of the DatabaseMap's. It also closes all SharedPoolDataSourceFactories and PerUserPoolDataSourceFactories initialized by Torque.
    Löst aus:
      `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 database map information for the default db.
    Gibt zurück:
      the requested DatabaseMap, not null.
    Löst aus:
      `TorqueException` - if Torque is not initialized.

  - ### getDatabaseMap

    public DatabaseMap getDatabaseMap(String name) throws TorqueException
    Returns the database map information for the given database name.
    Parameter:
      `name` - The name of the database corresponding to the `DatabaseMap` to retrieve, or null for the default database.
    Gibt zurück:
      The named `DatabaseMap`, not null.
    Löst aus:
      `TorqueException` - if Torque is not initialized and name is null.

  - ### registerIDBroker

    public 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.
    Parameter:
      `idBroker` - the id broker to register, not null.
    Löst aus:
      `NullPointerException` - if idBroker is null.

  - ### getConnection

    public Connection getConnection() throws TorqueException
    This method returns a Connection from the default pool.
    Gibt zurück:
      The requested connection, never null.
    Löst aus:
      `TorqueException` - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

  - ### getConnection

    public Connection getConnection(String name) throws TorqueException
    Returns a database connection to the database with the key `name`.
    Parameter:
      `name` - The database name.
    Gibt zurück:
      a database connection to the named database, never null.
    Löst aus:
      `TorqueException` - if Torque is not initialized, 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(String name) throws TorqueException
    Returns the DataSourceFactory for the database with the name `name`.
    Parameter:
      `name` - The name of the database to get the DSF for.
    Gibt zurück:
      A DataSourceFactory object, never null.
    Löst aus:
      `TorqueException` - if Torque is not initialized, or no DatasourceFactory is configured for the given name.

  - ### getConnection

    public Connection getConnection(String name, String username, 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!
    Parameter:
      `name` - The database name.
      `username` - The name of the database user.
      `password` - The password of the database user.
    Gibt zurück:
      A Connection to the named database.
    Löst aus:
      `TorqueException` - Any exceptions caught during processing will be rethrown wrapped into a TorqueException.

  - ### getAdapter

    public Adapter getAdapter(String name) throws TorqueException
    Returns the database adapter for a specific database.
    Parameter:
      `name` - the database name, or null for the default db.
    Gibt zurück:
      The corresponding database adapter, or null if no database adapter is defined for the given database.
    Löst aus:
      `TorqueException` - if Torque is not initialized.

  - ### getDefaultDB

    public String getDefaultDB()
    Returns the name of the default database.
    Gibt zurück:
      name of the default DB, or null if Torque is not initialized yet

  - ### closeConnection

    public void closeConnection(Connection con)
    Closes a connection.
    Parameter:
      `con` - A Connection to close.

  - ### setSchema

    public void setSchema(String name, String schema)
    Sets the current schema for a database connection
    Parameter:
      `name` - The database name, not null.
      `schema` - The current schema name.
    Löst aus:
      `NullPointerException` - if databaseName is null.

  - ### getSchema

    public String getSchema(String name) throws TorqueException
    This method returns the current schema for a database connection
    Parameter:
      `name` - The database name.
    Gibt zurück:
      The current schema name. Null means, no schema has been set or no database with the given name exists.
    Löst aus:
      `TorqueException` - if Torque is not yet initialized.

  - ### getDatabase

    public Database getDatabase(String databaseName) throws TorqueException
    Returns the database for the key `databaseName`.
    Parameter:
      `databaseName` - the key to get the database for, or null for the default database.
    Gibt zurück:
      the database for the specified key, or null if the database does not exist.
    Löst aus:
      `TorqueException` - if Torque is not yet initialized.

  - ### getDatabases

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

    Gibt zurück:
      a Map containing all Databases known to Torque, never null.
    Löst aus:
      `TorqueException` - if Torque is not yet initialized.

  - ### getOrCreateDatabase

    public Database getOrCreateDatabase(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.
    Parameter:
      `databaseName` - the key to get the database for, not null.
    Gibt zurück:
      the database associated with specified key, or the newly created database, never null.
    Löst aus:
      `NullPointerException` - if databaseName is null.