AbstractRoutingDataSource (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jdbc.datasource.lookup

## Class AbstractRoutingDataSource

- java.lang.Object
- - org.springframework.jdbc.datasource.AbstractDataSource
  - - org.springframework.jdbc.datasource.lookup.AbstractRoutingDataSource

- All Implemented Interfaces:
    Wrapper, CommonDataSource, DataSource, InitializingBean
  Direct Known Subclasses:
    IsolationLevelDataSourceRouter

      public abstract class AbstractRoutingDataSource
      extends AbstractDataSource
      implements InitializingBean

  Abstract `DataSource` implementation that routes `getConnection()` calls to one of various target DataSources based on a lookup key. The latter is usually (but not necessarily) determined through some thread-bound transaction context.
  Since:
    2.0.1
  Author:
    Juergen Hoeller
  See Also:
    `setTargetDataSources(java.util.Map<java.lang.Object, java.lang.Object>)`, `setDefaultTargetDataSource(java.lang.Object)`, `determineCurrentLookupKey()`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.jdbc.datasource.AbstractDataSource

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractRoutingDataSource()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
    `protected abstract Object` | `determineCurrentLookupKey()` Determine the current lookup key.
    `protected DataSource` | `determineTargetDataSource()` Retrieve the current target DataSource.
    `Connection` | `getConnection()`
    `Connection` | `getConnection(String username, String password)`
    `boolean` | `isWrapperFor(Class<?> iface)`
    `protected DataSource` | `resolveSpecifiedDataSource(Object dataSource)` Resolve the specified data source object into a DataSource instance.
    `protected Object` | `resolveSpecifiedLookupKey(Object lookupKey)` Resolve the given lookup key object, as specified in the `targetDataSources` map, into the actual lookup key to be used for matching with the `current lookup key`.
    `void` | `setDataSourceLookup(DataSourceLookup dataSourceLookup)` Set the DataSourceLookup implementation to use for resolving data source name Strings in the `targetDataSources` map.
    `void` | `setDefaultTargetDataSource(Object defaultTargetDataSource)` Specify the default target DataSource, if any.
    `void` | `setLenientFallback(boolean lenientFallback)` Specify whether to apply a lenient fallback to the default DataSource if no specific DataSource could be found for the current lookup key.
    `void` | `setTargetDataSources(Map<Object,Object> targetDataSources)` Specify the map of target DataSources, with the lookup key as key.
    `<T> T` | `unwrap(Class<T> iface)`

    - ### Methods inherited from class org.springframework.jdbc.datasource.AbstractDataSource

      `getLoginTimeout, getLogWriter, getParentLogger, setLoginTimeout, setLogWriter`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### AbstractRoutingDataSource

          public AbstractRoutingDataSource()

  - ### Method Detail

    - #### setTargetDataSources

          public void setTargetDataSources(Map<Object,Object> targetDataSources)

      Specify the map of target DataSources, with the lookup key as key. The mapped value can either be a corresponding `DataSource` instance or a data source name String (to be resolved via a `DataSourceLookup`).

      The key can be of arbitrary type; this class implements the generic lookup process only. The concrete key representation will be handled by `resolveSpecifiedLookupKey(Object)` and `determineCurrentLookupKey()`.

    - #### setDefaultTargetDataSource

          public void setDefaultTargetDataSource(Object defaultTargetDataSource)

      Specify the default target DataSource, if any.

      The mapped value can either be a corresponding `DataSource` instance or a data source name String (to be resolved via a `DataSourceLookup`).

      This DataSource will be used as target if none of the keyed `targetDataSources` match the `determineCurrentLookupKey()` current lookup key.

    - #### setLenientFallback

          public void setLenientFallback(boolean lenientFallback)

      Specify whether to apply a lenient fallback to the default DataSource if no specific DataSource could be found for the current lookup key.

      Default is "true", accepting lookup keys without a corresponding entry in the target DataSource map - simply falling back to the default DataSource in that case.

      Switch this flag to "false" if you would prefer the fallback to only apply if the lookup key was `null`. Lookup keys without a DataSource entry will then lead to an IllegalStateException.

      See Also:
        `setTargetDataSources(java.util.Map<java.lang.Object, java.lang.Object>)`, `setDefaultTargetDataSource(java.lang.Object)`, `determineCurrentLookupKey()`

    - #### setDataSourceLookup

          public void setDataSourceLookup(DataSourceLookup dataSourceLookup)

      Set the DataSourceLookup implementation to use for resolving data source name Strings in the `targetDataSources` map.

      Default is a `JndiDataSourceLookup`, allowing the JNDI names of application server DataSources to be specified directly.

    - #### afterPropertiesSet

          public void afterPropertiesSet()

      Description copied from interface: `InitializingBean`
      Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

      This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`

    - #### resolveSpecifiedLookupKey

          protected Object resolveSpecifiedLookupKey(Object lookupKey)

      Resolve the given lookup key object, as specified in the `targetDataSources` map, into the actual lookup key to be used for matching with the `current lookup key`.

      The default implementation simply returns the given key as-is.

      Parameters:
        `lookupKey` - the lookup key object as specified by the user
      Returns:
        the lookup key as needed for matching

    - #### resolveSpecifiedDataSource

          protected DataSource resolveSpecifiedDataSource(Object dataSource)
                                                   throws IllegalArgumentException

      Resolve the specified data source object into a DataSource instance.

      The default implementation handles DataSource instances and data source names (to be resolved via a `DataSourceLookup`).

      Parameters:
        `dataSource` - the data source value object as specified in the `targetDataSources` map
      Returns:
        the resolved DataSource (never `null`)
      Throws:
        `IllegalArgumentException` - in case of an unsupported value type

    - #### getConnection

          public Connection getConnection()
                                   throws SQLException

      Specified by:
        `getConnection` in interface `DataSource`
      Throws:
        `SQLException`

    - #### getConnection

          public Connection getConnection(String username,
                                 String password)
                                   throws SQLException

      Specified by:
        `getConnection` in interface `DataSource`
      Throws:
        `SQLException`

    - #### unwrap

          public <T> T unwrap(Class<T> iface)
                   throws SQLException

      Specified by:
        `unwrap` in interface `Wrapper`
      Overrides:
        `unwrap` in class `AbstractDataSource`
      Throws:
        `SQLException`

    - #### isWrapperFor

          public boolean isWrapperFor(Class<?> iface)
                               throws SQLException

      Specified by:
        `isWrapperFor` in interface `Wrapper`
      Overrides:
        `isWrapperFor` in class `AbstractDataSource`
      Throws:
        `SQLException`

    - #### determineTargetDataSource

          protected DataSource determineTargetDataSource()

      Retrieve the current target DataSource. Determines the `current lookup key`, performs a lookup in the `targetDataSources` map, falls back to the specified `default target DataSource` if necessary.
      See Also:
        `determineCurrentLookupKey()`

    - #### determineCurrentLookupKey

          protected abstract Object determineCurrentLookupKey()

      Determine the current lookup key. This will typically be implemented to check a thread-bound transaction context.

      Allows for arbitrary keys. The returned key needs to match the stored lookup key type, as resolved by the `resolveSpecifiedLookupKey(java.lang.Object)` method.