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

org.springframework.jdbc.support.nativejdbc

## Class NativeJdbcExtractorAdapter

- java.lang.Object
- - org.springframework.jdbc.support.nativejdbc.NativeJdbcExtractorAdapter

- All Implemented Interfaces:
    NativeJdbcExtractor
  Direct Known Subclasses:
    C3P0NativeJdbcExtractor, CommonsDbcpNativeJdbcExtractor, JBossNativeJdbcExtractor, Jdbc4NativeJdbcExtractor, SimpleNativeJdbcExtractor, WebLogicNativeJdbcExtractor, WebSphereNativeJdbcExtractor

      public abstract class NativeJdbcExtractorAdapter
      extends Object
      implements NativeJdbcExtractor

  Abstract adapter class for the `NativeJdbcExtractor` interface, for simplified implementation of basic extractors. Basically returns the passed-in JDBC objects on all methods.

  `getNativeConnection` checks for a ConnectionProxy chain, for example from a TransactionAwareDataSourceProxy, before delegating to `doGetNativeConnection` for actual unwrapping. You can override either of the two for a specific connection pool, but the latter is recommended to participate in ConnectionProxy unwrapping.

  `getNativeConnection` also applies a fallback if the first native extraction process failed, that is, returned the same Connection as passed in. It assumes that some additional proxying is going in this case: Hence, it retrieves the underlying native Connection from the DatabaseMetaData via `conHandle.getMetaData().getConnection()` and retries the native extraction process based on that Connection handle. This works, for example, for the Connection proxies exposed by Hibernate 3.1's `Session.connection()`.

  The `getNativeConnectionFromStatement` method is implemented to simply delegate to `getNativeConnection` with the Statement's Connection. This is what most extractor implementations will stick to, unless there's a more efficient version for a specific pool.

  Since:
    1.1
  Author:
    Juergen Hoeller
  See Also:
    `getNativeConnection(java.sql.Connection)`, `getNativeConnectionFromStatement(java.sql.Statement)`, `ConnectionProxy`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `NativeJdbcExtractorAdapter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Connection` | `doGetNativeConnection(Connection con)` Not able to unwrap: return passed-in Connection.
    `CallableStatement` | `getNativeCallableStatement(CallableStatement cs)` Not able to unwrap: return passed-in CallableStatement.
    `Connection` | `getNativeConnection(Connection con)` Check for a ConnectionProxy chain, then delegate to doGetNativeConnection.
    `Connection` | `getNativeConnectionFromStatement(Statement stmt)` Retrieve the Connection via the Statement's Connection.
    `PreparedStatement` | `getNativePreparedStatement(PreparedStatement ps)` Not able to unwrap: return passed-in PreparedStatement.
    `ResultSet` | `getNativeResultSet(ResultSet rs)` Not able to unwrap: return passed-in ResultSet.
    `Statement` | `getNativeStatement(Statement stmt)` Not able to unwrap: return passed-in Statement.
    `boolean` | `isNativeConnectionNecessaryForNativeCallableStatements()` Return `false` by default.
    `boolean` | `isNativeConnectionNecessaryForNativePreparedStatements()` Return `false` by default.
    `boolean` | `isNativeConnectionNecessaryForNativeStatements()` Return `false` by default.

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

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

