Weld SiteCommunity Documentation

Chapter 6. Getting started with Weld

6.1. Prerequisites
6.2. Deploying to WildFly
6.3. Deploying to GlassFish
6.4. Deploying to Apache Tomcat
6.5. Deploying to Jetty

Weld comes with a number of examples. We recommend you start with examples/jsf/numberguess and examples/jsf/translator. Numberguess is a web (war) example containing only non-transactional managed beans. This example can be run on a wide range of servers, including WildFly , GlassFish, Apache Tomcat, Jetty, Google App Engine, and any compliant Java EE 7 container. Translator is an enterprise (ear) example that contains session beans. This example must be run on WildFly 8 or better, GlassFish 4 or better, or any compliant Java EE 7 container.

Both examples use JSF 2.2 as the web framework and, as such, can be found in the examples/jsf directory of the Weld distribution.

To run the examples with the provided build scripts, you’ll need the following:

In the next few sections, you’ll be using the Maven command (mvn) to invoke the Maven project file in each example to compile, assemble and deploy the example to WildFly and, for the war example, Apache Tomcat. You can also deploy the generated artifact (war or ear) to any other container that supports Java EE 7, such as GlassFish 4.

The sections below cover the steps for deploying with Maven in detail. Let’s start with WildFly.

To deploy the examples to WildFly, you’ll need WildFly 8.0.0.Final or above. The good news is that there are no additional modifications you have to make to the server. It’s ready to go!

After you have downloaded WildFly, extract it. (We recommended renaming the folder to include the as qualifier so it’s clear that it’s the application server). You can move the extracted folder anywhere you like. Wherever it lays to rest, that’s what we’ll call the WildFly installation directory, or JBOSS_HOME.

$> unzip wildfly-8.0.0.Final.zip
$> mv wildfly-8.*/ wildfly-8

In order for the build scripts to know where to deploy the example, you have to tell them where to find your WildFly installation. Set the JBOSS_HOME environment variable to point to the WildFly installation, e.g.:

$> export JBOSS_HOME=/path/to/wildfly-8

You’re now ready to run your first example!

Switch to the examples/jsf/numberguess directory and execute the Maven deploy target:

$> cd examples/jsf/numberguess
$> mvn jboss-as:run

Note

If you are using Eclipse, you should seriously consider installing the JBoss Tools add-ons, which include a wide variety of tooling for CDI and Java EE development, as well as an enhanced WildFly server view.

Wait a few seconds for the application to deploy (or the application server to start) and see if you can determine the most efficient approach to pinpoint the random number at the local URL http://localhost:8080/weld-numberguess.

Note

The Maven WildFly plugin includes additional goals for WildFly to deploy and undeploy the archive.

  • mvn wildfly:deploy - deploy the example to a running WildFly instance
  • mvn wildfly:undeploy - undeploy the example from a running WildFly instance
  • mvn wildfly:redeploy - redeploys the example

For more information on the WildFly Maven plugin see the plugin documentation.

You can also run functional tests to verify that the example works as expected. Run:

$> mvn verify -Darquillian=wildfly-managed-8

You should see the following output:

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

The second starter example, weld-translator, will translate your text into Latin. (Well, not really, but the stub is there for you to implement, at least. Good luck!) To try it out, switch to the translator example directory and execute the deploy target:

$> cd examples/jsf/translator/ear
$> mvn jboss-as:run

Note

The translator uses session beans, which are packaged in an EJB module within an ear. Java EE 7 allows session beans to be deployed in war modules, but that’s a topic for a later chapter.

Again, wait a few seconds for the application to deploy (if you’re really bored, read the log messages), and visit http://localhost:8080/weld-translator to begin pseudo-translating.

Again, functional tests can be running by executing:

$> cd examples/jsf/translator/ftest
$> mvn verify -Darquillian=wildfly-managed-8

Deploying to GlassFish should be easy and familiar, right? After all, it’s the Java EE 7 reference implementation and Weld is the CDI reference implementation, meaning Weld gets bundled with GlassFish. So yes, it’s all quite easy and familiar.

To deploy the examples to GlassFish, you’ll need a GlassFish 4.0 release. Select the release that ends in either -unix.sh or -windows.exe depending on your platform. After the download is complete, execute the installer. On Linux/Unix, you’ll need to first make the script executable.

$> chmod 755 glassfish-4.0-unix.sh
$> ./glassfish-4.0-unix.sh

On Windows you can just click on the executable. Follow the instructions in the installer. It will create a single domain named domain1. You’ll use that domain to deploy the example. We recommend that you choose 7070 as the main HTTP port to avoid conflicts with a running instance of WildFly (or Apache Tomcat).

Next, make sure the GLASSFISH_HOME environment variable is set to point to the GlassFish installation.

Now switch to the example directory again and create a new GlassFish domain for the example.

$> cd examples/jsf/numberguess
$> mvn glassfish:create-domain

