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

org.springframework.jdbc.datasource

## Class UserCredentialsDataSourceAdapter

- java.lang.Object
- - org.springframework.jdbc.datasource.DelegatingDataSource
  - - org.springframework.jdbc.datasource.UserCredentialsDataSourceAdapter

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

      public class UserCredentialsDataSourceAdapter
      extends DelegatingDataSource

  An adapter for a target JDBC `DataSource`, applying the specified user credentials to every standard `getConnection()` call, implicitly invoking `getConnection(username, password)` on the target. All other methods simply delegate to the corresponding methods of the target DataSource.

  Can be used to proxy a target JNDI DataSource that does not have user credentials configured. Client code can work with this DataSource as usual, using the standard `getConnection()` call.

  In the following example, client code can simply transparently work with the preconfigured "myDataSource", implicitly accessing "myTargetDataSource" with the specified user credentials.

       <bean id="myTargetDataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
         <property name="jndiName" value="java:comp/env/jdbc/myds"/>
       </bean>

       <bean id="myDataSource" class="org.springframework.jdbc.datasource.UserCredentialsDataSourceAdapter">
         <property name="targetDataSource" ref="myTargetDataSource"/>
         <property name="username" value="myusername"/>
         <property name="password" value="mypassword"/>
       </bean>

  If the "username" is empty, this proxy will simply delegate to the standard `getConnection()` method of the target DataSource. This can be used to keep a UserCredentialsDataSourceAdapter bean definition just for the option of implicitly passing in user credentials if the particular target DataSource requires it.

  Since:
    1.0.2
  Author:
    Juergen Hoeller
  See Also:
    `getConnection()`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `UserCredentialsDataSourceAdapter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Connection` | `doGetConnection(String username, String password)` This implementation delegates to the `getConnection(username, password)` method of the target DataSource, passing in the specified user credentials.
    `Connection` | `getConnection()` Determine whether there are currently thread-bound credentials, using them if available, falling back to the statically specified username and password (i.e.
    `Connection` | `getConnection(String username, String password)` Simply delegates to `doGetConnection(String, String)`, keeping the given user credentials as-is.
    `void` | `removeCredentialsFromCurrentThread()` Remove any user credentials for this proxy from the current thread.
    `void` | `setCredentialsForCurrentThread(String username, String password)` Set user credententials for this proxy and the current thread.
    `void` | `setPassword(String password)` Set the default user's password that this adapter should use for retrieving Connections.
    `void` | `setUsername(String username)` Set the default username that this adapter should use for retrieving Connections.

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

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

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

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

- - ### Constructor Detail

    - #### UserCredentialsDataSourceAdapter

          public UserCredentialsDataSourceAdapter()

  - ### Method Detail

    - #### setUsername

          public void setUsername(String username)

      Set the default username that this adapter should use for retrieving Connections.

      Default is no specific user. Note that an explicitly specified username will always override any username/password specified at the DataSource level.

      See Also:
        `setPassword(java.lang.String)`, `setCredentialsForCurrentThread(String, String)`, `getConnection(String, String)`

    - #### setPassword

          public void setPassword(String password)

      Set the default user's password that this adapter should use for retrieving Connections.

      Default is no specific password. Note that an explicitly specified username will always override any username/password specified at the DataSource level.

      See Also:
        `setUsername(java.lang.String)`, `setCredentialsForCurrentThread(String, String)`, `getConnection(String, String)`

    - #### setCredentialsForCurrentThread

          public void setCredentialsForCurrentThread(String username,
                                            String password)

      Set user credententials for this proxy and the current thread. The given username and password will be applied to all subsequent `getConnection()` calls on this DataSource proxy.

      This will override any statically specified user credentials, that is, values of the "username" and "password" bean properties.

      Parameters:
        `username` - the username to apply
        `password` - the password to apply
      See Also:
        `removeCredentialsFromCurrentThread()`

    - #### removeCredentialsFromCurrentThread

          public void removeCredentialsFromCurrentThread()

      Remove any user credentials for this proxy from the current thread. Statically specified user credentials apply again afterwards.
      See Also:
        `setCredentialsForCurrentThread(java.lang.String, java.lang.String)`

    - #### getConnection

          public Connection getConnection()
                                   throws SQLException

      Determine whether there are currently thread-bound credentials, using them if available, falling back to the statically specified username and password (i.e. values of the bean properties) else.

      Delegates to `doGetConnection(String, String)` with the determined credentials as parameters.

      Specified by:
        `getConnection` in interface `DataSource`
      Overrides:
        `getConnection` in class `DelegatingDataSource`
      Throws:
        `SQLException`

    - #### getConnection

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

      Simply delegates to `doGetConnection(String, String)`, keeping the given user credentials as-is.
      Specified by:
        `getConnection` in interface `DataSource`
      Overrides:
        `getConnection` in class `DelegatingDataSource`
      Throws:
        `SQLException`

    - #### doGetConnection

          protected Connection doGetConnection(String username,
                                   String password)
                                        throws SQLException

      This implementation delegates to the `getConnection(username, password)` method of the target DataSource, passing in the specified user credentials. If the specified username is empty, it will simply delegate to the standard `getConnection()` method of the target DataSource.
      Parameters:
        `username` - the username to use
        `password` - the password to use
      Returns:
        the Connection
      Throws:
        `SQLException`
      See Also:
        `DataSource.getConnection(String, String)`, `DataSource.getConnection()`