Package 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`, `org.springframework.beans.factory.InitializingBean`

Direct Known Subclasses:
  `IsolationLevelDataSourceRouter`

public abstract class AbstractRoutingDataSource extends AbstractDataSource implements org.springframework.beans.factory.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
Description
`AbstractRoutingDataSource()`

## Method Summary

Modifier and Type
Method
Description
`void`
`afterPropertiesSet()`
Delegates to `initialize()`.
`ConnectionBuilder`
`createConnectionBuilder()`
`ShardingKeyBuilder`
`createShardingKeyBuilder()`
`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)`
`Map<Object,DataSource>`
`getResolvedDataSources()`
Return the resolved target DataSources that this router manages.
`DataSource`
`getResolvedDefaultDataSource()`
Return the resolved default target DataSource, if any.
`void`
`initialize()`
Initialize the internal state of this `AbstractRoutingDataSource` by resolving the configured target DataSources.
`boolean`
`isWrapperFor(Class<?> iface)`
`protected DataSource`
`resolveSpecifiedDataSource(Object dataSourceObject)`
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 Details

### AbstractRoutingDataSource

public AbstractRoutingDataSource()

## Method Details

### 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(@Nullable 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()
Delegates to `initialize()`.

Specified by:
  `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`

### initialize

public void initialize()
Initialize the internal state of this `AbstractRoutingDataSource` by resolving the configured target DataSources.

Throws:
  `IllegalArgumentException` - if the target DataSources have not been configured
Since:
  6.1
See Also:
  - `setTargetDataSources(Map)`
  - `setDefaultTargetDataSource(Object)`
  - `getResolvedDataSources()`
  - `getResolvedDefaultDataSource()`

### 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 dataSourceObject) 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:
  `dataSourceObject` - 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

### getResolvedDataSources

public Map<Object,DataSource> getResolvedDataSources()
Return the resolved target DataSources that this router manages.

Returns:
  an unmodifiable map of resolved lookup keys and DataSources
Throws:
  `IllegalStateException` - if the target DataSources are not resolved yet
Since:
  5.2.9
See Also:
  - `setTargetDataSources(java.util.Map<java.lang.Object, java.lang.Object>)`

### getResolvedDefaultDataSource

@Nullable public DataSource getResolvedDefaultDataSource()
Return the resolved default target DataSource, if any.

Returns:
  the default DataSource, or `null` if none or not resolved yet
Since:
  5.2.9
See Also:
  - `setDefaultTargetDataSource(java.lang.Object)`

### 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`

### createConnectionBuilder

public ConnectionBuilder createConnectionBuilder() throws SQLException

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

### createShardingKeyBuilder

public ShardingKeyBuilder createShardingKeyBuilder() throws SQLException

Specified by:
  `createShardingKeyBuilder` in interface `CommonDataSource`
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

@Nullable 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.