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

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
    Modifier and Type | Method and Description
    --- | ---
    `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