deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r922514 [3/11] - in /websites/staging/deltaspike/trunk/content: ./ documentation/ retired/
Date Wed, 17 Sep 2014 12:22:53 GMT
Added: websites/staging/deltaspike/trunk/content/retired/container-control.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/container-control.html (added)
+++ websites/staging/deltaspike/trunk/content/retired/container-control.html Wed Sep 17 12:22:52
2014
@@ -0,0 +1,261 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="deltaspike-generate-pages">
+    <meta name="author" content="chm">
+
+    <title>Apache DeltaSpike - Container &amp; Control</title>
+
+    
+
+    
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
+
+    <!-- Styles -->
+    
+    <link href="./../resources/css/bootstrap.css" rel="stylesheet">    
+    <!--<link href="./../resources/css/prettify.css" rel="stylesheet" /> -->
+    <link href="./../resources/css/codehilite.css" rel="stylesheet" />
+    <link href="./../resources/css/bootstrap-responsive.css" rel="stylesheet">
+    <style type="text/css">
+        body {
+            padding-top: 60px;
+            padding-bottom: 40px;
+        }
+    </style>
+	<script type="text/javascript">
+
+	  var _gaq = _gaq || [];
+	  _gaq.push(['_setAccount', 'UA-36103647-1']);
+	  _gaq.push(['_trackPageview']);
+	
+	  (function() {
+		var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+		ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+		var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+	  })();
+	
+	</script>
+</head>
+
+<body>
+    <div class="navbar navbar-fixed-top">
+        <div class="navbar-inner">
+            <div class="container">
+                <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
+                    <span class="icon-bar"></span>
+                    <span class="icon-bar"></span>
+                    <span class="icon-bar"></span>
+                </a>
+                <a class="brand logocolor" href="/index.html">Apache DeltaSpike</a>
+                <div class="nav-collapse">
+                    <ul class="nav">
+                        <li class="active"><a href="./../index.html">Home</a></li>
+                        <li><a href="./../documentation.html">Documentation</a></li>
+                        <li><a href="./../source.html">Source</a></li>
+                        <li><a href="./../download.html">Download</a></li>
+                        <li><a href="./../community.html">Community</a></li>
+                        <!-- <li><a href="./../support.html">Support</a></li>
 -->
+                        <li><a href="./../news.html">News</a></li>
+                        <li><a href="./../migration-guide.html">Migration</a></li>
+                    </ul>
+                </div><!--/.nav-collapse -->
+                <form id="search-form" action="http://www.google.com/search" method="get"
 class="navbar-search pull-right" >
