/**
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.dbcp.managed;
import org.apache.commons.dbcp.DelegatingConnection;
import org.apache.commons.pool.ObjectPool;
import java.sql.Connection;
import java.sql.SQLException;
/**
* ManagedConnection is responsible for managing a database connection in a transactional environment
* (typically called "Container Managed"). A managed connection operates like any other connection
* when no global transaction (a.k.a. XA transaction or JTA Transaction) is in progress. When a
* global transaction is active a single physical connection to the database is used by all
* ManagedConnections accessed in the scope of the transaction. Connection sharing means that all
* data access during a transaction has a consistent view of the database. When the global transaction
* is committed or rolled back the enlisted connections are committed or rolled back. Typically upon
* transaction completion, a connection returns to the auto commit setting in effect before being
* enlisted in the transaction, but some vendors do not properly implement this.
*
* When enlisted in a transaction the setAutoCommit(), commit(), rollback(), and setReadOnly() methods
* throw a SQLException. This is necessary to assure that the transaction completes as a single unit.
*
* @author Dain Sundstrom
* @version $Revision$
*/
public class ManagedConnection extends DelegatingConnection {
private final ObjectPool pool;
private final TransactionRegistry transactionRegistry;
private final boolean accessToUnderlyingConnectionAllowed;
private TransactionContext transactionContext;
private boolean isSharedConnection;
public ManagedConnection(ObjectPool pool, TransactionRegistry transactionRegistry, boolean accessToUnderlyingConnectionAllowed) throws SQLException {
super(null);
this.pool = pool;
this.transactionRegistry = transactionRegistry;
this.accessToUnderlyingConnectionAllowed = accessToUnderlyingConnectionAllowed;
updateTransactionStatus();
}
protected void checkOpen() throws SQLException {
super.checkOpen();
updateTransactionStatus();
}
private void updateTransactionStatus() throws SQLException {
// if there is a is an active transaction context, assure the transaction context hasn't changed
if (transactionContext != null) {
if (transactionContext.isActive()) {
if (transactionContext != transactionRegistry.getActiveTransactionContext()) {
throw new SQLException("Connection can not be used while enlisted in another transaction");
}
return;
} else {
// transaction should have been cleared up by TransactionContextListener, but in
// rare cases another lister could have registered which uses the connection before
// our listener is called. In that rare case, trigger the transaction complete call now
transactionComplete();
}
}
// the existing transaction context ended (or we didn't have one), get the active transaction context
transactionContext = transactionRegistry.getActiveTransactionContext();
// if there is an active transaction context and it already has a shared connection, use it
if (transactionContext != null && transactionContext.getSharedConnection() != null) {
// A connection for the connection factory has already been enrolled
// in the transaction, replace our delegate with the enrolled connection
// return current connection to the pool
Connection connection = getDelegateInternal();
setDelegate(null);
if (connection != null) {
try {
pool.returnObject(connection);
} catch (Exception ignored) {
// whatever... try to invalidate the connection
try {
pool.invalidateObject(connection);
} catch (Exception ignore) {
// no big deal
}
}
}
// add a listener to the transaction context
transactionContext.addTransactionContextListener(new CompletionListener());
// set our delegate to the shared connection
setDelegate(transactionContext.getSharedConnection());
// remember that we are using a shared connection so it can be cleared after the
// transaction completes
isSharedConnection = true;
} else {
// if our delegate is null, create one
if (getDelegateInternal() == null) {
try {
// borrow a new connection from the pool
Connection connection = (Connection) pool.borrowObject();
setDelegate(connection);
} catch (Exception e) {
throw (SQLException) new SQLException("Unable to acquire a new connection from the pool").initCause(e);
}
}
// if we have a transaction, out delegate becomes the shared delegate
if (transactionContext != null) {
// add a listener to the transaction context
transactionContext.addTransactionContextListener(new CompletionListener());
// register our connection as the shared connection
try {
transactionContext.setSharedConnection(getDelegateInternal());
} catch (SQLException e) {
// transaction is hosed
transactionContext = null;
throw e;
}
}
}
}
public void close() throws SQLException {
if (!_closed) {
try {
// don't actually close the connection if in a transaction
// the connection will be closed by the transactionComplete method
if (transactionContext == null) {
getDelegateInternal().close();
}
} finally {
_closed = true;
}
}
}
/**
* Delegates to {@link ManagedConnection#transactionComplete()}
* for transaction completion events.
*/
protected class CompletionListener implements TransactionContextListener {
public void afterCompletion(TransactionContext completedContext, boolean commited) {
if (completedContext == transactionContext) {
transactionComplete();
}
}
}
protected void transactionComplete() {
transactionContext = null;
// if we were using a shared connection, clear the reference now that the transaction has completed
if (isSharedConnection) {
// for now, just set the delegate to null, it will be created later if needed
setDelegate(null);
isSharedConnection = false;
}
// if this connection was closed during the transaction and there is still a delegate present close it
Connection delegate = getDelegateInternal();
if (_closed && delegate != null) {
try {
setDelegate(null);
// don't actually close the connection if in a transaction
if (!delegate.isClosed()) {
// don't use super.close() because it calls passivate() which marks the
// the connection as closed without returning it to the pool
delegate.close();
}
} catch (SQLException ignored) {
// not a whole lot we can do here as connection is closed
// and this is a transaction callback so there is no
// way to report the error
} finally {
_closed = true;
}
}
}
//
// The following methods can't be used while enlisted in a transaction
//
public void setAutoCommit(boolean autoCommit) throws SQLException {
if (transactionContext != null) {
throw new SQLException("Auto-commit can not be set while enrolled in a transaction");
}
super.setAutoCommit(autoCommit);
}
public void commit() throws SQLException {
if (transactionContext != null) {
throw new SQLException("Commit can not be set while enrolled in a transaction");
}
super.commit();
}
public void rollback() throws SQLException {
if (transactionContext != null) {
throw new SQLException("Commit can not be set while enrolled in a transaction");
}
super.rollback();
}
public void setReadOnly(boolean readOnly) throws SQLException {
if (transactionContext != null) {
throw new SQLException("Read-only can not be set while enrolled in a transaction");
}
super.setReadOnly(readOnly);
}
//
// Methods for accessing the delegate connection
//
/**
* If false, getDelegate() and getInnermostDelegate() will return null.
* @return if false, getDelegate() and getInnermostDelegate() will return null
*/
public boolean isAccessToUnderlyingConnectionAllowed() {
return accessToUnderlyingConnectionAllowed;
}
public Connection getDelegate() {
if (isAccessToUnderlyingConnectionAllowed()) {
return getDelegateInternal();
} else {
return null;
}
}
public Connection getInnermostDelegate() {
if (isAccessToUnderlyingConnectionAllowed()) {
return super.getInnermostDelegateInternal();
} else {
return null;
}
}
}