View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.dbcp2.managed;
18  
19  import java.sql.Connection;
20  import java.sql.SQLException;
21  import java.util.concurrent.locks.Lock;
22  import java.util.concurrent.locks.ReentrantLock;
23  
24  import org.apache.commons.dbcp2.DelegatingConnection;
25  import org.apache.commons.pool2.ObjectPool;
26  
27  /**
28   * ManagedConnection is responsible for managing a database connection in a transactional environment (typically called
29   * "Container Managed"). A managed connection operates like any other connection when no global transaction (a.k.a. XA
30   * transaction or JTA Transaction) is in progress. When a global transaction is active a single physical connection to
31   * the database is used by all ManagedConnections accessed in the scope of the transaction. Connection sharing means
32   * that all data access during a transaction has a consistent view of the database. When the global transaction is
33   * committed or rolled back the enlisted connections are committed or rolled back. Typically, upon transaction
34   * completion, a connection returns to the auto commit setting in effect before being enlisted in the transaction, but
35   * some vendors do not properly implement this.
36   * <p>
37   * When enlisted in a transaction the setAutoCommit(), commit(), rollback(), and setReadOnly() methods throw a
38   * SQLException. This is necessary to assure that the transaction completes as a single unit.
39   * </p>
40   *
41   * @param <C>
42   *            the Connection type
43   *
44   * @since 2.0
45   */
46  public class ManagedConnection<C extends Connection> extends DelegatingConnection<C> {
47  
48      /**
49       * Delegates to {@link ManagedConnection#transactionComplete()} for transaction completion events.
50       *
51       * @since 2.0
52       */
53      protected class CompletionListener implements TransactionContextListener {
54          @Override
55          public void afterCompletion(final TransactionContext completedContext, final boolean committed) {
56              if (completedContext == transactionContext) {
57                  transactionComplete();
58              }
59          }
60      }
61  
62      private final ObjectPool<C> pool;
63      private final TransactionRegistry transactionRegistry;
64      private final boolean accessToUnderlyingConnectionAllowed;
65      private TransactionContext transactionContext;
66      private boolean isSharedConnection;
67      private final Lock lock;
68  
69      /**
70       * Constructs a new instance responsible for managing a database connection in a transactional environment.
71       *
72       * @param pool
73       *            The connection pool.
74       * @param transactionRegistry
75       *            The transaction registry.
76       * @param accessToUnderlyingConnectionAllowed
77       *            Whether or not to allow access to the underlying Connection.
78       * @throws SQLException
79       *             Thrown when there is problem managing transactions.
80       */
81      public ManagedConnection(final ObjectPool<C> pool, final TransactionRegistry transactionRegistry,
82              final boolean accessToUnderlyingConnectionAllowed) throws SQLException {
83          super(null);
84          this.pool = pool;
85          this.transactionRegistry = transactionRegistry;
86          this.accessToUnderlyingConnectionAllowed = accessToUnderlyingConnectionAllowed;
87          this.lock = new ReentrantLock();
88          updateTransactionStatus();
89      }
90  
91      @Override
92      protected void checkOpen() throws SQLException {
93          super.checkOpen();
94          updateTransactionStatus();
95      }
96  
97      @Override
98      public void close() throws SQLException {
99          if (!isClosedInternal()) {
100             // Don't actually close the connection if in a transaction. The
101             // connection will be closed by the transactionComplete method.
102             //
103             // DBCP-484 we need to make sure setClosedInternal(true) being
104             // invoked if transactionContext is not null as this value will
105             // be modified by the transactionComplete method which could run
106             // in the different thread with the transaction calling back.
107             lock.lock();
108             try {
109                 if (transactionContext == null || transactionContext.isTransactionComplete()) {
110                     super.close();
111                 }
112             } finally {
113                 try {
114                     setClosedInternal(true);
115                 } finally {
116                     lock.unlock();
117                 }
118             }
119         }
120     }
121 
122     @Override
123     public void commit() throws SQLException {
124         if (transactionContext != null) {
125             throw new SQLException("Commit cannot be set while enrolled in a transaction");
126         }
127         super.commit();
128     }
129 
130     @Override
131     public C getDelegate() {
132         if (isAccessToUnderlyingConnectionAllowed()) {
133             return getDelegateInternal();
134         }
135         return null;
136     }
137 
138     //
139     // The following methods can't be used while enlisted in a transaction
140     //
141 
142     @Override
143     public Connection getInnermostDelegate() {
144         if (isAccessToUnderlyingConnectionAllowed()) {
145             return super.getInnermostDelegateInternal();
146         }
147         return null;
148     }
149 
150     /**
151      * Gets the transaction context.
152      *
153      * @return The transaction context.
154      * @since 2.6.0
155      */
156     public TransactionContext getTransactionContext() {
157         return transactionContext;
158     }
159 
160     /**
161      * Gets the transaction registry.
162      *
163      * @return The transaction registry.
164      * @since 2.6.0
165      */
166     public TransactionRegistry getTransactionRegistry() {
167         return transactionRegistry;
168     }
169 
170     /**
171      * If false, getDelegate() and getInnermostDelegate() will return null.
172      *
173      * @return if false, getDelegate() and getInnermostDelegate() will return null
174      */
175     public boolean isAccessToUnderlyingConnectionAllowed() {
176         return accessToUnderlyingConnectionAllowed;
177     }
178 
179     @Override
180     public void rollback() throws SQLException {
181         if (transactionContext != null) {
182             throw new SQLException("Commit cannot be set while enrolled in a transaction");
183         }
184         super.rollback();
185     }
186 
187     @Override
188     public void setAutoCommit(final boolean autoCommit) throws SQLException {
189         if (transactionContext != null) {
190             throw new SQLException("Auto-commit cannot be set while enrolled in a transaction");
191         }
192         super.setAutoCommit(autoCommit);
193     }
194 
195     @Override
196     public void setReadOnly(final boolean readOnly) throws SQLException {
197         if (transactionContext != null) {
198             throw new SQLException("Read-only cannot be set while enrolled in a transaction");
199         }
200         super.setReadOnly(readOnly);
201     }
202 
203     /**
204      * Completes the transaction.
205      */
206     protected void transactionComplete() {
207         lock.lock();
208         try {
209             transactionContext.completeTransaction();
210         } finally {
211             lock.unlock();
212         }
213 
214         // If we were using a shared connection, clear the reference now that
215         // the transaction has completed
216         if (isSharedConnection) {
217             setDelegate(null);
218             isSharedConnection = false;
219         }
220 
221         // autoCommit may have been changed directly on the underlying connection
222         clearCachedState();
223 
224         // If this connection was closed during the transaction and there is
225         // still a delegate present close it
226         final Connection delegate = getDelegateInternal();
227         if (isClosedInternal() && delegate != null) {
228             try {
229                 setDelegate(null);
230 
231                 if (!delegate.isClosed()) {
232                     delegate.close();
233                 }
234             } catch (final SQLException ignored) {
235                 // Not a whole lot we can do here as connection is closed
236                 // and this is a transaction callback so there is no
237                 // way to report the error.
238             }
239         }
240     }
241 
242     private void updateTransactionStatus() throws SQLException {
243         // if there is an active transaction context, assure the transaction context hasn't changed
244         if (transactionContext != null && !transactionContext.isTransactionComplete()) {
245             if (transactionContext.isActive()) {
246                 if (transactionContext != transactionRegistry.getActiveTransactionContext()) {
247                     throw new SQLException("Connection cannot be used while enlisted in another transaction");
248                 }
249                 return;
250             }
251             // transaction should have been cleared up by TransactionContextListener, but in
252             // rare cases another lister could have registered which uses the connection before
253             // our listener is called. In that rare case, trigger the transaction complete call now
254             transactionComplete();
255         }
256 
257         // the existing transaction context ended (or we didn't have one), get the active transaction context
258         transactionContext = transactionRegistry.getActiveTransactionContext();
259 
260         // if there is an active transaction context, and it already has a shared connection, use it
261         if (transactionContext != null && transactionContext.getSharedConnection() != null) {
262             // A connection for the connection factory has already been enrolled
263             // in the transaction, replace our delegate with the enrolled connection
264 
265             // return current connection to the pool
266             @SuppressWarnings("resource")
267             final C connection = getDelegateInternal();
268             setDelegate(null);
269             if (connection != null && transactionContext.getSharedConnection() != connection) {
270                 try {
271                     pool.returnObject(connection);
272                 } catch (final Exception e) {
273                     // whatever... try to invalidate the connection
274                     try {
275                         pool.invalidateObject(connection);
276                     } catch (final Exception ignored) {
277                         // no big deal
278                     }
279                 }
280             }
281 
282             // add a listener to the transaction context
283             transactionContext.addTransactionContextListener(new CompletionListener());
284 
285             // Set our delegate to the shared connection. Note that this will
286             // always be of type C since it has been shared by another
287             // connection from the same pool.
288             @SuppressWarnings("unchecked")
289             final C shared = (C) transactionContext.getSharedConnection();
290             setDelegate(shared);
291 
292             // remember that we are using a shared connection, so it can be cleared after the
293             // transaction completes
294             isSharedConnection = true;
295         } else {
296             C connection = getDelegateInternal();
297             // if our delegate is null, create one
298             if (connection == null) {
299                 try {
300                     // borrow a new connection from the pool
301                     connection = pool.borrowObject();
302                     setDelegate(connection);
303                 } catch (final Exception e) {
304                     throw new SQLException("Unable to acquire a new connection from the pool", e);
305                 }
306             }
307 
308             // if we have a transaction, out delegate becomes the shared delegate
309             if (transactionContext != null) {
310                 // add a listener to the transaction context
311                 transactionContext.addTransactionContextListener(new CompletionListener());
312 
313                 // register our connection as the shared connection
314                 try {
315                     transactionContext.setSharedConnection(connection);
316                 } catch (final SQLException e) {
317                     // transaction is hosed
318                     transactionContext = null;
319                     try {
320                         pool.invalidateObject(connection);
321                     } catch (final Exception ignored) {
322                         // we are try but no luck
323                     }
324                     throw e;
325                 }
326             }
327         }
328         // autoCommit may have been changed directly on the underlying
329         // connection
330         clearCachedState();
331     }
332 }