svn commit: r581905 - /myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/persistenceContexts/JpaPersistenceContextFactory.java

[sk...@apache.org]

Author: skitching
Date: Thu Oct  4 06:51:18 2007
New Revision: 581905

URL: http://svn.apache.org/viewvc?rev=581905&view=rev
Log:
Add comments and javadoc only.

Modified:
    myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/persistenceContexts/JpaPersistenceContextFactory.java

Modified: myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/persistenceContexts/JpaPersistenceContextFactory.java
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/persistenceContexts/JpaPersistenceContextFactory.java?rev=581905&r1=581904&r2=581905&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/persistenceContexts/JpaPersistenceContextFactory.java (original)
+++ myfaces/orchestra/trunk/core/src/main/java/org/apache/myfaces/orchestra/conversation/persistenceContexts/JpaPersistenceContextFactory.java Thu Oct  4 06:51:18 2007
@@ -29,7 +29,16 @@
 import java.util.Stack;
 
 /**
- * myfaces orchestra entity manager factory
+ * A factory for PersistenceContext objects which integrates with Spring's JPA
+ * support.
+ * <p>
+ * When a bean is invoked which is associated with a conversation, but the conversation
+ * does not yet have a PersistenceContext, then this factory is used to create a
+ * PersistenceContext.
+ * <p>
+ * The returned object knows how to configure itself as the "current persistence context"
+ * within Spring when a method on that bean is invoked, and how to restore the earlier
+ * "current persistence context" after the method returns.
  */
 public class JpaPersistenceContextFactory implements PersistenceContextFactory
 {
@@ -44,6 +53,26 @@
 		{
 			private final Stack bindings = new Stack();
 
+			// Store the current EntityManagerHolder on a stack, then install our own as the
+			// current EntityManagerHolder. Storing the old one allows us to restore it when
+			// this context is "unbound".
+			//
+			// Orchestra calls bind every time a method is invoked on a bean which has
+			// a conversation with a persistence context. The unbind is invoked when the
+			// invoked method on that bean returns.
+			//
+			// When a bean has a property that has been annotated as @PersistenceContext,
+			// Spring injects a proxy that looks up the "current" persistence context whenever
+			// a method is invoked on it. Because Orchestra has called persistencecontext.bind
+			// when the bean was first entered, and this object's bind method has installed
+			// itself as the "current" spring persistence context object, the bean sees the
+			// persistence context that is associated with its conversation.
+			//
+			// TODO: what happens when a bean invokes a method on itself? Does bind get called
+			// again? If so, then this implementation is inefficient as it will push itself
+			// onto the stack over and over again. This could be optimised by checking whether
+			// this is the current context, and if so just incrementing a counter rather than
+			// pushing onto a stack...
 			public void bind()
 			{
 				synchronized(bindings)