JBoss Weld CDI for Java Platform (2013)

Chapter 3. Deploying JBoss Weld

Now we will cover the installation of JBoss Weld into Java EE 6 and Servlet containers. All Java EE 6 containers will come with an implementation of CDI preinstalled, but there may be occasions in which we need to update the version of JBoss Weld that is installed within the container. As a Servlet container does not provide a CDI implementation, we will describe the process of installing JBoss Weld into popular Servlet containers.

For this chapter we will use the chapter3.war, built from the code of this chapter, to activate JBoss Weld in each container as a way of visualizing the version that has been installed in a container. It's not necessary to use chapter3.war, as we can use any WAR file that is CDI-enabled for our purposes.

To build chapter3.war for a nonServlet container environment, simply run:

mvn clean package

JBoss Weld distribution

For installing JBoss Weld into a Servlet container, or updating the version within a Java EE 6 container, we need to download the latest release of Weld 1.1.x from http://seamframework.org/Weld/Downloads. Once downloaded, extract the contents of the ZIP file to a local directory such as C:\Weld.

Note

At the time of publication the most recent release of JBoss Weld is 1.1.10.Final.

Taking a look at the contents of C:\Weld\weld-1.1.10.Final\artifacts\weld, we can see source and javadoc JARs for the following libraries:

· weld-api.jar: These are the extensions to the CDI API

· weld-core.jar: This is the JBoss Weld implementation of CDI

· weld-se.jar: This is the JAR for Java SE that contains all required classes from CDI and JBoss Weld

· weld-se-core.jar: This is the JBoss Weld support for Java SE, which is included within weld-se.jar

· weld-servlet.jar: This is the JAR for Servlet containers that contains all required classes from CDI and JBoss Weld

· weld-servlet-core.jar: This is the core implementation for JBoss Weld in a Servlet container, which is included within weld-servlet.jar

· weld-spi.jar: This is the service provider interface for containers integrating with JBoss Weld

JBoss AS

JBoss AS7 comes bundled with v1.1.5.Final of JBoss Weld as the default CDI implementation, so we have the choice of using this version with our CDI applications or deciding to upgrade to a more recent version, if available.

When we make the decision to upgrade JBoss Weld, we need to ensure that we are gaining an advantage by doing so, else we could possibly introduce issues into an otherwise stable application server. If our application experiences issues with JBoss Weld that have been resolved in a recent version, upgrading our application server to take advantage of those fixes is definitely a good decision.

If we don't already have it installed, download the latest release of JBoss AS7 from http://www.jboss.org/jbossas/downloads/ and extract the ZIP contents. We will refer to the location where the ZIP was extracted to as AS7_HOME.

Note

At the time of publication, the most recent binary available for JBoss AS7 is 7.1.1.Final.

With the use of a module system for JBoss AS7, it's very easy for us to upgrade the versions of modules that are installed for all parts of the application server to take advantage of that upgrade.

When we choose to upgrade JBoss Weld from the version within JBoss AS7 to the latest available, provided they are of the same minor version (that is 1.1.x) we can simply update the JAR for the core module as the API and SPI are still the same. The core module for JBoss Weld is located at AS7_HOME\modules\org\jboss\weld\core\main.

To update JBoss Weld, we do the following:

1. Copy weld-core.jar from C:\Weld\weld-1.1.10.Final\artifacts\weld and place it into AS7_HOME\modules\org\jboss\weld\core\main.

2. Rename weld-core.jar to weld-core-1.1.10.Final.jar.

3. Update module.xml so that <resource-root path=""> references the name of the JAR file from Step 2.

Note

It's not mandatory to perform Step 2, but it does make it quicker to see which version of JBoss Weld is installed in the future.

That's all there is to it! Now we deploy our chapter3.war to JBoss AS7, if it isn't already deployed, and start the server.

In the server console during startup we will see messages, like in the following screenshot, which shows that the version of JBoss Weld that was started for chapter3.war is 1.1.10.Final:

JBoss AS

By opening a browser and navigating to http://localhost:8080/chapter3/index.jsf, we can see the result of our simple CDI application as follows:

JBoss AS

Glassfish

Glassfish comes bundled with JBoss Weld 1.1.8.Final as the default CDI implementation. As with JBoss AS7, we have the choice of using the version that is there already or upgrading to the latest version.

If we don't already have Glassfish installed, download the latest release from http://glassfish.java.net/public/downloadsindex.html#top and either run the installation program or extract the contents of the ZIP, depending on our operating system and which installation format we chose. We will refer to the location where we installed Glassfish as GLASSFISH_HOME.

Note

