Weld SiteCommunity Documentation

Chapter 18. Application servers and environments supported by Weld

18.1. Using Weld with WildFly
18.2. GlassFish
18.3. Servlet containers (such as Tomcat or Jetty)
18.3.1. Tomcat
18.3.2. Jetty
18.3.3. Undertow
18.3.4. WildFly Web
18.3.5. Bean Archive Isolation
18.3.6. Implicit Bean Archive Support
18.3.7. Servlet Container Detection
18.4. Java SE
18.4.1. CDI SE Module
18.4.2. Bootstrapping CDI SE
18.4.3. Request Context
18.4.4. Thread Context
18.4.5. Setting the Classpath
18.4.6. Bean Archive Isolation
18.4.7. Implicit Bean Archive Support
18.5. Weld SE and Weld Servlet cooperation
18.6. OSGi

WildFly 8 and newer come with pre-configured Weld. There is no configuration needed to use Weld (or CDI for that matter). You may still want to fine-tune Weld with additional configuration settings.

Weld is also built into GlassFish from V3 onwards. Since GlassFish V3 is the Java EE reference implementation, it supports all features of CDI. What better way for GlassFish to support these features than to use Weld, the CDI reference implementation? Just package up your CDI application and deploy.

While CDI does not require support for servlet environments, Weld can be used in a servlet container, such as Tomcat or Jetty.

Weld can be used as a library in an web application that is deployed to a Servlet container. You should add the weld-servlet-core as a dependency to your project:


<dependency>
    <groupId>org.jboss.weld.servlet</groupId>
    <artifactId>weld-servlet-core</artifactId>
    <version>2.4.5.Final</version>
</dependency>

All the necessary dependencies (CDI API, Weld core) will be fetched transitively.

Alternatively, there is a shaded version with all the dependencies in a single jar file which is available as:


<dependency>
    <groupId>org.jboss.weld.servlet</groupId>
    <artifactId>weld-servlet</artifactId>
    <version>2.4.5.Final</version>
</dependency>

In general, weld-servlet uses ServletContainerInitializer mechanism to hook into the life cycle of Servlet 3.x compatible containers.

In special cases when your Servlet container does not support ServletContainerInitializer or you need more control over the ordering of listeners (e.g. move Weld’s listener) to the beginning of the list so that CDI context are active during invocation of other listeners) you can register Weld’s listener manually in the WEB-INF/web.xml file of the application:


<listener>
   <listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
</listener>

Note

There is quite a special use-case where one more special component must be involved. If you want the session context to be active during HttpSessionListener.sessionDestroyed() invocation when the session times out or when all the sessions are destroyed because the deployment is being removed then org.jboss.weld.servlet.WeldTerminalListener must be specified as the last one in your web.xml. This listener activates the session context before other listeners are invoked (note that the listeners are notified in reverse order when a session is being destroyed).

When working with multiple deployments in servlet environment, Weld Servlet allows to define context identifier per application deployed. Each different context identifier will create a new Weld container instance. If not specified, Weld falls back to the default value - STATIC_INSTANCE. While using custom identifiers is neither required nor commonly used, it certainly has some use-cases. For instance managing several deployments with Arquillian Tomcat container. Setting the identifier is as simple as adding one context parameter into web.xml:


<context-param>
   <param-name>WELD_CONTEXT_ID_KEY</param-name>
   <param-value>customValue</param-value>
</context-param>

Tomcat 7 and 8 are supported. Context activation/deactivation and dependency injection into Servlets and Filters works out of the box. Injection into Servlet listeners works on Tomcat 7.0.50 and newer.

Jetty 7, 8 and 9 are supported. Context activation/deactivation and dependency injection into Servlets and Filters works out of the box. Injection into Servlet listeners works on Jetty 9.1.1 and newer.

No further configuration is needed when starting Jetty as an embedded webapp server from within another Java program. However, if you’re using a Jetty standalone instance one more configuration step is required.

