svn commit: r567015 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/connectionManager/ConnectionManagerDataSource.java

[sk...@apache.org]

Author: skitching
Date: Fri Aug 17 04:08:09 2007
New Revision: 567015

URL: http://svn.apache.org/viewvc?view=rev&rev=567015
Log:
Update javadoc only.

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/connectionManager/ConnectionManagerDataSource.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/connectionManager/ConnectionManagerDataSource.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/connectionManager/ConnectionManagerDataSource.java?view=diff&rev=567015&r1=567014&r2=567015
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/connectionManager/ConnectionManagerDataSource.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/connectionManager/ConnectionManagerDataSource.java Fri Aug 17 04:08:09 2007
@@ -29,11 +29,21 @@
 import java.util.Set;
 
 /**
- * manage all borrowed connections and hand out {@link org.apache.myfaces.orchestra.connectionManager.DisconnectableConnection}s
- * so that we can close them again after the HTTP request has been finished.
- * <br />
- * I'd consider this as a hack, but a required one if your JPA-implementation do not free the connection
- * again after a lazy-init.
+ * Manage all borrowed connections and hand out
+ * {@link org.apache.myfaces.orchestra.connectionManager.DisconnectableConnection}
+ * objects so that we can close them again after the HTTP request has been finished.
+ * <p>
+ * This datasource can be configured as a "wrapper" for a real datasource. When a connection is
+ * requested from this object, a proxy is returned that simply forwards all calls transparently
+ * to the real connection. This manager keeps track of all the Connections borrowed by each
+ * thread. At some point (eg from a servlet filter) this object can be asked to check for 
+ * unreturned connections held by the current thread. If any exist then the real connection
+ * is returned to the underlying datasource and the proxy's connection reference is set to null.
+ * This ensures that a thread cannot leak real database connections.
+ * <p>
+ * Of course all code should return its connections; this is only a workaround/hack useful when the
+ * real problem cannot be fixed. This is particularly useful for JPA implementations that do not free
+ * their connection again after a lazy-init.
  *
  * @see org.apache.myfaces.orchestra.connectionManager.DisconnectableConnection
  */