Title: Container & Control
Notice:    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.

[TOC]

***

# Introduction

There are basically two parts:

  - The `CdiContainer` interface allows to boot and shutdown the CDI container in SE applications.
  - The `ContextControl` interface allows to control the life-cycle of the built-in contexts of the CDI container.

## CdiContainer
You can use the `CdiContainerLoader` as a simple factory to gain access to the underlying `CdiContainer` 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.
    

    :::java
    // this will give you a CdiContainer for Weld or OWB, depending on the jar you added
    CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();

    // now we gonna boot the CDI container. This will trigger the classpath scan, etc
    cdiContainer.boot();

    // and finally we like to start all built-in contexts
    cdiContainer.getContextControl().startContexts();

    // now we can use CDI in our SE application.
    // And there is not a single line of OWB or Weld specific code in your project!

    // finally we gonna stop the container
    cdiContainer.shutdown();

## 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:

    :::java
    @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:

    :::java
    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);
            }
        }
    }

## Embedded Servlet Support

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.

The two main listeners are `CdiServletRequestListener` and `CdiServletContextListener`.  `CdiServletRequestListener` is responsible for starting a `RequestContext` on each incoming request.  In most containers this is all you need.  For Tomcat specifically, you need to use `CdiServletContextListener` which registers the `CdiServletRequestListener`.

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:

    :::java
    CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
    cdiContainer.boot();
    cdiContainer.getContextControl().startContexts();

### Jetty
For Jetty, you need to add an `EventListener` which will be your `CdiServletRequestListener`.  The object must be instantiated.  This must be done before the server is started.

    :::java
    Server server = new Server(port);
    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);

    context.addEventListener(new CdiServletRequestListener());
    context.addServlet(new ServletHolder(new YourServlet()),"/*");

    server.start();

### Undertow
For Undertow, you register the `CdiServletRequestListener` via `ListenerInfo` by passing in the class to their builders.  Then you add the `ListenerInfo` to your deployment before starting.

    :::java
    ServletInfo servletInfo = Servlets.servlet("YourServletName", YourServlet.class).setAsyncSupported(true)
        .setLoadOnStartup(1).addMapping("/*");
    ListenerInfo listenerInfo = Servlets.listener(CdiServletRequestListener.class);
    DeploymentInfo di = new DeploymentInfo()
            .addListener(listenerInfo)
            .setContextPath("/")
            .addServlet(servletInfo).setDeploymentName("CdiSEServlet")
            .setClassLoader(ClassLoader.getSystemClassLoader());
    DeploymentManager deploymentManager = Servlets.defaultContainer().addDeployment(di);
    deploymentManager.deploy();
    Undertow server = Undertow.builder()
            .addHttpListener(port, "localhost")
            .setHandler(deploymentManager.start())
            .build();
    server.start();

### Tomcat
For Tomcat, you need to register the `CdiServletContextListener` instead of the `CdiServletRequestListener`.  It is added as an `ApplicationListener` by passing in the class name as a `String`.

    :::java
    Tomcat tomcat = new Tomcat();
    tomcat.setPort(port);
    File base = new File("...");
    Context ctx = tomcat.addContext("/",base.getAbsolutePath());
    StandardContext standardContext = (StandardContext)ctx;
    standardContext.addApplicationListener(CdiServletContextListener.class.getName());
    Wrapper wrapper = Tomcat.addServlet(ctx,"YourServlet",YourServlet.class.getName());
    wrapper.addMapping("/*");
    tomcat.start();