- - ### Constructor Detail

    - #### NativeJdbcExtractorAdapter

          public NativeJdbcExtractorAdapter()

  - ### Method Detail

    - #### isNativeConnectionNecessaryForNativeStatements

          public boolean isNativeConnectionNecessaryForNativeStatements()

      Return `false` by default.
      Specified by:
        `isNativeConnectionNecessaryForNativeStatements` in interface `NativeJdbcExtractor`

    - #### isNativeConnectionNecessaryForNativePreparedStatements

          public boolean isNativeConnectionNecessaryForNativePreparedStatements()

      Return `false` by default.
      Specified by:
        `isNativeConnectionNecessaryForNativePreparedStatements` in interface `NativeJdbcExtractor`

    - #### isNativeConnectionNecessaryForNativeCallableStatements

          public boolean isNativeConnectionNecessaryForNativeCallableStatements()

      Return `false` by default.
      Specified by:
        `isNativeConnectionNecessaryForNativeCallableStatements` in interface `NativeJdbcExtractor`

    - #### getNativeConnection

          public Connection getNativeConnection(Connection con)
                                         throws SQLException

      Check for a ConnectionProxy chain, then delegate to doGetNativeConnection.

      ConnectionProxy is used by Spring's TransactionAwareDataSourceProxy and LazyConnectionDataSourceProxy. The target connection behind it is typically one from a local connection pool, to be unwrapped by the doGetNativeConnection implementation of a concrete subclass.

      Specified by:
        `getNativeConnection` in interface `NativeJdbcExtractor`
      Parameters:
        `con` - the Connection handle, potentially wrapped by a connection pool
      Returns:
        the underlying native JDBC Connection, if possible; else, the original Connection
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `doGetNativeConnection(java.sql.Connection)`, `ConnectionProxy`, `DataSourceUtils.getTargetConnection(java.sql.Connection)`, `TransactionAwareDataSourceProxy`, `LazyConnectionDataSourceProxy`

    - #### doGetNativeConnection

          protected Connection doGetNativeConnection(Connection con)
                                              throws SQLException

      Not able to unwrap: return passed-in Connection.
      Throws:
        `SQLException`

    - #### getNativeConnectionFromStatement

          public Connection getNativeConnectionFromStatement(Statement stmt)
                                                      throws SQLException

      Retrieve the Connection via the Statement's Connection.
      Specified by:
        `getNativeConnectionFromStatement` in interface `NativeJdbcExtractor`
      Parameters:
        `stmt` - the Statement handle, potentially wrapped by a connection pool
      Returns:
        the underlying native JDBC Connection, if possible; else, the original Connection
      Throws:
        `SQLException` - if thrown by JDBC methods
      See Also:
        `getNativeConnection(java.sql.Connection)`, `Statement.getConnection()`

    - #### getNativeStatement

          public Statement getNativeStatement(Statement stmt)
                                       throws SQLException

      Not able to unwrap: return passed-in Statement.
      Specified by:
        `getNativeStatement` in interface `NativeJdbcExtractor`
      Parameters:
        `stmt` - the Statement handle, potentially wrapped by a connection pool
      Returns:
        the underlying native JDBC Statement, if possible; else, the original Statement
      Throws:
        `SQLException` - if thrown by JDBC methods

    - #### getNativePreparedStatement

          public PreparedStatement getNativePreparedStatement(PreparedStatement ps)
                                                       throws SQLException

      Not able to unwrap: return passed-in PreparedStatement.
      Specified by:
        `getNativePreparedStatement` in interface `NativeJdbcExtractor`
      Parameters:
        `ps` - the PreparedStatement handle, potentially wrapped by a connection pool
      Returns:
        the underlying native JDBC PreparedStatement, if possible; else, the original PreparedStatement
      Throws:
        `SQLException` - if thrown by JDBC methods

    - #### getNativeCallableStatement

          public CallableStatement getNativeCallableStatement(CallableStatement cs)
                                                       throws SQLException

      Not able to unwrap: return passed-in CallableStatement.
      Specified by:
        `getNativeCallableStatement` in interface `NativeJdbcExtractor`
      Parameters:
        `cs` - the CallableStatement handle, potentially wrapped by a connection pool
      Returns:
        the underlying native JDBC CallableStatement, if possible; else, the original CallableStatement
      Throws:
        `SQLException` - if thrown by JDBC methods

    - #### getNativeResultSet

          public ResultSet getNativeResultSet(ResultSet rs)
                                       throws SQLException

      Not able to unwrap: return passed-in ResultSet.
      Specified by:
        `getNativeResultSet` in interface `NativeJdbcExtractor`
      Parameters:
        `rs` - the ResultSet handle, potentially wrapped by a connection pool
      Returns:
        the underlying native JDBC ResultSet, if possible; else, the original ResultSet
      Throws:
        `SQLException` - if thrown by JDBC methods