The reason is that since Jetty 8 some internal classes are not visible from the web application. See also Setting Server Classes. Therefore, we have to tell Jetty not to hide the system classes which Weld integration code is using. Unfortunately, it’s not so simple. The only workaround is to use a Jetty Deployable Descriptor XML File (this is a Jetty 9 feature, in Jetty 8 a similar feature is incorporated - ContextProvider). For instance, if there is an application archive named weld-numberguess.war deployed in the webapps directory, an XML descriptor named weld-numberguess.xml should be created in the same directory (the file should have the same base name as the war - see alse the scanning rules described in Jetty docs):


<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/weld-numberguess</Set>
  <Set name="war"><Property name="jetty.webapps" default="."/>/weld-numberguess.war</Set>
  <Call name="prependServerClass">
    <Arg>-org.eclipse.jetty.server.handler.ContextHandler</Arg>
  </Call>
  <Call name="prependServerClass">
    <Arg>-org.eclipse.jetty.servlet.FilterHolder</Arg>
  </Call>
  <Call name="prependServerClass">
    <Arg>-org.eclipse.jetty.servlet.ServletContextHandler</Arg>
  </Call>
  <Call name="prependServerClass">
    <Arg>-org.eclipse.jetty.servlet.ServletHolder</Arg>
  </Call>
</Configure>

Tip

Jetty distributions (from version 9.2.4) contain a dedicated CDI/Weld module which allows to deploy a CDI application without bundling the Weld Servlet integration code.

To bind the BeanManager into JNDI, you should either populate WEB-INF/jetty-env.xml with the following contents:


<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN"
   "http://www.eclipse.org/jetty/configure.dtd">

<Configure id="webAppCtx" class="org.eclipse.jetty.webapp.WebAppContext">
    <New id="BeanManager" class="org.eclipse.jetty.plus.jndi.Resource">
        <Arg> <Ref id="webAppCtx"/> </Arg>
        <Arg>BeanManager</Arg>
        <Arg>
            <New class="javax.naming.Reference">
                <Arg>javax.enterprise.inject.spi.BeanManager</Arg>
                <Arg>org.jboss.weld.resources.ManagerObjectFactory</Arg>
                <Arg/>
            </New>
        </Arg>
    </New>
</Configure>

Or you can configure a special Servlet listener to bind the BeanManager automatically:


<listener>
   <listener-class>org.jboss.weld.environment.servlet.BeanManagerResourceBindingListener</listener-class>
</listener>

Just like in Tomcat, you need to make the BeanManager available to your deployment by adding this to the bottom of web.xml:


<resource-env-ref>
   <resource-env-ref-name>BeanManager</resource-env-ref-name>
   <resource-env-ref-type>
      javax.enterprise.inject.spi.BeanManager
   </resource-env-ref-type>
</resource-env-ref>

Jetty only allows you to bind entries to java:comp/env, so the BeanManager will be available at java:comp/env/BeanManager.

Weld supports context activation/deactivation and dependency injection into Servlets when running on Undertow. Injection into Filters and Servlet listeners is not currently supported. Weld’s listener needs to be registered programmatically:

public class Main {


    public static void main(String[] args) throws ServletException {
        DeploymentInfo servletBuilder = Servlets.deployment()
                .setClassLoader(Main.class.getClassLoader())
                .setResourceManager(new ClassPathResourceManager(Main.class.getClassLoader()))
                .setContextPath("/")
                .setDeploymentName("test.war")
                .addServlet(Servlets.servlet("hello", HelloWorldServlet.class).addMapping("/*"))
                .addListener(Servlets.listener(Listener.class)); 
1
        DeploymentManager manager = Servlets.defaultContainer().addDeployment(servletBuilder);
        manager.deploy();
        HttpHandler servletHandler = manager.start();
        PathHandler path = Handlers.path(Handlers.redirect("/")).addPrefixPath("/", servletHandler);
        Undertow server = Undertow.builder().addHttpListener(8080, "localhost").setHandler(path).build();
        server.start();
    }
    public static class HelloWorldServlet extends HttpServlet {
        @Inject BeanManager manager;
        protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
            resp.setContentType("text/plain");
            resp.getWriter().append("Hello from " + manager);
        }
    }
}

1

Weld’s org.jboss.weld.environment.servlet.Listener registered programmatically:

CDI 1.1 introduced the bean discovery mode of annotated used for implicit bean archives (see also Section 15.6, “Packaging and deployment”). This mode may bring additional overhead during container bootstrap. Therefore, Weld Servlet supports the use of Jandex bytecode scanning library to speed up the scanning process. Simply put the jandex.jar on the classpath. It’s also possible to generate the Jandex index beforehand. If Jandex is not found on the classpath Weld will use the Java Reflection as a fallback.

In general, an implicit bean archive does not have to contain a beans.xml descriptor. However, such a bean archive is not supported by Weld Servlet, i.e. it’s excluded from discovery.

Note

The bean discovery mode of annotated is supported from version 2.2.5.Final. Previous versions processed implicit bean archives in the same way as explicit bean archives.

In addition to improved integration of the Enterprise Java stack, the "Contexts and Dependency Injection for the Java EE platform" specification also defines a state of the art typesafe, stateful dependency injection framework, which can prove useful in a wide range of application types. To help developers take advantage of this, Weld provides a simple means for being executed in the Java Standard Edition (SE) environment independently of any Java EE APIs.

When executing in the SE environment the following features of Weld are available:

EJB beans are not supported.

CDI SE applications can be bootstrapped in the following ways.

For added flexibility, CDI SE also comes with a bootstrap API which can be called from within your application in order to initialize CDI and obtain references to your application’s beans and events. The API consists of two classes: Weld and WeldContainer.

/** A builder used to bootsrap a Weld SE container. */

public class Weld
{
   /** Boots Weld and creates and returns a WeldContainer instance, through which
    * beans and events can be accesed. */
   public WeldContainer initialize() {...}
   /** Convenience method for shutting down all the containers initialized by a specific builder instance. */
   public void shutdown() {...}
}
/** Represents a Weld SE container. */

public class WeldContainer implements javax.enterprise.inject.Instance<Object>
{
   /** Provides access to all events within the application. */
   public Event<Object> event() {...}
   /** Provides direct access to the BeanManager. */
   public BeanManager getBeanManager() {...}
   /** Returns the identifier of the container */
   String getId() {...}
   /** Shuts down the container. */
   public void shutdown() {...}
   /** Returns the running container with the specified identifier or null if no such container exists */
   public static WeldContainer instance(String id) {...}
}

Here’s an example application main method which uses this API to bootsrap a Wedl SE container and call a business method of a bean MyApplicationBean.

import org.jboss.weld.environment.se.Weld;


public static void main(String[] args) {
   Weld weld = new Weld();
   WeldContainer container = weld.initialize();
   container.select(MyApplicationBean.class).get().callBusinessMethod();
   container.shutdown();
}

Alternatively the application could be started by firing a custom event which would then be observed by another simple bean. The following example fires MyEvent on startup.

org.jboss.weld.environment.se.Weld;


public static void main(String[] args) {
   Weld weld = new Weld();
   WeldContainer container = weld.initialize();
   container.event().select(MyEvent.class).fire( new MyEvent() );
   // When all observer methods are notified the container shuts down
   container.shutdown();
}

Because WeldContainer implements AutoCloseable, it can be used within a try-with-resources block. Should the execution get out of the code block, the Weld instance is shut down and all managed instances are safely destroyed. Here is an example using the above code but leaving out the shutdown() method:

org.jboss.weld.environment.se.Weld;


public static void main(String[] args) {
   Weld weld = new Weld();
   try (WeldContainer container = weld.initialize()) {
      container.select(MyApplicationBean.class).get().callBusinessMethod();
   }
}

In case of more complex scenarios, it might be handy to gain higher level of control over the bootstraping process. Using the builder, it is possible to disable automatic scanning and to explicitly select classes/packages which will be managed by Weld. Interceptors, decorators and extensions can be defined in the very same manner. Last but not least, builder can be used to set Weld-specific configuration. Following example demonstrates these features:

Weld weld = new Weld()

    .disableDiscovery()
    .packages(Main.class, Utils.class)
    .interceptors(TransactionalInterceptor.class)
    .property("org.jboss.weld.construction.relaxed", true);
try (WeldContainer container = weld.initialize()) {
    MyBean bean = container.select(MyBean.class).get();
    System.out.println(bean.computeResult());
}

Furthermore, it is also possible to create several independent Weld instances. Code snippet below shows how to achieve that:

Weld weld = new Weld()

    .disableDiscovery();