+                    <input value="deltaspike.apache.org" name="sitesearch" type="hidden"/>
+                    <input class="search-query" name="q" id="query" type="text" />
+                </form>
+            </div>
+        </div>
+    </div>
+
+    <div class="container">
+      <div class="row">
+          <div class="span12">
+              <div class="page-title">
+                <h1>Container &amp; Control</h1>
+              </div>
+              <div class="toc">
+<ul>
+<li><a href="#introduction">Introduction</a><ul>
+<li><a href="#cdicontainer">CdiContainer</a></li>
+<li><a href="#contextcontrol-usage">ContextControl usage</a></li>
+<li><a href="#embedded-servlet-support">Embedded Servlet Support</a><ul>
+<li><a href="#jetty">Jetty</a></li>
+<li><a href="#undertow">Undertow</a></li>
+<li><a href="#tomcat">Tomcat</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<hr />
+<h1 id="introduction">Introduction</h1>
+<p>There are basically two parts:</p>
+<ul>
+<li>The <code>CdiContainer</code> interface allows to boot and shutdown
the CDI container in SE applications.</li>
+<li>The <code>ContextControl</code> interface allows to control the life-cycle
of the built-in contexts of the CDI container.</li>
+</ul>
+<h2 id="cdicontainer">CdiContainer</h2>
+<p>You can use the <code>CdiContainerLoader</code> as a simple factory
to gain access to the underlying <code>CdiContainer</code> implementation. This
is of little interest for Java EE applications since the CDI Container
+already gets properly booted and shut down by the Servlet container integration.</p>
+<div class="codehilite"><pre><span class="c1">// this will give you a CdiContainer
for Weld or OWB, depending on the jar you added</span>
+<span class="n">CdiContainer</span> <span class="n">cdiContainer</span>
<span class="o">=</span> <span class="n">CdiContainerLoader</span><span
class="o">.</span><span class="na">getCdiContainer</span><span class="o">();</span>
+
+<span class="c1">// now we gonna boot the CDI container. This will trigger the classpath
scan, etc</span>
+<span class="n">cdiContainer</span><span class="o">.</span><span
class="na">boot</span><span class="o">();</span>
+
+<span class="c1">// and finally we like to start all built-in contexts</span>
+<span class="n">cdiContainer</span><span class="o">.</span><span
class="na">getContextControl</span><span class="o">().</span><span
class="na">startContexts</span><span class="o">();</span>
+
+<span class="c1">// now we can use CDI in our SE application.</span>
+<span class="c1">// And there is not a single line of OWB or Weld specific code in
your project!</span>
+
+<span class="c1">// finally we gonna stop the container</span>
+<span class="n">cdiContainer</span><span class="o">.</span><span
class="na">shutdown</span><span class="o">();</span>
+</pre></div>
+
+
+<h2 id="contextcontrol-usage">ContextControl usage</h2>
+<p>The <code>ContextControl</code> interface allows you to start and stop
built-in standard Contexts like <code>@RequestScoped</code>, <code>@ConversationScoped</code>,
<code>@SessionScoped</code>, etc. It is provided as <code>@Dependent</code>
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.</p>
+<p><strong>Restarting the RequestContext in unit tests</strong></p>
+<p>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 <a href="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html">entitymanager-per-request
approach</a> 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.</p>
+<p>Using ContextControl to detach entities:</p>
+<div class="codehilite"><pre><span class="nd">@Test</span>
+<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">testMyBusinessLogic</span><span class="o">()</span>
+<span class="o">{</span>
+    <span class="n">doSomeJpaStuff</span><span class="o">()</span>
+    <span class="n">MyEntity</span> <span class="n">me</span> <span
class="o">=</span> <span class="n">em</span><span class="o">.</span><span
class="na">find</span><span class="o">(...);</span>
+
+    <span class="n">ContextControl</span> <span class="n">ctxCtrl</span>
<span class="o">=</span> <span class="n">BeanProvider</span><span
class="o">.</span><span class="na">getContextualReference</span><span
class="o">(</span><span class="n">ContextControl</span><span class="o">.</span><span
class="na">class</span><span class="o">);</span>
+
+    <span class="c1">//stopping the request context will dispose the @RequestScoped
EntityManager</span>
+    <span class="n">ctxCtrl</span><span class="o">.</span><span
class="na">stopContext</span><span class="o">(</span><span class="n">RequestScoped</span><span
class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+    <span class="c1">// and now immediately restart the context again</span>
+    <span class="n">ctxCtrl</span><span class="o">.</span><span
class="na">startContext</span><span class="o">(</span><span class="n">RequestScoped</span><span
class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+    <span class="c1">// the entity &#39;em&#39; is now in a detached state!</span>
+    <span class="n">doSomeStuffWithTheDetachedEntity</span><span class="o">(</span><span
class="n">em</span><span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Attaching a Request Context to a new thread in EE</p>
+<p>Accessing the <code>@RequestScoped</code> bean in a new thread will
result in a <code>ContextNotActiveException</code>. The request-context usually
gets started for a particular thread via a simple <code>ServletRequestListener</code>.
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.</p>
+<p>Controlling the request-context for a Quartz-Job:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">CdiJob</span> <span class="kd">implements</span>
<span class="n">org</span><span class="o">.</span><span class="na">quartz</span><span
class="o">.</span><span class="na">Job</span>
+<span class="o">{</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">execute</span><span class="o">(</span><span class="n">JobExecutionContext</span>
<span class="n">context</span><span class="o">)</span> <span class="kd">throws</span>
<span class="n">JobExecutionException</span>
+    <span class="o">{</span>
+        <span class="n">ContextControl</span> <span class="n">ctxCtrl</span>
<span class="o">=</span> <span class="n">BeanProvider</span><span
class="o">.</span><span class="na">getContextualReference</span><span
class="o">(</span><span class="n">ContextControl</span><span class="o">.</span><span
class="na">class</span><span class="o">);</span>
+
+        <span class="c1">//this will implicitly bind a new RequestContext to the current
thread</span>
+        <span class="n">ctxCtrl</span><span class="o">.</span><span
class="na">startContext</span><span class="o">(</span><span class="n">RequestScoped</span><span
class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+        <span class="k">try</span>
+        <span class="o">{</span>
+            <span class="n">doYourWork</span><span class="o">();</span>
+        <span class="o">}</span>
+        <span class="k">finally</span>
+        <span class="o">{</span>
+            <span class="c1">//stop the RequestContext to ensure that all request-scoped
beans get cleaned up.</span>
+            <span class="n">ctxCtrl</span><span class="o">.</span><span
class="na">stopContext</span><span class="o">(</span><span class="n">RequestScoped</span><span
class="o">.</span><span class="na">class</span><span class="o">);</span>
+        <span class="o">}</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h2 id="embedded-servlet-support">Embedded Servlet Support</h2>
+<p>Starting with 1.0.2, you can use DeltaSpike to power embedded Servlet runtimes.
 This work is done via Servlet Listeners.  The configuration is specific to each container,
below are some examples.</p>
+<p>The two main listeners are <code>CdiServletRequestListener</code> and
<code>CdiServletContextListener</code>.  <code>CdiServletRequestListener</code>
is responsible for starting a <code>RequestContext</code> on each incoming request.
 In most containers this is all you need.  For Tomcat specifically, you need to use <code>CdiServletContextListener</code>
which registers the <code>CdiServletRequestListener</code>.</p>
+<p>The main usecase for this feature is for lightweight embedded runtimes, microservices.
 For each of these, it is assumed that you are using the following start up code somewhere:</p>
+<div class="codehilite"><pre><span class="n">CdiContainer</span>
<span class="n">cdiContainer</span> <span class="o">=</span> <span
class="n">CdiContainerLoader</span><span class="o">.</span><span class="na">getCdiContainer</span><span
class="o">();</span>
+<span class="n">cdiContainer</span><span class="o">.</span><span
class="na">boot</span><span class="o">();</span>
+<span class="n">cdiContainer</span><span class="o">.</span><span
class="na">getContextControl</span><span class="o">().</span><span
class="na">startContexts</span><span class="o">();</span>
+</pre></div>
+
+
+<h3 id="jetty">Jetty</h3>
+<p>For Jetty, you need to add an <code>EventListener</code> which will
be your <code>CdiServletRequestListener</code>.  The object must be instantiated.
 This must be done before the server is started.</p>
+<div class="codehilite"><pre><span class="n">Server</span> <span
class="n">server</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">Server</span><span class="o">(</span><span class="n">port</span><span
class="o">);</span>
+<span class="n">ServletContextHandler</span> <span class="n">context</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">ServletContextHandler</span><span
class="o">(</span><span class="n">ServletContextHandler</span><span
class="o">.</span><span class="na">SESSIONS</span><span class="o">);</span>
+<span class="n">context</span><span class="o">.</span><span class="na">setContextPath</span><span
class="o">(</span><span class="s">&quot;/&quot;</span><span
class="o">);</span>
+<span class="n">server</span><span class="o">.</span><span class="na">setHandler</span><span
class="o">(</span><span class="n">context</span><span class="o">);</span>
+
+<span class="n">context</span><span class="o">.</span><span class="na">addEventListener</span><span
class="o">(</span><span class="k">new</span> <span class="n">CdiServletRequestListener</span><span
class="o">());</span>
+<span class="n">context</span><span class="o">.</span><span class="na">addServlet</span><span
class="o">(</span><span class="k">new</span> <span class="n">ServletHolder</span><span
class="o">(</span><span class="k">new</span> <span class="n">YourServlet</span><span
class="o">()),</span><span class="s">&quot;/*&quot;</span><span
class="o">);</span>
+
+<span class="n">server</span><span class="o">.</span><span class="na">start</span><span
class="o">();</span>
+</pre></div>
+
+
+<h3 id="undertow">Undertow</h3>
+<p>For Undertow, you register the <code>CdiServletRequestListener</code>
via <code>ListenerInfo</code> by passing in the class to their builders.  Then
you add the <code>ListenerInfo</code> to your deployment before starting.</p>
+<div class="codehilite"><pre><span class="n">ServletInfo</span> <span
class="n">servletInfo</span> <span class="o">=</span> <span class="n">Servlets</span><span
class="o">.</span><span class="na">servlet</span><span class="o">(</span><span
class="s">&quot;YourServletName&quot;</span><span class="o">,</span>
<span class="n">YourServlet</span><span class="o">.</span><span
class="na">class</span><span class="o">).</span><span class="na">setAsyncSupported</span><span
class="o">(</span><span class="kc">true</span><span class="o">)</span>
+    <span class="o">.</span><span class="na">setLoadOnStartup</span><span
class="o">(</span><span class="mi">1</span><span class="o">).</span><span
class="na">addMapping</span><span class="o">(</span><span class="s">&quot;/*&quot;</span><span
class="o">);</span>
+<span class="n">ListenerInfo</span> <span class="n">listenerInfo</span>
<span class="o">=</span> <span class="n">Servlets</span><span class="o">.</span><span
class="na">listener</span><span class="o">(</span><span class="n">CdiServletRequestListener</span><span
class="o">.</span><span class="na">class</span><span class="o">);</span>
+<span class="n">DeploymentInfo</span> <span class="n">di</span> <span
class="o">=</span> <span class="k">new</span> <span class="n">DeploymentInfo</span><span
class="o">()</span>
+        <span class="o">.</span><span class="na">addListener</span><span
class="o">(</span><span class="n">listenerInfo</span><span class="o">)</span>
+        <span class="o">.</span><span class="na">setContextPath</span><span
class="o">(</span><span class="s">&quot;/&quot;</span><span
class="o">)</span>
+        <span class="o">.</span><span class="na">addServlet</span><span
class="o">(</span><span class="n">servletInfo</span><span class="o">).</span><span
class="na">setDeploymentName</span><span class="o">(</span><span class="s">&quot;CdiSEServlet&quot;</span><span
class="o">)</span>
+        <span class="o">.</span><span class="na">setClassLoader</span><span
class="o">(</span><span class="n">ClassLoader</span><span class="o">.</span><span
class="na">getSystemClassLoader</span><span class="o">());</span>
+<span class="n">DeploymentManager</span> <span class="n">deploymentManager</span>
<span class="o">=</span> <span class="n">Servlets</span><span class="o">.</span><span
class="na">defaultContainer</span><span class="o">().</span><span
class="na">addDeployment</span><span class="o">(</span><span class="n">di</span><span
class="o">);</span>
+<span class="n">deploymentManager</span><span class="o">.</span><span
class="na">deploy</span><span class="o">();</span>
+<span class="n">Undertow</span> <span class="n">server</span> <span
class="o">=</span> <span class="n">Undertow</span><span class="o">.</span><span
class="na">builder</span><span class="o">()</span>
+        <span class="o">.</span><span class="na">addHttpListener</span><span
class="o">(</span><span class="n">port</span><span class="o">,</span>
<span class="s">&quot;localhost&quot;</span><span class="o">)</span>
+        <span class="o">.</span><span class="na">setHandler</span><span
class="o">(</span><span class="n">deploymentManager</span><span class="o">.</span><span
class="na">start</span><span class="o">())</span>
+        <span class="o">.</span><span class="na">build</span><span
class="o">();</span>
+<span class="n">server</span><span class="o">.</span><span class="na">start</span><span
class="o">();</span>
+</pre></div>
+
+
+<h3 id="tomcat">Tomcat</h3>
+<p>For Tomcat, you need to register the <code>CdiServletContextListener</code>
instead of the <code>CdiServletRequestListener</code>.  It is added as an <code>ApplicationListener</code>
by passing in the class name as a <code>String</code>.</p>
+<div class="codehilite"><pre><span class="n">Tomcat</span> <span
class="n">tomcat</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">Tomcat</span><span class="o">();</span>
+<span class="n">tomcat</span><span class="o">.</span><span class="na">setPort</span><span
class="o">(</span><span class="n">port</span><span class="o">);</span>
+<span class="n">File</span> <span class="n">base</span> <span
class="o">=</span> <span class="k">new</span> <span class="n">File</span><span
class="o">(</span><span class="s">&quot;...&quot;</span><span
class="o">);</span>
+<span class="n">Context</span> <span class="n">ctx</span> <span
class="o">=</span> <span class="n">tomcat</span><span class="o">.</span><span
class="na">addContext</span><span class="o">(</span><span class="s">&quot;/&quot;</span><span
class="o">,</span><span class="n">base</span><span class="o">.</span><span
class="na">getAbsolutePath</span><span class="o">());</span>
+<span class="n">StandardContext</span> <span class="n">standardContext</span>
<span class="o">=</span> <span class="o">(</span><span class="n">StandardContext</span><span
class="o">)</span><span class="n">ctx</span><span class="o">;</span>
+<span class="n">standardContext</span><span class="o">.</span><span
class="na">addApplicationListener</span><span class="o">(</span><span
class="n">CdiServletContextListener</span><span class="o">.</span><span
class="na">class</span><span class="o">.</span><span class="na">getName</span><span
class="o">());</span>
+<span class="n">Wrapper</span> <span class="n">wrapper</span> <span
class="o">=</span> <span class="n">Tomcat</span><span class="o">.</span><span
class="na">addServlet</span><span class="o">(</span><span class="n">ctx</span><span
class="o">,</span><span class="s">&quot;YourServlet&quot;</span><span
class="o">,</span><span class="n">YourServlet</span><span class="o">.</span><span
class="na">class</span><span class="o">.</span><span class="na">getName</span><span
class="o">());</span>
+<span class="n">wrapper</span><span class="o">.</span><span class="na">addMapping</span><span
class="o">(</span><span class="s">&quot;/*&quot;</span><span
class="o">);</span>
+<span class="n">tomcat</span><span class="o">.</span><span class="na">start</span><span
class="o">();</span>
+</pre></div>
+          </div>
+      </div>
+
+      <hr>
+
+      <footer>
+        <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed under
the Apache License, Version 2.0.</p>
+        <p>Apache and the Apache feather logo are trademarks of The Apache Software
Foundation.</p>
+      </footer>
+
+    </div> <!-- /.container -->
+
+    <!-- Javascript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <!--<script src="./../resources/js/prettyfy.js"></script> -->
+    <script src="./../resources/js/prettyprint.js"></script>
+    <script src="./../resources/js/jquery.js"></script>
+    <script src="./../resources/js/bootstrap-transition.js"></script>
+    <script src="./../resources/js/bootstrap-alert.js"></script>
+    <script src="./../resources/js/bootstrap-modal.js"></script>
+    <script src="./../resources/js/bootstrap-dropdown.js"></script>
+    <script src="./../resources/js/bootstrap-scrollspy.js"></script>
+    <script src="./../resources/js/bootstrap-tab.js"></script>
+    <script src="./../resources/js/bootstrap-tooltip.js"></script>
+    <script src="./../resources/js/bootstrap-popover.js"></script>
+    <script src="./../resources/js/bootstrap-button.js"></script>
+    <script src="./../resources/js/bootstrap-collapse.js"></script>
+    <script src="./../resources/js/bootstrap-carousel.js"></script>
+    <script src="./../resources/js/bootstrap-typeahead.js"></script>
+</body>
+</html>



Mime
View raw message