At the time of publication, the most recent download for Glassfish was 3.1.2.2 and is available at http://glassfish.java.net/downloads/3.1.2.2-final.html.

As Glassfish uses OSGI bundles for the various pieces that make up the entire server environment, the download of JBoss Weld from earlier does not contain an appropriate JAR that we can use as a replacement for the server.

The appropriate JBoss Weld OSGI bundle, for the most recent release, is available at https://repository.jboss.org/nexus/content/repositories/releases/org/jboss/weld/weld-osgi-bundle/1.1.10.Final/ and is called weld-osgi-bundle-1.1.10.Final.jar.

We need to rename the JAR we just downloaded to weld-osgi-bundle.jar, essentially removing all reference to the version of the file, as that is the name of the file we need to replace within Glassfish.

Once renamed, we move weld-osgi-bundle.jar into GLASSFISH_HOME\glassfish\modules and replace the existing file of that name.

Now we deploy chapter3.war to Glassfish by copying it to GLASSFISH_HOME\glassfish\domains\domain1\autodeploy.

Note

The autodeployment directory we just specified refers to domain1 as the single domain in a default installation, which needs to be modified depending on our environment setup.

And lastly, we run Glassfish using:

asadmin start-domain

By checking GLASSFISH_HOME\glassfish\domains\logs\server.log, we should see an output similar to the following, which informs us that chapter3.war was deployed with JBoss Weld 1.1.10.Final:

By opening a browser and navigating to http://localhost:8080/chapter3/index.jsf, we will see the message Welcome to JBoss Weld.

Apache Tomcat

As Apache Tomcat is only a Servlet container, there is no CDI implementation provided by default. This has both an upside and a downside to it. The upside is that we don't have to alter the default configuration and setup of Apache Tomcat in any way to use JBoss Weld with it. The downside is that all of our applications that utilize CDI need to bundle their own copy of JBoss Weld within WEB-INF/lib of the WAR.

If we don't already have Apache Tomcat installed, download the latest release from http://tomcat.apache.org/download-70.cgi and extract the contents of the ZIP. We will refer to the location where we extracted Apache Tomcat as CATALINA_HOME.

Note

At the time of publication, the most recent download for Apache Tomcat was 7.0.35.

We have a separate Maven profile in our example application for Apache Tomcat that will package weld-servlet.jar, along with a JSF implementation, into WEB-INF/lib of the archive. The profile also includes web.xml so that the servlet listener from JBoss Weld can be used to activate it on startup. The listener definition is as follows:

<listener-class>

org.jboss.weld.environment.servlet.Listener

</listener-class>

</listener>

With our application as it stands, we have JBoss Weld set up to allow us to use the most common development practices of CDI. However, if we need access to the BeanManager extension SPI, we need some additional configuration.

JBoss Weld is unable to automatically bind the BeanManager extension SPI into JNDI as Apache Tomcat's JNDI is read-only. For the BeanManager to be accessible through JNDI, we need to add the following content into META-INF/context.xml of our WAR:

<Resource name="BeanManager" auth="Container"

type="javax.enterprise.inject.spi.BeanManager"

factory="org.jboss.weld.resources.ManagerObjectFactory" />

</Context>

Then for the BeanManager to be available to our application, we need the following in 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>

The BeanManager is then accessible from JNDI under java:comp/env/BeanManager.

To build chapter3.war for Apache Tomcat, we need to run the following command:

mvn clean package -PTomcat7

Then, copy chapter3.war into CATALINA_HOME\webapps and run CATALINA_HOME\bin\startup.bat or startup.sh, depending on your environment.

In the server console, during startup, we will see messages showing that the version of JBoss Weld that was started for chapter3.war is 1.1.10.Final, as shown in the following screenshot:

Apache Tomcat

By opening a browser and navigating to http://localhost:8080/chapter3/index.jsf, we will see the message Welcome to JBoss Weld.

Summary

We've now covered how to upgrade the version of JBoss Weld that is present within a Java EE container, such as JBoss AS7 and Glassfish, as well as how to use JBoss Weld as part of our application on a Servlet container, such as Apache Tomcat.

An important point to note here is how we bundled JBoss Weld into our application and added the servlet listener; they are not specific to Apache Tomcat. Those steps are applicable to all Servlet containers that implement the Servlet 2.5 specification or a more recent version of it.

The only aspect of bundling JBoss Weld for Apache Tomcat that will vary between Servlet containers is how the BeanManager extension is attached to JNDI. If a Servlet container has a writable JNDI, JBoss Weld will handle it for us, but if it is a read-only JNDI such as Apache Tomcat, we will need a similar configuration to store the reference into JNDI.