org.springframework.jdbc.datasource

## Class SingleConnectionDataSource

- java.lang.Object
- - org.springframework.jdbc.datasource.AbstractDataSource
  - - org.springframework.jdbc.datasource.AbstractDriverBasedDataSource
    - - org.springframework.jdbc.datasource.DriverManagerDataSource
      - - org.springframework.jdbc.datasource.SingleConnectionDataSource

All Implemented Interfaces:
  Wrapper, CommonDataSource, DataSource, DisposableBean, SmartDataSource

    public class SingleConnectionDataSource
    extends DriverManagerDataSource
    implements SmartDataSource, DisposableBean

Implementation of `SmartDataSource` that wraps a single JDBC Connection which is not closed after use. Obviously, this is not multi-threading capable.

Note that at shutdown, someone should close the underlying Connection via the `close()` method. Client code will never call close on the Connection handle if it is SmartDataSource-aware (e.g. uses `DataSourceUtils.releaseConnection`).

If client code will call `close()` in the assumption of a pooled Connection, like when using persistence tools, set "suppressClose" to "true". This will return a close-suppressing proxy instead of the physical Connection. Be aware that you will not be able to cast this to a native `OracleConnection` or the like anymore; you need to use a `NativeJdbcExtractor` then.

This is primarily intended for testing. For example, it enables easy testing outside an application server, for code that expects to work on a DataSource. In contrast to `DriverManagerDataSource`, it reuses the same Connection all the time, avoiding excessive creation of physical Connections.

Author:
  Rod Johnson, Juergen Hoeller
See Also:
  `getConnection()`, `Connection.close()`, `DataSourceUtils.releaseConnection(java.sql.Connection, javax.sql.DataSource)`, `NativeJdbcExtractor`

### Field Summary

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

`logger`

### Constructor Summary

Constructors
Constructor and Description
`SingleConnectionDataSource()` Constructor for bean-style configuration.
`SingleConnectionDataSource(Connection target, boolean suppressClose)` Create a new SingleConnectionDataSource with a given Connection.
`SingleConnectionDataSource(String url, boolean suppressClose)` Create a new SingleConnectionDataSource with the given standard DriverManager parameters.
`SingleConnectionDataSource(String url, String username, String password, boolean suppressClose)` Create a new SingleConnectionDataSource with the given standard DriverManager parameters.
`SingleConnectionDataSource(String driverClassName, String url, String username, String password, boolean suppressClose)` Deprecated. since Spring 2.5. Driver parameter usage is generally not recommended for a SingleConnectionDataSource. If you insist on using driver parameters directly, set up the Driver class manually before invoking this DataSource.

### Method Summary

Methods
`void` `destroy()` Close the underlying Connection.
`protected Boolean` `getAutoCommitValue()` Return whether the returned Connection's "autoCommit" setting should be overridden.
`protected Connection` `getCloseSuppressingConnectionProxy(Connection target)` Wrap the given Connection with a proxy that delegates every method call to it but suppresses close calls.
`Connection` `getConnection()` This implementation delegates to `getConnectionFromDriver`, using the default username and password of this DataSource.
`Connection` `getConnection(String username, String password)` Specifying a custom username and password doesn't make sense with a single Connection.
`void` `initConnection()` Initialize the underlying Connection via the DriverManager.
`protected boolean` `isSuppressClose()` Return whether the returned Connection will be a close-suppressing proxy or the physical Connection.
`protected void` `prepareConnection(Connection con)` Prepare the given Connection before it is exposed.
`void` `resetConnection()` Reset the underlying shared Connection, to be reinitialized on next access.
`void` `setAutoCommit(boolean autoCommit)` Set whether the returned Connection's "autoCommit" setting should be overridden.
`void` `setSuppressClose(boolean suppressClose)` Set whether the returned Connection should be a close-suppressing proxy or the physical Connection.
`boolean` `shouldClose(Connection con)` This is a single Connection: Do not close it when returning to the "pool".

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

`getConnectionFromDriver, getConnectionFromDriverManager, setDriverClassName`

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

`getConnectionFromDriver, getConnectionProperties, getPassword, getUrl, getUsername, setConnectionProperties, setPassword, setUrl, setUsername`

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

`getLoginTimeout, getLogWriter, getParentLogger, isWrapperFor, setLoginTimeout, setLogWriter, unwrap`

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

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

### Methods inherited from interface javax.sql.CommonDataSource

`getLoginTimeout, getLogWriter, getParentLogger, setLoginTimeout, setLogWriter`

### Methods inherited from interface java.sql.Wrapper

`isWrapperFor, unwrap`

### Constructor Detail

#### SingleConnectionDataSource

    public SingleConnectionDataSource()

Constructor for bean-style configuration.

#### SingleConnectionDataSource

    @Deprecated
    public SingleConnectionDataSource(String driverClassName,
                                         String url,
                                         String username,
                                         String password,
                                         boolean suppressClose)

Deprecated. since Spring 2.5. Driver parameter usage is generally not recommended for a SingleConnectionDataSource. If you insist on using driver parameters directly, set up the Driver class manually before invoking this DataSource.
Create a new SingleConnectionDataSource with the given standard DriverManager parameters.

