/*
    * 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.dbcp2.managed;
  
  import java.sql.Connection;
  import java.sql.SQLException;
  import java.util.concurrent.locks.Lock;
  import java.util.concurrent.locks.ReentrantLock;
  
  import org.apache.commons.dbcp2.DelegatingConnection;
  import org.apache.commons.pool2.ObjectPool;
  
  /**
   * 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.
   * <p>
   * 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.
   * </p>
   *
   * @param <C>
   *            the Connection type
   *
   * @since 2.0
   */
  public class ManagedConnection<C extends Connection> extends DelegatingConnection<C> {
  
      /**
       * Delegates to {@link ManagedConnection#transactionComplete()} for transaction completion events.
       *
       * @since 2.0
       */
      protected class CompletionListener implements TransactionContextListener {
          @Override
          public void afterCompletion(final TransactionContext completedContext, final boolean committed) {
              if (completedContext == transactionContext) {
                  transactionComplete();
              }
          }
      }
  
      private final ObjectPool<C> pool;
      private final TransactionRegistry transactionRegistry;
      private final boolean accessToUnderlyingConnectionAllowed;
      private TransactionContext transactionContext;
      private boolean isSharedConnection;
      private final Lock lock;
  
      /**
       * Constructs a new instance responsible for managing a database connection in a transactional environment.
       *
       * @param pool
       *            The connection pool.
       * @param transactionRegistry
       *            The transaction registry.
       * @param accessToUnderlyingConnectionAllowed
       *            Whether or not to allow access to the underlying Connection.
       * @throws SQLException
       *             Thrown when there is problem managing transactions.
       */
      public ManagedConnection(final ObjectPool<C> pool, final TransactionRegistry transactionRegistry,
              final boolean accessToUnderlyingConnectionAllowed) throws SQLException {
          super(null);
          this.pool = pool;
          this.transactionRegistry = transactionRegistry;
          this.accessToUnderlyingConnectionAllowed = accessToUnderlyingConnectionAllowed;
          this.lock = new ReentrantLock();
          updateTransactionStatus();
      }
  
      @Override
      protected void checkOpen() throws SQLException {
          super.checkOpen();
          updateTransactionStatus();
      }
  
      @Override
      public void close() throws SQLException {
          if (!isClosedInternal()) {
             // Don't actually close the connection if in a transaction. The
             // connection will be closed by the transactionComplete method.
             //
             // DBCP-484 we need to make sure setClosedInternal(true) being
             // invoked if transactionContext is not null as this value will
             // be modified by the transactionComplete method which could run
             // in the different thread with the transaction calling back.
             lock.lock();
             try {
                 if (transactionContext == null || transactionContext.isTransactionComplete()) {
                     super.close();
                 }
             } finally {
                 try {
                     setClosedInternal(true);
                 } finally {
                     lock.unlock();
                 }
             }
         }
     }
 
     @Override
     public void commit() throws SQLException {
         if (transactionContext != null) {
             throw new SQLException("Commit cannot be set while enrolled in a transaction");
         }
         super.commit();
     }
 
     @Override
     public C getDelegate() {
         if (isAccessToUnderlyingConnectionAllowed()) {
             return getDelegateInternal();
         }
         return null;
     }
 
     //
     // The following methods can't be used while enlisted in a transaction
     //
 
     @Override
     public Connection getInnermostDelegate() {
         if (isAccessToUnderlyingConnectionAllowed()) {
             return super.getInnermostDelegateInternal();
         }
         return null;
     }
 
     /**
      * Gets the transaction context.
      *
      * @return The transaction context.
      * @since 2.6.0
      */
     public TransactionContext getTransactionContext() {
         return transactionContext;
     }
 
     /**
      * Gets the transaction registry.
      *
      * @return The transaction registry.
      * @since 2.6.0
      */
     public TransactionRegistry getTransactionRegistry() {
         return transactionRegistry;
     }
 
     /**
      * If false, getDelegate() and getInnermostDelegate() will return null.
      *
      * @return if false, getDelegate() and getInnermostDelegate() will return null
      */
     public boolean isAccessToUnderlyingConnectionAllowed() {
         return accessToUnderlyingConnectionAllowed;
     }
 
     @Override
     public void rollback() throws SQLException {
         if (transactionContext != null) {
             throw new SQLException("Commit cannot be set while enrolled in a transaction");
         }
         super.rollback();
     }
 
     @Override
     public void setAutoCommit(final boolean autoCommit) throws SQLException {
         if (transactionContext != null) {
             throw new SQLException("Auto-commit cannot be set while enrolled in a transaction");
         }
         super.setAutoCommit(autoCommit);
     }
 
     @Override
     public void setReadOnly(final boolean readOnly) throws SQLException {
         if (transactionContext != null) {
             throw new SQLException("Read-only cannot be set while enrolled in a transaction");
         }
         super.setReadOnly(readOnly);
     }
 
     /**
      * Completes the transaction.
      */
     protected void transactionComplete() {
         lock.lock();
         try {
             transactionContext.completeTransaction();
         } finally {
             lock.unlock();
         }
 
         // If we were using a shared connection, clear the reference now that
         // the transaction has completed
         if (isSharedConnection) {
             setDelegate(null);
             isSharedConnection = false;
         }
 
         // autoCommit may have been changed directly on the underlying connection
         clearCachedState();
 
         // If this connection was closed during the transaction and there is
         // still a delegate present close it
         final Connection delegate = getDelegateInternal();
         if (isClosedInternal() && delegate != null) {
             try {
                 setDelegate(null);
 
                 if (!delegate.isClosed()) {
                     delegate.close();
                 }
             } catch (final 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.
             }
         }
     }
 
     private void updateTransactionStatus() throws SQLException {
         // if there is an active transaction context, assure the transaction context hasn't changed
         if (transactionContext != null && !transactionContext.isTransactionComplete()) {
             if (transactionContext.isActive()) {
                 if (transactionContext != transactionRegistry.getActiveTransactionContext()) {
                     throw new SQLException("Connection cannot be used while enlisted in another transaction");
                 }
                 return;
             }
             // 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
             @SuppressWarnings("resource")
             final C connection = getDelegateInternal();
             setDelegate(null);
             if (connection != null && transactionContext.getSharedConnection() != connection) {
                 try {
                     pool.returnObject(connection);
                 } catch (final Exception e) {
                     // whatever... try to invalidate the connection
                     try {
                         pool.invalidateObject(connection);
                     } catch (final Exception ignored) {
                         // no big deal
                     }
                 }
             }
 
             // add a listener to the transaction context
             transactionContext.addTransactionContextListener(new CompletionListener());
 
             // Set our delegate to the shared connection. Note that this will
             // always be of type C since it has been shared by another
             // connection from the same pool.
             @SuppressWarnings("unchecked")
             final C shared = (C) transactionContext.getSharedConnection();
             setDelegate(shared);
 
             // remember that we are using a shared connection, so it can be cleared after the
             // transaction completes
             isSharedConnection = true;
         } else {
             C connection = getDelegateInternal();
             // if our delegate is null, create one
             if (connection == null) {
                 try {
                     // borrow a new connection from the pool
                     connection = pool.borrowObject();
                     setDelegate(connection);
                 } catch (final Exception e) {
                     throw new SQLException("Unable to acquire a new connection from the pool", 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(connection);
                 } catch (final SQLException e) {
                     // transaction is hosed
                     transactionContext = null;
                     try {
                         pool.invalidateObject(connection);
                     } catch (final Exception ignored) {
                         // we are try but no luck
                     }
                     throw e;
                 }
             }
         }
         // autoCommit may have been changed directly on the underlying
         // connection
         clearCachedState();
     }
 }