You are now ready to deploy the example by running:

$> mvn package glassfish:deploy

Once the command completes the application is available at http://localhost:7070/weld-numberguess

The example is deployed using the maven-glassfish-plugin. For more information about the plugin see the plugin documentation

There are alternative ways of,deploying applications to GlassFish either by using the GlassFish Admin Console or the asadmin command.

The reason the same artifact can be deployed to both WildFly and GlassFish, without any modifications, is because all of the features being used are part of the standard platform. And what a capable platform it has become!

Servlet containers are not required to support Java EE services like CDI. However, you can use CDI in a servlet container like Tomcat by embedding a standalone CDI implementation such as Weld.

Weld comes with servlet integration extension which bootstraps the CDI environment and provides injection into servlets components. Basically, it emulates some of the work done by the Java EE container, but you don’t get the enterprise features such as session beans and container-managed transactions.

Let’s give the Weld servlet extension a spin on Apache Tomcat. First, you’ll need to download Tomcat 7.0.50 or later from tomcat.apache.org and extract it.

$> unzip apache-tomcat-7.0.53.zip

The Maven plugin communicates with Tomcat over HTTP, so it doesn’t care where you have installed Tomcat. However, the plugin configuration assumes you are running Tomcat in its default configuration, with a hostname of localhost and port 8080. The readme.txt file in the example directory has information about how to modify the Maven settings to accommodate a different setup.

To allow Maven to communicate with Tomcat over HTTP, edit the conf/tomcat-users.xml file in your Tomcat installation. For Tomcat 7 and higher add the following line:


<user username="admin" password="" roles="manager-script"/>

Next, start Tomcat. You can either start Tomcat from a Linux shell:

$> cd /path/to/apache-tomcat-7
$> ./bin/start.sh

a Windows command window:

$> cd c:\path\to\apache-tomcat-7\bin
$> start

or you can start the server using an IDE, like Eclipse.

Now you’re ready to deploy the numberguess example to Tomcat!

Change to the examples/jsf/numberguess directory again and run the following Maven command:

$> cd examples/jsf/numberguess
$> mvn clean compile war:exploded tomcat7:deploy -Ptomcat

Once the application is deployed, you can redeploy it using this command:

$> mvn tomcat7:redeploy -Ptomcat

The -Ptomcat argument activates the tomcat profile defined in the Maven POM (pom.xml). Among other things, this profile activates the Tomcat plugin.

Rather than shipping the container off to a standalone Tomcat installation, you can also execute the application in an embedded Tomcat 6 container:

$> mvn war:inplace tomcat7:run -Ptomcat

The advantage of using the embedded server is that changes to assets in src/main/webapp take effect immediately. If a change to a webapp configuration file is made, the application may automatically redeploy (depending on the plugin configuration). If you make a change to a classpath resource, you need to execute a build:

$> mvn compile war:inplace -Ptomcat

Finally, you can run the functional tests:

$> mvn verify -Darquillian=tomcat-embedded-7 -Ptomcat

There are several other Maven goals that you can use if you are hacking on the example, which are documented in the example’s README.md file.

If you’ve read through the entire Tomcat section, then you’re all ready to go. The Maven build parallels the embedded Tomcat deployment. If not, don’t worry. We’ll still go over everything that you need to know again in this section.

The Maven POM (pom.xml) includes a profile named jetty that activates the Maven Jetty plugin, which you can use to start Jetty in embedded mode and deploy the application in place. You don’t need anything else installed except to have the Maven command (mvn) on your path. The rest will be downloaded from the internet when the build is run.

To run the weld-numberguess example on Jetty, switch to the example directory and execute the inplace goal of the Maven war plugin followed by the run goal of the Maven Jetty plugin with the jetty profile enabled, as follows:

$> cd examples/jsf/numberguess
$> mvn war:inplace jetty:run -Pjetty

The log output of Jetty will be shown in the console. Once Jetty reports that the application has deployed, you can access it at the following local URL: http://localhost:9090/weld-numberguess. The port is defined in the Maven Jetty plugin configuration within the jetty profile.

Any changes to assets in src/main/webapp take effect immediately. If a change to a webapp configuration file is made, the application may automatically redeploy. The redeploy behavior can be fined-tuned in the plugin configuration. If you make a change to a classpath resource, you need to execute a build and the inplace goal of the Maven war plugin, again with the jetty profile enabled.

$> mvn compile war:inplace -Pjetty

The war:inplace goal copies the compiled classes and jars inside src/main/webapp, under WEB-INF/classes and WEB-INF/lib, respectively, mixing source and compiled files. However, the build does work around these temporary files by excluding them from the packaged war and cleaning them during the Maven clean phase.

Finally, you can run the functional tests:

$> mvn verify -Darquillian=jetty-embedded-7 -Pjetty

Now that you have gotten the starter applications deployed on the server of your choice, you probably want to know a little bit about how they actually work.