weld.containerId("one").beanClasses(MyBean.class).initialize();
weld.containerId("two").beanClasses(OtherBean.class).initialize();
MyBean bean = WeldContainer.instance("one").select(MyBean.class).get();
System.out.println(bean.computeResult());
// Shutdown the first container
WeldContainer.instance("one").shutdown();
// Shutdown all the containers initialized by the builder instance
weld.shutdown();

In contrast to Java EE applications, Java SE applications place no restrictions on developers regarding the creation and usage of threads. Therefore Weld SE provides a custom scope annotation, @ThreadScoped, and corresponding context implementation which can be used to bind bean instances to the current thread. It is intended to be used in scenarios where you might otherwise use ThreadLocal, and does in fact use ThreadLocal under the hood.

To use the @ThreadScoped annotation you need to enable the RunnableDecorator which listens for all executions of Runnable.run() and decorates them by setting up the thread context beforehand, bound to the current thread, and destroying the context afterwards.


<beans>
  <decorators>
     <class>org.jboss.weld.environment.se.threading.RunnableDecorator</class>
  </decorator>
</beans>

Another option how to use thread context is to enable it at class or method level by @ActivateThreadScope interceptor binding and related ActivateThreadScopeInterceptor.

public class Foo {


  @Inject
  MyThreadScopedBean bean;
  @ActivateThreadScope
  public void executeInThreadContext() {
    bean.ping()
  }
}

CDI 1.1 introduced the bean discovery mode of annotated used for implicit bean archives (see also Section 15.6, “Packaging and deployment”). This mode may bring additional overhead during container bootstrap. Therefore, Weld SE supports the use of Jandex bytecode scanning library to speed up the scanning process. Simply put the jandex.jar on the classpath. It’s also possible to generate the Jandex index beforehand. If Jandex is not found on the classpath Weld will use the Java Reflection as a fallback.

In general, an implicit bean archive does not have to contain a beans.xml descriptor. However, such a bean archive is not supported by default in Weld SE (i.e. it’s excluded from discovery). This behaviour can be changed by setting a system property org.jboss.weld.se.scan.classpath.entries to true or through the Weld.property() method - if set to true Weld scans the class path entries and implicit bean archives which don’t contain a beans.xml descriptor are also supported.

Note

The bean discovery mode of annotated is supported from version 2.2.0.Final. Previous versions processed implicit bean archives in the same way as explicit bean archives.

Sometimes it could be convenient to start Servlet container programmatically. In this case a cooperation with Weld SE might come handy. This cooperation is based on passing Weld, WeldContainer or BeanManager instance to ServletContextHandler (in case of Jetty). You can either set a context attribute or use org.jboss.weld.environment.servlet.Listener. Check following examples.

Adding WeldContainer instance as a context attribute:

        try (WeldContainer weld = new Weld().disableDiscovery().beanClasses(Cat.class).initialize()) {

              ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
              context.addEventListener(new Listener());
              context.setAttribute(Listener.CONTAINER_ATTRIBUTE_NAME, weld);
              Server server = new Server(8080);
              context.setContextPath("/");
              server.setHandler(context);
              context.addServlet(TestServlet.class, "/test");
              server.start();
        }

Adding BeanManager instance as a context attribute:

        Weld weld = new Weld();

        WeldContainer container = weld.initialize();
        Server server = new Server(8080);
        context.setContextPath("/");
        server.setHandler(context);
        context.addServlet(TestServlet.class, "/test");
        context.setAttribute(WeldServletLifecycle.BEAN_MANAGER_ATTRIBUTE_NAME, container.getBeanManager());
        server.start();

Adding Weld instance as event listener with usage of org.jboss.weld.environment.servlet.Listener:

        Weld builder = new Weld().disableDiscovery().beanClasses(Cat.class);

        ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
        context.addEventListener(Listener.using(builder));
        Server server = new Server(8080);
        context.setContextPath("/");
        server.setHandler(context);
        context.addServlet(TestServlet.class, "/test");
        server.start();

Weld supports OSGi environment through Pax CDI. For more information on using Weld in OSGi environment check Pax CDI documentation . In addition, Weld comes with a sample application called Paint which demonstrates how to use CDI with OSGi. Check examples/osgi/README.md for more information.