svn commit: r1422406 - /incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext

[gp...@apache.org]

Author: gpetracek
Date: Sat Dec 15 23:14:50 2012
New Revision: 1422406

URL: http://svn.apache.org/viewvc?rev=1422406&view=rev
Log:
updated content - thx to Mark Struberg

Modified:
    incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext

Modified: incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext
URL: http://svn.apache.org/viewvc/incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext?rev=1422406&r1=1422405&r2=1422406&view=diff
==============================================================================
--- incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext (original)
+++ incubator/deltaspike/site/trunk/content/deltaspike/documentation.mdtext Sat Dec 15 23:14:50 2012
@@ -247,3 +247,67 @@ Before the application exits, you have t
 ## JSF (optional)
 
 <a class="btn" href="jsf.html">View details »</a>
+
+## Container-Control (optional)
+
+### Usage
+
+There are basically two parts
+The *CdiContainer* Interface will provide you with a way to boot and shutdown the CDI Container in SE applications.
+The *ContextControl* interface provides a way to control the life cycle of the built-in Contexts of the CDI container.
+
+### CdiContainer
+
+See the Java-SE part [above](#start-the-cdi-container).
+
+### ContextControl usage
+
+The `ContextControl` interface allows you to start and stop built-in standard Contexts like `@RequestScoped`, `@ConversationScoped`, `@SessionScoped`, etc. It is provided as `@Dependent` bean and can get injected in the classic CDI way. This is not only usable in Java SE projects but also very helpful in Servlets and Java EE containers.
+
+**Restarting the RequestContext in unit tests**
+
+In unit testing it can be necessary to test with attached and also with detached JPA entities. A very common approach for JPA is the [entitymanager-per-request approach](http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html) and thus have a producer method which creates a @RequestScoped EntityManager. Since a single unit test is usually treated as one ‘request’ a problem arises detaching entities.
+
+Using ContextControl to detach entities:
+
+    @Test
+    public void testMyBusinessLogic() {
+        doSomeJpaStuff()
+        MyEntity me = em.find(...);
+
+        ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+        //stopping the request context will dispose the @RequestScoped EntityManager
+        ctxCtrl.stopContext(RequestScoped.class);
+
+        // and now immediately restart the context again
+        ctxCtrl.startContext(RequestScoped.class);
+
+        // the entity 'em' is now in a detached state!
+        doSomeStuffWithTheDetachedEntity(em);
+
+### Attaching a Request Context to a new thread in EE
+
+Accessing the `@RequestScoped` bean in a new thread will result in a `ContextNotActiveException`. The request-context usually gets started for a particular thread via a simple `ServletRequestListener`. So "no servlet-request" means that there is no Servlet-Context for the current (/new) Thread.
+You might face such issues, if you would like to reuse business services in e.g. a Quartz Job. 
+
+Controlling the request-context for a Quartz-Job:
+
+    public class CdiJob implements org.quartz.Job {
+        public void execute(JobExecutionContext context) throws JobExecutionException {
+            ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+            //this will implicitly bind a new RequestContext to the current thread
+            ctxCtrl.startContext(RequestScoped.class);
+
+            try
+            {
+                doYourWork();
+            }
+            finally
+            {
+                //stop the RequestContext to ensure that all request-scoped beans get cleaned up.
+                ctxCtrl.stopContext(RequestScoped.class);
+            }
+        }
+    }
\ No newline at end of file