Package org.springframework.jdbc.datasource

# Class ShardingKeyDataSourceAdapter

java.lang.Object
org.springframework.jdbc.datasource.DelegatingDataSource
org.springframework.jdbc.datasource.ShardingKeyDataSourceAdapter

All Implemented Interfaces:
  `Wrapper`, `CommonDataSource`, `DataSource`, `org.springframework.beans.factory.InitializingBean`

public class ShardingKeyDataSourceAdapter extends DelegatingDataSource
An adapter for a target `DataSource`, designed to apply sharding keys, if specified, to every standard `#getConnection` call, returning a direct connection to the shard corresponding to the specified sharding key value. All other methods simply delegate to the corresponding methods of the target `DataSource`.

The target `DataSource` must implement the `createConnectionBuilder()` method; otherwise, a `SQLFeatureNotSupportedException` will be thrown when attempting to acquire shard connections.

This adapter needs to be configured with a `ShardingKeyProvider` callback which is used to get the current sharding keys for every `#getConnection` call, for example:

     ShardingKeyDataSourceAdapter dataSourceAdapter = new ShardingKeyDataSourceAdapter(dataSource);
     dataSourceAdapter.setShardingKeyProvider(() -> dataSource.createShardingKeyBuilder()
         .subkey(SecurityContextHolder.getContext().getAuthentication().getName(), JDBCType.VARCHAR).build());

Since:
  6.1.2
Author:
  Mohamed Lahyane (Anir), Juergen Hoeller
See Also:
  - `getConnection()`
  - `createConnectionBuilder()`
  - `UserCredentialsDataSourceAdapter`

## Constructor Summary

Constructors
Constructor
Description
`ShardingKeyDataSourceAdapter(DataSource dataSource)`
Create a new instance of `ShardingKeyDataSourceAdapter`, wrapping the given `DataSource`.
`ShardingKeyDataSourceAdapter(DataSource dataSource, ShardingKeyProvider shardingKeyProvider)`
Create a new instance of `ShardingKeyDataSourceAdapter`, wrapping the given `DataSource`.

## Method Summary

Modifier and Type
Method
Description
`ConnectionBuilder`
`createConnectionBuilder()`
Create a new instance of `ConnectionBuilder` using the target `DataSource`'s `createConnectionBuilder()` method and set the appropriate sharding keys from the configured `ShardingKeyProvider`.
`Connection`
`getConnection()`
Obtain a connection to the database shard using the provided sharding key and super sharding key (if available).
`Connection`
`getConnection(String username, String password)`
Obtain a connection to the database shard using the provided username and password, considering the sharding keys (if available) and the given credentials.
`void`
`setShardingKeyProvider(ShardingKeyProvider shardingKeyProvider)`
Set the `ShardingKeyProvider` for this adapter.

### Methods inherited from class org.springframework.jdbc.datasource.DelegatingDataSource

`afterPropertiesSet, createShardingKeyBuilder, getLoginTimeout, getLogWriter, getParentLogger, getTargetDataSource, isWrapperFor, obtainTargetDataSource, setLoginTimeout, setLogWriter, setTargetDataSource, unwrap`

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

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

## Constructor Details

### ShardingKeyDataSourceAdapter

public ShardingKeyDataSourceAdapter(DataSource dataSource)
Create a new instance of `ShardingKeyDataSourceAdapter`, wrapping the given `DataSource`.

Parameters:
  `dataSource` - the target `DataSource` to be wrapped

### ShardingKeyDataSourceAdapter

public ShardingKeyDataSourceAdapter(DataSource dataSource, ShardingKeyProvider shardingKeyProvider)
Create a new instance of `ShardingKeyDataSourceAdapter`, wrapping the given `DataSource`.

Parameters:
  `dataSource` - the target `DataSource` to be wrapped
  `shardingKeyProvider` - the `ShardingKeyProvider` used to get the sharding keys

## Method Details

### setShardingKeyProvider

public void setShardingKeyProvider(ShardingKeyProvider shardingKeyProvider)
Set the `ShardingKeyProvider` for this adapter.

### getConnection

public Connection getConnection() throws SQLException
Obtain a connection to the database shard using the provided sharding key and super sharding key (if available).

The sharding key is obtained from the configured `ShardingKeyProvider`.

Specified by:
  `getConnection` in interface `DataSource`
Overrides:
  `getConnection` in class `DelegatingDataSource`
Returns:
  a `Connection` object representing a direct shard connection
Throws:
  `SQLException` - if an error occurs while creating the connection
See Also:
  - `createConnectionBuilder()`

### getConnection

public Connection getConnection(String username, String password) throws SQLException
Obtain a connection to the database shard using the provided username and password, considering the sharding keys (if available) and the given credentials.

The sharding key is obtained from the configured `ShardingKeyProvider`.

Specified by:
  `getConnection` in interface `DataSource`
Overrides:
  `getConnection` in class `DelegatingDataSource`
Parameters:
  `username` - the database user on whose behalf the connection is being made
  `password` - the user's password
Returns:
  a `Connection` object representing a direct shard connection
Throws:
  `SQLException` - if an error occurs while creating the connection

### createConnectionBuilder

public ConnectionBuilder createConnectionBuilder() throws SQLException
Create a new instance of `ConnectionBuilder` using the target `DataSource`'s `createConnectionBuilder()` method and set the appropriate sharding keys from the configured `ShardingKeyProvider`.

Specified by:
  `createConnectionBuilder` in interface `DataSource`
Overrides:
  `createConnectionBuilder` in class `DelegatingDataSource`
Returns:
  a ConnectionBuilder object representing a builder for direct shard connections
Throws:
  `SQLException` - if an error occurs while creating the ConnectionBuilder