Parameters:
  `driverClassName` - the JDBC driver class name
  `url` - the JDBC URL to use for accessing the DriverManager
  `username` - the JDBC username to use for accessing the DriverManager
  `password` - the JDBC password to use for accessing the DriverManager
  `suppressClose` - if the returned Connection should be a close-suppressing proxy or the physical Connection
See Also:
  `DriverManager.getConnection(String, String, String)`

#### SingleConnectionDataSource

    public SingleConnectionDataSource(String url,
                              String username,
                              String password,
                              boolean suppressClose)

Create a new SingleConnectionDataSource with the given standard DriverManager parameters.

Parameters:
  `url` - the JDBC URL to use for accessing the DriverManager
  `username` - the JDBC username to use for accessing the DriverManager
  `password` - the JDBC password to use for accessing the DriverManager
  `suppressClose` - if the returned Connection should be a close-suppressing proxy or the physical Connection
See Also:
  `DriverManager.getConnection(String, String, String)`

#### SingleConnectionDataSource

    public SingleConnectionDataSource(String url,
                              boolean suppressClose)

Create a new SingleConnectionDataSource with the given standard DriverManager parameters.

Parameters:
  `url` - the JDBC URL to use for accessing the DriverManager
  `suppressClose` - if the returned Connection should be a close-suppressing proxy or the physical Connection
See Also:
  `DriverManager.getConnection(String, String, String)`

#### SingleConnectionDataSource

    public SingleConnectionDataSource(Connection target,
                              boolean suppressClose)

Create a new SingleConnectionDataSource with a given Connection.

Parameters:
  `target` - underlying target Connection
  `suppressClose` - if the Connection should be wrapped with a Connection that suppresses `close()` calls (to allow for normal `close()` usage in applications that expect a pooled Connection but do not know our SmartDataSource interface)

### Method Detail

#### setSuppressClose

    public void setSuppressClose(boolean suppressClose)

Set whether the returned Connection should be a close-suppressing proxy or the physical Connection.

#### isSuppressClose

    protected boolean isSuppressClose()

Return whether the returned Connection will be a close-suppressing proxy or the physical Connection.

#### setAutoCommit

    public void setAutoCommit(boolean autoCommit)

Set whether the returned Connection's "autoCommit" setting should be overridden.

#### getAutoCommitValue

    protected Boolean getAutoCommitValue()

Return whether the returned Connection's "autoCommit" setting should be overridden.

Returns:
  the "autoCommit" value, or `null` if none to be applied

#### getConnection

    public Connection getConnection()
                             throws SQLException

Description copied from class: `AbstractDriverBasedDataSource`
This implementation delegates to `getConnectionFromDriver`, using the default username and password of this DataSource.

Specified by:
  `getConnection` in interface `DataSource`
Overrides:
  `getConnection` in class `AbstractDriverBasedDataSource`
Throws:
  `SQLException`
See Also:
  `AbstractDriverBasedDataSource.getConnectionFromDriver(String, String)`, `AbstractDriverBasedDataSource.setUsername(java.lang.String)`, `AbstractDriverBasedDataSource.setPassword(java.lang.String)`

#### getConnection

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

Specifying a custom username and password doesn't make sense with a single Connection. Returns the single Connection if given the same username and password; throws a SQLException else.

Specified by:
  `getConnection` in interface `DataSource`
Overrides:
  `getConnection` in class `AbstractDriverBasedDataSource`
Throws:
  `SQLException`
See Also:
  `AbstractDriverBasedDataSource.getConnectionFromDriver(String, String)`

#### shouldClose

    public boolean shouldClose(Connection con)

This is a single Connection: Do not close it when returning to the "pool".

Specified by:
  `shouldClose` in interface `SmartDataSource`
Parameters:
  `con` - the Connection to check
Returns:
  whether the given Connection should be closed
See Also:
  `Connection.close()`

#### destroy

    public void destroy()

Close the underlying Connection. The provider of this DataSource needs to care for proper shutdown.

As this bean implements DisposableBean, a bean factory will automatically invoke this on destruction of its cached singletons.

Specified by:
  `destroy` in interface `DisposableBean`

#### initConnection

    public void initConnection()
                        throws SQLException

Initialize the underlying Connection via the DriverManager.

Throws:
  `SQLException`

#### resetConnection

    public void resetConnection()

Reset the underlying shared Connection, to be reinitialized on next access.

#### prepareConnection

    protected void prepareConnection(Connection con)
                              throws SQLException

Prepare the given Connection before it is exposed.

The default implementation applies the auto-commit flag, if necessary. Can be overridden in subclasses.

Parameters:
  `con` - the Connection to prepare
Throws:
  `SQLException`
See Also:
  `setAutoCommit(boolean)`

#### getCloseSuppressingConnectionProxy

    protected Connection getCloseSuppressingConnectionProxy(Connection target)

Wrap the given Connection with a proxy that delegates every method call to it but suppresses close calls.

Parameters:
  `target` - the original Connection to wrap
Returns:
  the wrapped Connection