Configuring Tomcat 7 and 8 to Use CDI

How to set up Apache Tomcat to use CDI (via JBoss Weld) in order to run JSF 2.2 faces flow applications.


This tutorial gives details on the configuration needed to add CDI support to Web apps in Tomcat. It was originally part of the JSF 2 tutorial series, but was moved here when it seemed more generally useful.

Background and Need

Most JSF 2.2 apps can easily run on servlet containers like Tomcat, Jetty or Resin with merely the addition of the JSF 2.2 JAR file. However, faces flow and flow-scoped beans fundamentally depend on CDI, so require either a Java EE 7 server like Glassfish 4 or Firefly (aka JBoss) 8, or that you add CDI to the servlet container. This tutorial gives details for Tomcat, but the JBoss Weld documentation on which much of this tutorial was based also gives details for Jetty. Based on that, the instructions here can relatively easily be adapted for Jetty.

Detailed Configuration Steps

1. Download Weld

JBoss Weld is the reference implementation of CDI (Contexts and Dependency Injection for the Java EE Platform), which JSF 2.2 faces flow fundamentally depends upon. Download Weld at http://weld.cdi-spec.org/download/: go to "Binary Distribution" and select version 2.2 or later. Once you download and unzip the Weld distribution file, go to weld_install_dir/artifacts/weld/, and the only file you need is weld-servlet.jar.

2. Use context.xml to add CDI Support to Tomcat

As described in the Weld documentation, Tomcat has a read-only JNDI, Weld can't automatically bind the BeanManager extension SPI, and so you need context.xml entries to bind the BeanManager into JNDI. To do so, edit context.xml and add the following Resource entry within the main Context element:
<?xml version="1.0" encoding="UTF-8"?>
<Context>
   <!-- Existing entries left unchanged -->
   
   <Resource name="BeanManager"
      auth="Container"
      type="javax.enterprise.inject.spi.BeanManager"
      factory="org.jboss.weld.resources.ManagerObjectFactory"/>
</Context>
There are three places that context.xml file can go:

  • context.xml in the META-INF folder In the META-INF folder of the individual Web application. (This is WebContent/META-INF/ in Eclipse projects.) This is usually the best option for adding CDI support to a Web app, since it does not change the defaults for other Web apps.
  • Under the Servers folder in Eclipse. If running Tomcat from within Eclipse, context.xml can also be context.xml in the Eclipse Servers folder found in your Eclipse workspace in Servers/Tomcat v7.0 Server/ or Servers/Tomcat v8.0 Server/. This provides defaults for all apps in your workspace that are deployed with this server. A context.xml in the META-INF of the Web app overrides the defaults here.
  • In the conf folder. If running Tomcat from the desktop, context.xml also goes in tomcat-install-dir/conf/. Again, this provides defaults for all apps in that are deployed with this server, and as above, a context.xml in the META-INF of the app overrides the defaults here.

3. Put weld-servlet.jar in Your App

weld-servlet.jar in WEB-INF/lib Go to the folder where you unzipped the Weld distribution file, go to weld_install_dir/artifacts/weld/, copy weld-servlet.jar, and put it in the WEB-INF/lib folder of your Web application. Note that this step is illegal in an app that will be deployed to Glassfish 4 or another full Java EE 7 server, so your app is not 100% portable between Tomcat and a Java EE 7 app server. All the JSF code, of course, is completely portable, however.

4. Add a resource-env-ref to web.xml

Make CDI available by adding a resource-env-ref entry to the bottom of WEB-INF/web.xml as follows:
<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
  <!-- Existing entries left unchanged -->

  <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>
</web-app>

Sample Files

Rather than creating all of the files yourself, you can use or adapt some of mine.

  • context.xml. A context.xml, configured for CDI as described above.
  • weld-servlet.jar. Taken from weld 2.2.0.
  • web.xml. A Web app deployment descriptor, configured for both JSF and CDI.
  • flows-tomcat.zip. A sample app that uses JSF 2.2 faces flow, configured to work in Tomcat 7 or 8 via the instructions above. Taken from the faces flow section of the JSF 2 tutorial. This Eclipse project contains all of the files (context.xml, weld-servlet.jar, web.xml) described earlier, and should run unchanged on Tomcat.

More Information

Java

JSF (JavaServer Faces)

Servlets & JSP
Ajax, GWT, & JavaScript

Spring, Hibernate, & JPA

Struts