You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by bu...@apache.org on 2020/02/05 11:25:47 UTC
svn commit: r1056144 [5/18] - in /websites/staging/deltaspike/trunk/content:
./ javadoc/1.3.1-SNAPSHOT/ javadoc/1.4.1-SNAPSHOT/ javadoc/1.5.1-SNAPSHOT/
staging/documentation/
Modified: websites/staging/deltaspike/trunk/content/staging/documentation/container-control.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/staging/documentation/container-control.html (original)
+++ websites/staging/deltaspike/trunk/content/staging/documentation/container-control.html Wed Feb 5 11:25:47 2020
@@ -1,661 +1,661 @@
-<!DOCTYPE html>
-<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">
- <!-- No caching headers -->
- <meta http-equiv="cache-control" content="no-cache"/>
- <meta http-equiv="pragma" content="no-cache"/>
- <meta http-equiv="expires" content="-1"/>
-
- <title>Container Control Module</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
- "License"); 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
- "AS IS" 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="https://deltaspike.apache.org/resources/css/bootstrap.css" rel="stylesheet">
- <link href="https://deltaspike.apache.org/resources/css/bootstrap-responsive.css" rel="stylesheet">
- <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.1.0/css/font-awesome.min.css" rel="stylesheet">
-
-
-
-
- <!-- Tocify - nice dynamic autoscrolling TOC -->
- <link href="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/stylesheets/jquery.tocify.min.css" rel="stylesheet">
- <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
- <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
- <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/javascripts/jquery.tocify.min.js"></script>
-
-
- <script type="text/javascript">
- $(function () {
- $("#toc").tocify({
- scrollTo: 50,
- extendPage: true,
- context: "#doc-content",
- selectors: "h2,h3,h4,h5"
- });
- $(".fallback-toc").hide();
- });
- </script>
-
-
- <style type="text/css">
- /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
-/*pre.CodeRay {background-color:#f7f7f8;}*/
-.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
-.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
-.CodeRay .line-numbers strong{font-weight: normal}
-table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
-table.CodeRay td{vertical-align: top}
-table.CodeRay td.line-numbers{text-align:right}
-table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
-table.CodeRay td.code{padding:0 0 0 .5em}
-table.CodeRay td.code>pre{padding:0}
-.CodeRay .debug{color:#fff !important;background:#000080 !important}
-.CodeRay .annotation{color:#007}
-.CodeRay .attribute-name{color:#000080}
-.CodeRay .attribute-value{color:#700}
-.CodeRay .binary{color:#509}
-.CodeRay .comment{color:#998;font-style:italic}
-.CodeRay .char{color:#04d}
-.CodeRay .char .content{color:#04d}
-.CodeRay .char .delimiter{color:#039}
-.CodeRay .class{color:#458;font-weight:bold}
-.CodeRay .complex{color:#a08}
-.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
-.CodeRay .color{color:#099}
-.CodeRay .class-variable{color:#369}
-.CodeRay .decorator{color:#b0b}
-.CodeRay .definition{color:#099}
-.CodeRay .delimiter{color:#000}
-.CodeRay .doc{color:#970}
-.CodeRay .doctype{color:#34b}
-.CodeRay .doc-string{color:#d42}
-.CodeRay .escape{color:#666}
-.CodeRay .entity{color:#800}
-.CodeRay .error{color:#808}
-.CodeRay .exception{color:inherit}
-.CodeRay .filename{color:#099}
-.CodeRay .function{color:#900;font-weight:bold}
-.CodeRay .global-variable{color:#008080}
-.CodeRay .hex{color:#058}
-.CodeRay .integer,.CodeRay .float{color:#099}
-.CodeRay .include{color:#555}
-.CodeRay .inline{color:#00}
-.CodeRay .inline .inline{background:#ccc}
-.CodeRay .inline .inline .inline{background:#bbb}
-.CodeRay .inline .inline-delimiter{color:#d14}
-.CodeRay .inline-delimiter{color:#d14}
-.CodeRay .important{color:#555;font-weight:bold}
-.CodeRay .interpreted{color:#b2b}
-.CodeRay .instance-variable{color:#008080}
-.CodeRay .label{color:#970}
-.CodeRay .local-variable{color:#963}
-.CodeRay .octal{color:#40e}
-.CodeRay .predefined{color:#369}
-.CodeRay .preprocessor{color:#579}
-.CodeRay .pseudo-class{color:#555}
-.CodeRay .directive{font-weight:bold}
-.CodeRay .type{font-weight:bold}
-.CodeRay .predefined-type{color:inherit}
-.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
-.CodeRay .key{color:#808}
-.CodeRay .key .delimiter{color:#606}
-.CodeRay .key .char{color:#80f}
-.CodeRay .value{color:#088}
-.CodeRay .regexp .delimiter{color:#808}
-.CodeRay .regexp .content{color:#808}
-.CodeRay .regexp .modifier{color:#808}
-.CodeRay .regexp .char{color:#d14}
-.CodeRay .regexp .function{color:#404;font-weight:bold}
-.CodeRay .string{color:#d20}
-.CodeRay .string .string .string{background:#ffd0d0}
-.CodeRay .string .content{color:#d14}
-.CodeRay .string .char{color:#d14}
-.CodeRay .string .delimiter{color:#d14}
-.CodeRay .shell{color:#d14}
-.CodeRay .shell .delimiter{color:#d14}
-.CodeRay .symbol{color:#990073}
-.CodeRay .symbol .content{color:#a60}
-.CodeRay .symbol .delimiter{color:#630}
-.CodeRay .tag{color:#008080}
-.CodeRay .tag-special{color:#d70}
-.CodeRay .variable{color:#036}
-.CodeRay .insert{background:#afa}
-.CodeRay .delete{background:#faa}
-.CodeRay .change{color:#aaf;background:#007}
-.CodeRay .head{color:#f8f;background:#505}
-.CodeRay .insert .insert{color:#080}
-.CodeRay .delete .delete{color:#800}
-.CodeRay .change .change{color:#66f}
-.CodeRay .head .head{color:#f4f}
-
- body {
- padding-top: 60px;
- padding-bottom: 40px;
- }
-
- .toc-like {
- border-radius: 6px;
- border: 1px solid #ccc;
- }
-
- .toc-like li {
- line-height: 30px;
- text-indent: 10px;
- }
-
- .toc-like li.custom-toc-header {
- font-weight: bold;
- background: #666;
- color: white;
- cursor: initial !important;
- padding: 5px;
- }
-
- .toc-like li.custom-toc-header a {
- color: white;
- font-style: normal;
- text-shadow: none;
- padding: 0;
- }
-
- .toc-like li.custom-toc-header:hover a {
- background: #666;
- }
-
- .page-title {
- text-align: left;
- }
-
- #doc-content h2,
- #doc-content h3,
- #doc-content h4,
- #doc-content h5,
- #doc-content h6 {
- padding-top: 0;
- margin-top: 25px;
- margin-bottom: 10px;
- line-height: 1.4em;
- }
-
- #doc-content h2 {
- border-bottom: 1px solid lightgrey;
- }
-
-
- </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><a href="../index.html">Home</a></li>
- <li class="active"><a href="../documentation">Documentation</a></li>
- <li ><a href="../javadoc.html">Javadoc</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>
- </ul>
- </div>
- <!--/.nav-collapse -->
- <form id="search-form" action="https://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-fluid">
-
-
-
- <div class="span8">
- <div class="page-title">
- <h1>Container Control Module</h1>
- </div>
-
- <div id="doc-content">
- <div class="sect1">
-<h2 id="_overview">Overview</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The Container Control module provides CDI container booting and shutdown, crucial for CDI use in Java SE6+ environments, and associated context lifecycle management. The module abstracts individual CDI container implementations, ensuring projects are container-independent.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_project_setup">Project Setup</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <a href="configure.html">Configure DeltaSpike in Your Projects</a>. For Maven-independent projects, see <a href="configure.html#config-maven-indep">Configure DeltaSpike in Maven-independent Projects</a>.</p>
-</div>
-<div class="sect2">
-<h3 id="_enable_cdi_for_your_java_environment">Enable CDI For Your Java Environment</h3>
-<div class="paragraph">
-<p>This module requires a CDI implementation to be available in the Java environment where your projects are deployed. Dependent on the Java environment you choose, some setup may be necessary as detailed at the <a href="cdiimp.html">Enable CDI For Your Java Environment</a> page.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_declare_container_control_module_dependencies">Declare Container Control Module Dependencies</h3>
-<div class="paragraph">
-<p>Add the Container Control module to the list of dependencies in the project <code>pom.xml</code> file using this code snippet:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><dependency></span>
- <span class="tag"><groupId></span>org.apache.deltaspike.cdictrl<span class="tag"></groupId></span>
- <span class="tag"><artifactId></span>deltaspike-cdictrl-api<span class="tag"></artifactId></span>
- <span class="tag"><version></span>${deltaspike.version}<span class="tag"></version></span>
- <span class="tag"><scope></span>compile<span class="tag"></scope></span>
-<span class="tag"></dependency></span></code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Or if you’re using Gradle, add these dependencies to your <code>build.gradle</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code> compile 'org.apache.deltaspike.cdictrl:deltaspike-cdictrl-api'</code></pre>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_start_the_cdi_container_from_your_project">Start the CDI Container from Your Project</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>To start a CDI container in your application, you must instantiate a <code>CdiContainer</code> object and call the <code>#boot</code> method. When <code>#boot</code> is called, the <code>CdiContainer</code> scans CDI-enabled
-archives for beans and CDI extensions. Before the application exits, <code>#shutdown</code> must be called to correctly destroy all beans. An example is given in the code snippet here.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainer</span>;
-<span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainerLoader</span>;
-
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MainApp</span> {
- <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
-
- CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
- cdiContainer.boot();
-
- <span class="comment">// You can use CDI here</span>
-
- cdiContainer.shutdown();
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Starting the container does not automatically start all CDI Contexts. Contexts must be started independently using the provided <code>ContextControl</code> class. An example of starting the Context for <code>@ApplicationScoped</code> beans is added to the code snippet here.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainer</span>;
-<span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainerLoader</span>;
-<span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.ContextControl</span>;
-<span class="keyword">import</span> <span class="include">javax.enterprise.context.ApplicationScoped</span>;
-
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MainApp</span> {
- <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
-
- CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
- cdiContainer.boot();
-
- <span class="comment">// Starting the application-context enables use of @ApplicationScoped beans</span>
- ContextControl contextControl = cdiContainer.getContextControl();
- contextControl.startContext(ApplicationScoped.class);
-
- <span class="comment">// You can use CDI here</span>
-
- cdiContainer.shutdown();
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>To resolve project beans, you can use the DeltaSpike <code>BeanProvider</code> class. Whether <code>EchoService</code> is a concrete implementation or just an interface depends on the application. In the case that it is an interface, the corresponding implementation is resolved. The resolved bean is a standard CDI bean and it can be used for all CDI concepts, such as <code>@Inject</code>, in the class without further uses of <code>BeanProvider</code>. An example of resolving the bean without qualifiers is given in the code snippet here.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">EchoService echoService = BeanProvider.getContextualReference(EchoService.class, <span class="predefined-constant">false</span>);</code></pre>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cdicontainer">CdiContainer</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The <code>CdiContainer</code> interface provides booting and shutdown of the CDI containers from deployed applications, with <code>CdiContainerLoader</code> a simple factory providing access to the underlying <code>CdiContainer</code> implementation.</p>
-</div>
-<div class="paragraph">
-<p>This is useful to Java SE6+ applications in which a standalone CDI implementation must be provided and booted and shutdown by the application. Booting and shutdown of the CDI container for Java EE and servlet containers is managed by the servlet container integration.</p>
-</div>
-<div class="paragraph">
-<p>For instructions and examples on using this feature in your projects, see <a href="cdiimp.html#javase6">Enable CDI For Your Java Environment: Java SE6+</a>.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_contextcontrol_usage">ContextControl Usage</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The <code>ContextControl</code> interface provides life-cycle control of the CDI container built-in contexts. This includes starting and stoping built-in standard contexts like <code>@RequestScoped</code>, <code>@ConversationScoped</code>, and <code>@SessionScoped</code>. It is provided as an <code>@Dependent</code> bean and can be injected in the classic CDI way. This feature can be used and is helpful in all Java environments, including Java SE, as illustrated here.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_procedure_for_building_an_uber_jar">Procedure for building an uber jar</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Uber jar or executable jar can created by using the maven shade plugin. Some things you needs to be aware of when you use it.</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Multiple <code>beans.xml</code> and <code>javax.enterprise.inject.spi.Extension</code> files needs to be merged into the final jar using a transformer.</p>
-</li>
-</ul>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre><transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/></pre>
-</div>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>The <em>asm:asm:3.3.1</em> transitive dependency of OpenWebBeans isn’t properly included in the Uber jar. Add it as a project dependency if you use OWB. (Only needed for OWB 1.1.8 !)</p>
-</li>
-<li>
-<p>Some frameworks, like logging frameworks, aren’t CDI compatible. So you need to exclude them from scanning. Use for example the <code>scan</code> feature of Weld to define which packages needs to be excluded.</p>
-</li>
-</ul>
-</div>
-<div class="sect2">
-<h3 id="_restart_the_requestcontext_in_unit_tests">Restart the RequestContext in Unit Tests</h3>
-<div class="paragraph">
-<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>
-</div>
-<div class="listingblock">
-<div class="title">Using ContextControl to Detach Entities</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Test</span>
-<span class="directive">public</span> <span class="type">void</span> testMyBusinessLogic()
-{
- doSomeJpaStuff()
- MyEntity me = em.find(...);
-
- ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
-
- <span class="comment">//stop the RequestContext to dispose of the @RequestScoped EntityManager</span>
- ctxCtrl.stopContext(RequestScoped.class);
-
- <span class="comment">//immediately restart the context again</span>
- ctxCtrl.startContext(RequestScoped.class);
-
- <span class="comment">//the entity 'em' is now in a detached state!</span>
- doSomeStuffWithTheDetachedEntity(em);
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_attach_a_requestcontext_to_a_new_thread_in_ee">Attach a RequestContext to a New Thread in EE</h3>
-<div class="paragraph">
-<p>Accessing the <code>@RequestScoped</code> bean in a new thread will result in a
-<code>ContextNotActiveException</code>. The RequestContext 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 for example a Quartz Job.</p>
-</div>
-<div class="listingblock">
-<div class="title">Using ContextControl to Control the RequestContext for a Quartz-Job</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">CdiJob</span> <span class="directive">implements</span> org.quartz.Job
-{
- <span class="directive">public</span> <span class="type">void</span> execute(JobExecutionContext context) <span class="directive">throws</span> JobExecutionException
- {
- ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
-
- <span class="comment">//this will implicitly bind a new RequestContext to the current thread</span>
- ctxCtrl.startContext(RequestScoped.class);
-
- <span class="keyword">try</span>
- {
- doYourWork();
- }
- <span class="keyword">finally</span>
- {
- <span class="comment">//stop the RequestContext to ensure that all request-scoped beans get cleaned up.</span>
- ctxCtrl.stopContext(RequestScoped.class);
- }
- }
-}</code></pre>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_embedded_servlet_support">Embedded Servlet Support</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>From DeltaSpike 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>
-</div>
-<div class="paragraph">
-<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>
-</div>
-<div class="paragraph">
-<p>The main use case 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>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
-cdiContainer.boot();
-cdiContainer.getContextControl().startContexts();</code></pre>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_jetty">Jetty</h3>
-<div class="paragraph">
-<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>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">Server server = <span class="keyword">new</span> Server(port);
-ServletContextHandler context = <span class="keyword">new</span> ServletContextHandler(ServletContextHandler.SESSIONS);
-context.setContextPath(<span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>);
-server.setHandler(context);
-
-context.addEventListener(<span class="keyword">new</span> CdiServletRequestListener());
-context.addServlet(<span class="keyword">new</span> ServletHolder(<span class="keyword">new</span> YourServlet()),<span class="string"><span class="delimiter">"</span><span class="content">/*</span><span class="delimiter">"</span></span>);
-
-server.start();</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_undertow">Undertow</h3>
-<div class="paragraph">
-<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>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">ServletInfo servletInfo = Servlets.servlet(<span class="string"><span class="delimiter">"</span><span class="content">YourServletName</span><span class="delimiter">"</span></span>, YourServlet.class).setAsyncSupported(<span class="predefined-constant">true</span>)
- .setLoadOnStartup(<span class="integer">1</span>).addMapping(<span class="string"><span class="delimiter">"</span><span class="content">/*</span><span class="delimiter">"</span></span>);
-ListenerInfo listenerInfo = Servlets.listener(CdiServletRequestListener.class);
-DeploymentInfo di = <span class="keyword">new</span> DeploymentInfo()
- .addListener(listenerInfo)
- .setContextPath(<span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>)
- .addServlet(servletInfo).setDeploymentName(<span class="string"><span class="delimiter">"</span><span class="content">CdiSEServlet</span><span class="delimiter">"</span></span>)
- .setClassLoader(<span class="predefined-type">ClassLoader</span>.getSystemClassLoader());
-DeploymentManager deploymentManager = Servlets.defaultContainer().addDeployment(di);
-deploymentManager.deploy();
-Undertow server = Undertow.builder()
- .addHttpListener(port, <span class="string"><span class="delimiter">"</span><span class="content">localhost</span><span class="delimiter">"</span></span>)
- .setHandler(deploymentManager.start())
- .build();
-server.start();</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_tomcat">Tomcat</h3>
-<div class="paragraph">
-<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>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">Tomcat tomcat = <span class="keyword">new</span> Tomcat();
-tomcat.setPort(port);
-<span class="predefined-type">File</span> base = <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">...</span><span class="delimiter">"</span></span>);
-<span class="predefined-type">Context</span> ctx = tomcat.addContext(<span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>,base.getAbsolutePath());
-StandardContext standardContext = (StandardContext)ctx;
-standardContext.addApplicationListener(CdiServletContextListener.class.getName());
-Wrapper wrapper = Tomcat.addServlet(ctx,<span class="string"><span class="delimiter">"</span><span class="content">YourServlet</span><span class="delimiter">"</span></span>,YourServlet.class.getName());
-wrapper.addMapping(<span class="string"><span class="delimiter">"</span><span class="content">/*</span><span class="delimiter">"</span></span>);
-tomcat.start();</code></pre>
-</div>
-</div>
-</div>
-</div>
-</div>
- </div>
- </div>
-
-
- <div class="span4">
- <div id="toc">
- <div class="moduledeps">
- <ul class="toc-like nav nav-list">
-
-
-
- </ul>
- </div>
- </div>
-
- <div class="fallback-toc">
- <ul class="sectlevel1">
-<li><a href="#_overview">Overview</a></li>
-<li><a href="#_project_setup">Project Setup</a>
-<ul class="sectlevel2">
-<li><a href="#_enable_cdi_for_your_java_environment">Enable CDI For Your Java Environment</a></li>
-<li><a href="#_declare_container_control_module_dependencies">Declare Container Control Module Dependencies</a></li>
-</ul>
-</li>
-<li><a href="#_start_the_cdi_container_from_your_project">Start the CDI Container from Your Project</a></li>
-<li><a href="#_cdicontainer">CdiContainer</a></li>
-<li><a href="#_contextcontrol_usage">ContextControl Usage</a></li>
-<li><a href="#_procedure_for_building_an_uber_jar">Procedure for building an uber jar</a>
-<ul class="sectlevel2">
-<li><a href="#_restart_the_requestcontext_in_unit_tests">Restart the RequestContext in Unit Tests</a></li>
-<li><a href="#_attach_a_requestcontext_to_a_new_thread_in_ee">Attach a RequestContext to a New Thread in EE</a></li>
-</ul>
-</li>
-<li><a href="#_embedded_servlet_support">Embedded Servlet Support</a>
-<ul class="sectlevel2">
-<li><a href="#_jetty">Jetty</a></li>
-<li><a href="#_undertow">Undertow</a></li>
-<li><a href="#_tomcat">Tomcat</a></li>
-</ul>
-</li>
-</ul>
- </div>
-
- </div>
-
-
- </div>
- <div class="row">
- <hr>
- <footer>
- <p>Copyright © 2011-2016 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>
-</div>
-
-</body>
+<!DOCTYPE html>
+<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">
+ <!-- No caching headers -->
+ <meta http-equiv="cache-control" content="no-cache"/>
+ <meta http-equiv="pragma" content="no-cache"/>
+ <meta http-equiv="expires" content="-1"/>
+
+ <title>Container Control Module</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
+ "License"); 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
+ "AS IS" 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="https://deltaspike.apache.org/resources/css/bootstrap.css" rel="stylesheet">
+ <link href="https://deltaspike.apache.org/resources/css/bootstrap-responsive.css" rel="stylesheet">
+ <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.1.0/css/font-awesome.min.css" rel="stylesheet">
+
+
+
+
+ <!-- Tocify - nice dynamic autoscrolling TOC -->
+ <link href="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/stylesheets/jquery.tocify.min.css" rel="stylesheet">
+ <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/javascripts/jquery.tocify.min.js"></script>
+
+
+ <script type="text/javascript">
+ $(function () {
+ $("#toc").tocify({
+ scrollTo: 50,
+ extendPage: true,
+ context: "#doc-content",
+ selectors: "h2,h3,h4,h5"
+ });
+ $(".fallback-toc").hide();
+ });
+ </script>
+
+
+ <style type="text/css">
+ /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
+/*pre.CodeRay {background-color:#f7f7f8;}*/
+.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
+.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
+.CodeRay .line-numbers strong{font-weight: normal}
+table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
+table.CodeRay td{vertical-align: top}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
+table.CodeRay td.code{padding:0 0 0 .5em}
+table.CodeRay td.code>pre{padding:0}
+.CodeRay .debug{color:#fff !important;background:#000080 !important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:#000080}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:#008080}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#00}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:#008080}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:#008080}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
+
+ body {
+ padding-top: 60px;
+ padding-bottom: 40px;
+ }
+
+ .toc-like {
+ border-radius: 6px;
+ border: 1px solid #ccc;
+ }
+
+ .toc-like li {
+ line-height: 30px;
+ text-indent: 10px;
+ }
+
+ .toc-like li.custom-toc-header {
+ font-weight: bold;
+ background: #666;
+ color: white;
+ cursor: initial !important;
+ padding: 5px;
+ }
+
+ .toc-like li.custom-toc-header a {
+ color: white;
+ font-style: normal;
+ text-shadow: none;
+ padding: 0;
+ }
+
+ .toc-like li.custom-toc-header:hover a {
+ background: #666;
+ }
+
+ .page-title {
+ text-align: left;
+ }
+
+ #doc-content h2,
+ #doc-content h3,
+ #doc-content h4,
+ #doc-content h5,
+ #doc-content h6 {
+ padding-top: 0;
+ margin-top: 25px;
+ margin-bottom: 10px;
+ line-height: 1.4em;
+ }
+
+ #doc-content h2 {
+ border-bottom: 1px solid lightgrey;
+ }
+
+
+ </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><a href="../index.html">Home</a></li>
+ <li class="active"><a href="../documentation">Documentation</a></li>
+ <li ><a href="../javadoc.html">Javadoc</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>
+ </ul>
+ </div>
+ <!--/.nav-collapse -->
+ <form id="search-form" action="https://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-fluid">
+
+
+
+ <div class="span8">
+ <div class="page-title">
+ <h1>Container Control Module</h1>
+ </div>
+
+ <div id="doc-content">
+ <div class="sect1">
+<h2 id="_overview">Overview</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The Container Control module provides CDI container booting and shutdown, crucial for CDI use in Java SE6+ environments, and associated context lifecycle management. The module abstracts individual CDI container implementations, ensuring projects are container-independent.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_project_setup">Project Setup</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <a href="configure.html">Configure DeltaSpike in Your Projects</a>. For Maven-independent projects, see <a href="configure.html#config-maven-indep">Configure DeltaSpike in Maven-independent Projects</a>.</p>
+</div>
+<div class="sect2">
+<h3 id="_enable_cdi_for_your_java_environment">Enable CDI For Your Java Environment</h3>
+<div class="paragraph">
+<p>This module requires a CDI implementation to be available in the Java environment where your projects are deployed. Dependent on the Java environment you choose, some setup may be necessary as detailed at the <a href="cdiimp.html">Enable CDI For Your Java Environment</a> page.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_declare_container_control_module_dependencies">Declare Container Control Module Dependencies</h3>
+<div class="paragraph">
+<p>Add the Container Control module to the list of dependencies in the project <code>pom.xml</code> file using this code snippet:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><dependency></span>
+ <span class="tag"><groupId></span>org.apache.deltaspike.cdictrl<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>deltaspike-cdictrl-api<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>${deltaspike.version}<span class="tag"></version></span>
+ <span class="tag"><scope></span>compile<span class="tag"></scope></span>
+<span class="tag"></dependency></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Or if you’re using Gradle, add these dependencies to your <code>build.gradle</code>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code> compile 'org.apache.deltaspike.cdictrl:deltaspike-cdictrl-api'</code></pre>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_start_the_cdi_container_from_your_project">Start the CDI Container from Your Project</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>To start a CDI container in your application, you must instantiate a <code>CdiContainer</code> object and call the <code>#boot</code> method. When <code>#boot</code> is called, the <code>CdiContainer</code> scans CDI-enabled
+archives for beans and CDI extensions. Before the application exits, <code>#shutdown</code> must be called to correctly destroy all beans. An example is given in the code snippet here.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainer</span>;
+<span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainerLoader</span>;
+
+<span class="directive">public</span> <span class="type">class</span> <span class="class">MainApp</span> {
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
+
+ CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
+ cdiContainer.boot();
+
+ <span class="comment">// You can use CDI here</span>
+
+ cdiContainer.shutdown();
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Starting the container does not automatically start all CDI Contexts. Contexts must be started independently using the provided <code>ContextControl</code> class. An example of starting the Context for <code>@ApplicationScoped</code> beans is added to the code snippet here.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainer</span>;
+<span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.CdiContainerLoader</span>;
+<span class="keyword">import</span> <span class="include">org.apache.deltaspike.cdise.api.ContextControl</span>;
+<span class="keyword">import</span> <span class="include">javax.enterprise.context.ApplicationScoped</span>;
+
+<span class="directive">public</span> <span class="type">class</span> <span class="class">MainApp</span> {
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
+
+ CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
+ cdiContainer.boot();
+
+ <span class="comment">// Starting the application-context enables use of @ApplicationScoped beans</span>
+ ContextControl contextControl = cdiContainer.getContextControl();
+ contextControl.startContext(ApplicationScoped.class);
+
+ <span class="comment">// You can use CDI here</span>
+
+ cdiContainer.shutdown();
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>To resolve project beans, you can use the DeltaSpike <code>BeanProvider</code> class. Whether <code>EchoService</code> is a concrete implementation or just an interface depends on the application. In the case that it is an interface, the corresponding implementation is resolved. The resolved bean is a standard CDI bean and it can be used for all CDI concepts, such as <code>@Inject</code>, in the class without further uses of <code>BeanProvider</code>. An example of resolving the bean without qualifiers is given in the code snippet here.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">EchoService echoService = BeanProvider.getContextualReference(EchoService.class, <span class="predefined-constant">false</span>);</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cdicontainer">CdiContainer</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The <code>CdiContainer</code> interface provides booting and shutdown of the CDI containers from deployed applications, with <code>CdiContainerLoader</code> a simple factory providing access to the underlying <code>CdiContainer</code> implementation.</p>
+</div>
+<div class="paragraph">
+<p>This is useful to Java SE6+ applications in which a standalone CDI implementation must be provided and booted and shutdown by the application. Booting and shutdown of the CDI container for Java EE and servlet containers is managed by the servlet container integration.</p>
+</div>
+<div class="paragraph">
+<p>For instructions and examples on using this feature in your projects, see <a href="cdiimp.html#javase6">Enable CDI For Your Java Environment: Java SE6+</a>.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_contextcontrol_usage">ContextControl Usage</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The <code>ContextControl</code> interface provides life-cycle control of the CDI container built-in contexts. This includes starting and stoping built-in standard contexts like <code>@RequestScoped</code>, <code>@ConversationScoped</code>, and <code>@SessionScoped</code>. It is provided as an <code>@Dependent</code> bean and can be injected in the classic CDI way. This feature can be used and is helpful in all Java environments, including Java SE, as illustrated here.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_procedure_for_building_an_uber_jar">Procedure for building an uber jar</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Uber jar or executable jar can created by using the maven shade plugin. Some things you needs to be aware of when you use it.</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Multiple <code>beans.xml</code> and <code>javax.enterprise.inject.spi.Extension</code> files needs to be merged into the final jar using a transformer.</p>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre><transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>The <em>asm:asm:3.3.1</em> transitive dependency of OpenWebBeans isn’t properly included in the Uber jar. Add it as a project dependency if you use OWB. (Only needed for OWB 1.1.8 !)</p>
+</li>
+<li>
+<p>Some frameworks, like logging frameworks, aren’t CDI compatible. So you need to exclude them from scanning. Use for example the <code>scan</code> feature of Weld to define which packages needs to be excluded.</p>
+</li>
+</ul>
+</div>
+<div class="sect2">
+<h3 id="_restart_the_requestcontext_in_unit_tests">Restart the RequestContext in Unit Tests</h3>
+<div class="paragraph">
+<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>
+</div>
+<div class="listingblock">
+<div class="title">Using ContextControl to Detach Entities</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Test</span>
+<span class="directive">public</span> <span class="type">void</span> testMyBusinessLogic()
+{
+ doSomeJpaStuff()
+ MyEntity me = em.find(...);
+
+ ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+ <span class="comment">//stop the RequestContext to dispose of the @RequestScoped EntityManager</span>
+ ctxCtrl.stopContext(RequestScoped.class);
+
+ <span class="comment">//immediately restart the context again</span>
+ ctxCtrl.startContext(RequestScoped.class);
+
+ <span class="comment">//the entity 'em' is now in a detached state!</span>
+ doSomeStuffWithTheDetachedEntity(em);
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_attach_a_requestcontext_to_a_new_thread_in_ee">Attach a RequestContext to a New Thread in EE</h3>
+<div class="paragraph">
+<p>Accessing the <code>@RequestScoped</code> bean in a new thread will result in a
+<code>ContextNotActiveException</code>. The RequestContext 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 for example a Quartz Job.</p>
+</div>
+<div class="listingblock">
+<div class="title">Using ContextControl to Control the RequestContext for a Quartz-Job</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">CdiJob</span> <span class="directive">implements</span> org.quartz.Job
+{
+ <span class="directive">public</span> <span class="type">void</span> execute(JobExecutionContext context) <span class="directive">throws</span> JobExecutionException
+ {
+ ContextControl ctxCtrl = BeanProvider.getContextualReference(ContextControl.class);
+
+ <span class="comment">//this will implicitly bind a new RequestContext to the current thread</span>
+ ctxCtrl.startContext(RequestScoped.class);
+
+ <span class="keyword">try</span>
+ {
+ doYourWork();
+ }
+ <span class="keyword">finally</span>
+ {
+ <span class="comment">//stop the RequestContext to ensure that all request-scoped beans get cleaned up.</span>
+ ctxCtrl.stopContext(RequestScoped.class);
+ }
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_embedded_servlet_support">Embedded Servlet Support</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>From DeltaSpike 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>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>The main use case 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>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
+cdiContainer.boot();
+cdiContainer.getContextControl().startContexts();</code></pre>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_jetty">Jetty</h3>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">Server server = <span class="keyword">new</span> Server(port);
+ServletContextHandler context = <span class="keyword">new</span> ServletContextHandler(ServletContextHandler.SESSIONS);
+context.setContextPath(<span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>);
+server.setHandler(context);
+
+context.addEventListener(<span class="keyword">new</span> CdiServletRequestListener());
+context.addServlet(<span class="keyword">new</span> ServletHolder(<span class="keyword">new</span> YourServlet()),<span class="string"><span class="delimiter">"</span><span class="content">/*</span><span class="delimiter">"</span></span>);
+
+server.start();</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_undertow">Undertow</h3>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">ServletInfo servletInfo = Servlets.servlet(<span class="string"><span class="delimiter">"</span><span class="content">YourServletName</span><span class="delimiter">"</span></span>, YourServlet.class).setAsyncSupported(<span class="predefined-constant">true</span>)
+ .setLoadOnStartup(<span class="integer">1</span>).addMapping(<span class="string"><span class="delimiter">"</span><span class="content">/*</span><span class="delimiter">"</span></span>);
+ListenerInfo listenerInfo = Servlets.listener(CdiServletRequestListener.class);
+DeploymentInfo di = <span class="keyword">new</span> DeploymentInfo()
+ .addListener(listenerInfo)
+ .setContextPath(<span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>)
+ .addServlet(servletInfo).setDeploymentName(<span class="string"><span class="delimiter">"</span><span class="content">CdiSEServlet</span><span class="delimiter">"</span></span>)
+ .setClassLoader(<span class="predefined-type">ClassLoader</span>.getSystemClassLoader());
+DeploymentManager deploymentManager = Servlets.defaultContainer().addDeployment(di);
+deploymentManager.deploy();
+Undertow server = Undertow.builder()
+ .addHttpListener(port, <span class="string"><span class="delimiter">"</span><span class="content">localhost</span><span class="delimiter">"</span></span>)
+ .setHandler(deploymentManager.start())
+ .build();
+server.start();</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_tomcat">Tomcat</h3>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">Tomcat tomcat = <span class="keyword">new</span> Tomcat();
+tomcat.setPort(port);
+<span class="predefined-type">File</span> base = <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">"</span><span class="content">...</span><span class="delimiter">"</span></span>);
+<span class="predefined-type">Context</span> ctx = tomcat.addContext(<span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>,base.getAbsolutePath());
+StandardContext standardContext = (StandardContext)ctx;
+standardContext.addApplicationListener(CdiServletContextListener.class.getName());
+Wrapper wrapper = Tomcat.addServlet(ctx,<span class="string"><span class="delimiter">"</span><span class="content">YourServlet</span><span class="delimiter">"</span></span>,YourServlet.class.getName());
+wrapper.addMapping(<span class="string"><span class="delimiter">"</span><span class="content">/*</span><span class="delimiter">"</span></span>);
+tomcat.start();</code></pre>
+</div>
+</div>
+</div>
+</div>
+</div>
+ </div>
+ </div>
+
+
+ <div class="span4">
+ <div id="toc">
+ <div class="moduledeps">
+ <ul class="toc-like nav nav-list">
+
+
+
+ </ul>
+ </div>
+ </div>
+
+ <div class="fallback-toc">
+ <ul class="sectlevel1">
+<li><a href="#_overview">Overview</a></li>
+<li><a href="#_project_setup">Project Setup</a>
+<ul class="sectlevel2">
+<li><a href="#_enable_cdi_for_your_java_environment">Enable CDI For Your Java Environment</a></li>
+<li><a href="#_declare_container_control_module_dependencies">Declare Container Control Module Dependencies</a></li>
+</ul>
+</li>
+<li><a href="#_start_the_cdi_container_from_your_project">Start the CDI Container from Your Project</a></li>
+<li><a href="#_cdicontainer">CdiContainer</a></li>
+<li><a href="#_contextcontrol_usage">ContextControl Usage</a></li>
+<li><a href="#_procedure_for_building_an_uber_jar">Procedure for building an uber jar</a>
+<ul class="sectlevel2">
+<li><a href="#_restart_the_requestcontext_in_unit_tests">Restart the RequestContext in Unit Tests</a></li>
+<li><a href="#_attach_a_requestcontext_to_a_new_thread_in_ee">Attach a RequestContext to a New Thread in EE</a></li>
+</ul>
+</li>
+<li><a href="#_embedded_servlet_support">Embedded Servlet Support</a>
+<ul class="sectlevel2">
+<li><a href="#_jetty">Jetty</a></li>
+<li><a href="#_undertow">Undertow</a></li>
+<li><a href="#_tomcat">Tomcat</a></li>
+</ul>
+</li>
+</ul>
+ </div>
+
+ </div>
+
+
+ </div>
+ <div class="row">
+ <hr>
+ <footer>
+ <p>Copyright © 2011-2016 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>
+</div>
+
+</body>
</html>
\ No newline at end of file