JavaEE6 marks a major milestone in enterprise Java with the arrival of subspecs such as CDI, JPA2, EJB 3.1 (with EJB Lite) or Servlet 3.0. But the most important part for me is the new web profile which was really overdue.JavaEE5 left web developers somewhere between all or nothing. POSCs (Plain Old Servlet Containers) proveded not all of the JEE stack that might be needed while full blown application servers like JBoss were too heavy (although JBoss did a< good job with the different profiles).

Integrating different Frameworks into POSCs can be really a pain in the ass. Take JPA for example. JPA in a POSC is nothing more than a JavaSE usage of the JPA. Which means there are no manged transactions no container managed persistence contexts etc. Everything had to be custom made which is not the desired way.

With the new web profile you only get what you really need: Servlets, JPA2, JTA, CDI, EJB Lite which makes web development a lot easier. But not only the developer benefits but also the vendors since they don’t have to implement the full stack.

Hopefully vendors will jump on the JEE6 train and there will be a vibrant market of implementations.

In a web application always put the stuff (which is not packaged a single JARs)  in /WEB-INF/classes/META-INF (e.g. persistence.xml or service files) and not in /META-INF. Otherwise the various applications will not be able to locate them.

With this way of injection it is possible to really inject everything. POJOs, DB resoures like ResultSets even primitives can be injected.

The following two code listings show how to produce and how to consume. I’m going to explain what’s really happening here afterwards:

@Produces @Random int next() {
 return getRandom().nextInt(maxNumber);
}

@Inject @Random
private int number;

Okay, as promised here are some explanations:

@Produces tells Weld that something that might get injected somewhere is being produced here. What is specified by the next annotation. Although @Random might look like a built-in annotation it is not. I named it Random to point out that the int is generated (pseudo) randomly. This is a socalled qualifier annotation which tells the dependency injection framework where to look for the producer.

@Target( { TYPE, METHOD, PARAMETER, FIELD })
@Retention(RUNTIME)
@Documented
@Qualifier
public @interface Random
{
}

The only new thing is the @Qualifier annotation which is contained in the javax.inject package and defines qualifier annotations. As you can see in the samples above it is really possible to inject everything. There thousands of scenarios in which this might be useful. Just imagine a producer which generates a unique ID fo every instance.

Event / Observer concept

So far I just talked about the DI features of JSR-299. Althought the official name of this JRS-299 might say otherwise Weld is not limited to dependecy injection. One thing I really love is the event “bus” which basically an implementation of the observer pattern with lots of tuning and simplification.

The greatest simplification ist that there is no need to explicitly register an observer and the observable knows nothing about its observers. If you look a the “standard” observer pattern used in Swing you’ll find a method JButton.addActionListener(ActionListener l). It’s clear what’s happening here: an ActionListener is explicitly registered at one button. That means that the Button knows its listeners and the listener knows exactly to what component he or she is listening to.

The following annotation defines an observable (Standard Java: implements Observable):

@Qualifier
@Target( { PARAMETER })
@Retention(RUNTIME)
public @interface Event {
 String source();
}

The next part might seem a litte strange since it implements an annotation but later it will be clear why this is done.

package de.publicstaticfinal.web.jsf;
import javax.enterprise.inject.AnnotationLiteral;
public abstract class EventImpl extends AnnotationLiteral<Event> implements Event
{
}

Next we declare the concrete event we’re listening to. This is just a simple POJO. IF you look at the Java API this Event is equivalent to the second argument of Observer.update(Oberservable o, Object argument). For better clarification I name it HelloWeldEvent.

package de.publicstaticfinal.web.jsf;
public class HelloWeldEvent
{
 private String source;

 public HelloWeldEvent(String source)
 {
 this.source = source;
 }

 public String getSource()
 {
 return source;
 }
}

A simple event which contains the name of its source. What’s left is the event listener itself but that’s not that many code:

public void handleEvent(@Observes @Any HelloWeldEvent hwe)
{
 System.out.println(hwe.getSource());
}

@Observes is the annotations which tells Weld that this method listens to ALL (@Any) HelloWeldEvent which are raised in this application. This might be useful in some circumstances (imagine a logging facility which gets called every time a button is clicked) but on other occasions this is to bloated. Therefore I added the “method” source() to the Event annotation. With that it is possible to just listen to a special HelloWeldEvent.

public void handleEvent(@Observes @Event("button1") HelloWeldEvent hwe)
{
 System.out.println(hwe.getSource());
}

This observer method just gets called when the raised event’s source is “button1″. So far so good but how do you raise an event? The famous BeanManager provides a method for doing this: public void fireEvent(Object event, Annotation… bindings).

The first argument is the event itself. It is of type Object since there is no special interface an event has to implement which means that every Object could be an event. The next arguments are the anootation bindings which are used to resolve the listeners. In this tutorial’s case this would be Event. And now it might be clear why we need an implementation if Event. I used @Event(“button1″) to specify on which concrete event the listener should be called. Weld needs a mechanism to read this information and to decide whether the method should be called or not.

Written in Java it looks like this:

private void fireEvent(){
 beanManager.fireEvent(new HelloWeldEvent("Test"), new EventImpl(){
 public String source()
 {
 return "button1";
 }});
 }

When calling fireEvent a concrete implementation of Event is provided and Weld can use the source() method to retrieve the source. After an check whith equals to the value of @Event(…) Weld knows what methods to call. Be aware that we talk about synchronous events here. JSR-299 does not define asynchronous events.

This was the last part of my tutorial series. As I stated before JSR-299 is way to extensive to be completely covered by a tutorial. I just wanted to give people who are interested in working with it a litte help to get started. I hope that I achieved this goal a little bit and the ones who read the article are goind to use Weld (or other implementations) since it will boost your application.

Having said that lets go to…

Obtaining the BeanManager

In your web.xml/context.xml you declared a managed resource called BeanManager which is main interface to all Bean related stuff (adding/removing beans from a context etc.). There are two ways for obtaining the Bean Manager. The first way is to use dependey injection with the @Resource annotation:

@Resource(mappedName="java:/comp/env/BeanManager")
BeanManager beanManager;

Here you let the container do all the work. Or you cann ask Weld to inject the BeanManager by using @Inject:

@Inject
BeanManager beanManager;

Simple Dependency Injection

In the previous section I made a little trip to the future by using the @Inject annotation. As you might have already guessed this annotation tells Weld that the field/parameter should be injected. This is the simplest dependency injection available. You just tell Weld that you need something injected and Weld takes care of it. A good example for this would be a Cache which is typically application scoped (although every scoped bean can be injected):

package de.publicstaticfinal.web.jsf;

import javax.enterprise.context.ApplicationScoped;
import javax.inject.Named;

@Named
@ApplicationScoped
public class Cache {...}

As you learned already this managed bean can be accessed via EL using #{cache}. But most often you’re not only using the Cache in the frontend but in the business logic too. The extenden HelloWeld bean would look like this:

package de.publicstaticfinal.web.jsf;

import java.io.Serializable;
import javax.enterprise.context.SessionScoped;
import javax.inject.Named;

@Named("helloWeld")
@SessionScoped
public class HelloWeld implements Serializable {
  private String message = "Hello Weld";

  @Inject
  private transient Cache cache;

  public String getMessage() {
    return message;
  }
}

The injected Cache object has to be marked as transient since HelloWeld is serializable while the Cache is not. If the cache field is not marked as transient Weld will throw an Exception since it enforces serializability. This is really a good feature in Weld since it leads to consistent data.

Another good point is that you can use loose coupling without much effort. If the Cache class above would be “CacheImpl” and implementing a Cache interface you don’t have to change your code that much. The Cache implementation class would look like this:

package de.publicstaticfinal.web.jsf;

import javax.enterprise.context.ApplicationScoped;
import javax.inject.Named;

@Named("cache")
@ApplicationScoped
public class CacheImpl implements Cache
{

}

And the CacheImpl would be injected like this:

@Inject @Named("cache")
private transient Cache cache;

What if you need mor than one Caches? I’m too lazy at the moment to think of a scenario where you might need this but of course this is possible. Although with the restriction that this cannot be achieved directly by dependency injection. If you asked yourself why I explained how to obtain the BeanManager here’s the answer: the BeanManager helps you to create new instances of an injectable resource. The following mehtod gets called with getNewCache(“cache”):

private Cache getNewCache(String elName) {
  Set<Bean<?>> beans = beanManager.getBeans(elName);
  for (Bean<?> bean : beans) {
    Set<Type> beanTypes = bean.getTypes();
    for (Type type : beanTypes) {
      if (type.equals(Cache.class)) {
        Bean<Cache> tmp = (Bean<Cache>) bean;
        Cache newCache = tmp.create(beanManager.createCreationalContext(tmp));
        return newCache;
      }
    }
 }
 return null;
}

• 2: In this line all beans which can be accessed by #{cache} are retrieved
• 4: all types of the bean are read
• 6: Check if the bean is of type Cache
• 7: cast to the proper type
• 8: retrieval of the proxy object by api calls

I’m not going into detail of every single API call. If you’re interested in more information please refer to the Javadoc (link: http://docs.jboss.org/cdi/api/1.0-CR1/).

I think that’s enough for the second part of my tutorial. This part just covered injection of scoped beans. While this is a pretty powerful tool JSR-299 doesn’t limit injection to scoped beans. Generally speaking you can blow inject your foot away using Weld.

In this first part I want to create a really really really simple example application – the so called “Hello Weld” example. For the Non-German readers: “Hello Weld” is a litte pun. “World” is “Welt” in German which is pretty close to Weld. Enough jokes for now, let’s go to work.First we create the simplest bean known to mankind:

package de.publicstaticfinal.web.jsf;
import java.io.Serializable;

import javax.enterprise.context.SessionScoped;
import javax.inject.Named;

@Named("helloWeld")
@SessionScoped
public class HelloWeld implements Serializable {
private String message = "Hello Weld";

 public String getMessage() {
   return message;
 }
}

• 9: @Named(“helloWeld”) tells Weld that this bean is accessible under the name “helloWeld”. You don’t have to specify a value the default would be the camel-cased de-capitalized name of the Class.
• 10: @SessionScoped tells Weld that this bean resides in session scope. Be aware: When you use JSF 2.0 the are two @SessionScoped annotation. If using Wled always use the annotation in the javax.enterprise package.

Now consider the following Facelets page which just outputs the “message” field from the bean referenced by the name “helloWeld”:

<html xmlns="http://www.w3.org/1999/xhtml"
 xmlns:ui="http://java.sun.com/jsf/facelets"
 xmlns:h="http://java.sun.com/jsf/html"
 xmlns:f="http://java.sun.com/jsf/core">
<head>
<title>Test</title>
</head>
<body>
<h:outputText value="#{helloWeld.message}" />
</body>
</html>

And with little surprise you get this output:

What happened? When helloWeld.jsf is requested Weld does a lookup of “#{helloWeld}” and since we declared the bean it can be found by Weld. Weld creates an instance of the bean and puts it into session scope. If you debug the application and create a breakpoint you can see that it is indeed always the same instance within a session.

There’s nothing that special about it since the scoped annotations are also included in JSF 2.0. Part 2 of my tutorial will show you the real fun with dependency injection.

• Mojarra 2.0.0 (Instructions for obtaining can be found here)
• Weld 1.0.0CR1 Servlet Environment (“weld-servlet.jar” contained in Weld donwload archive)
• JSR-250 API
• jstl 1.2
• el-impl 2.1.2-b04

Thats’s not really much (just about 5 MB of JARs) but all you need to get your application running. I’m not going into detail on how to configurate JSF but just what’s additionally required for Weld.

First you have to “tell” Weld and Tomcat that Weld is present by including the Weld Servlet listener in your application’s web.xml:

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

After that create an empty file called “beans.xml” in the WEB-INF folder. Now Weld can do its magical stuff with all incoming Servlet request. Buth there’s more. This was just the setup of the Weld Servlet environment. Next you need to tell Weld what BeanManager should be used. The BeanManager is the reference to the Injection Manager itself.

The first thing to add is a resource reference in web.xml:

<resource-env-ref>
 <description>Object factory for the CDI Bean Manager</description>
 <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>

And finally if not already present create META-INF/context.xml and put the Resource itself in it:

<Resource
 name="BeanManager"
 auth="Container"
 type="javax.enterprise.inject.spi.BeanManager"
 factory="org.jboss.weld.resources.ManagerObjectFactory"
/>

That’s all. Tomcat6 is now running with JSF 2.0 and Weld 1.0.0CR1 and ready for hours of fun. As you might have already guessed this post doesn’t contain anything about how to use Weld but just how to set it up with Tomcat6. However I’m writing a short introduction for Wled which should be online within 3 or 4 days.

UPDATE: For those using Maven here’s a simple POM containing the required repositories and dependencies:

<project
 xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>de.publicstaticfinal</groupId>
 <artifactId>WeldJSF2</artifactId>
 <packaging>war</packaging>
 <version>0.0.1-SNAPSHOT</version>
 <repositories>
  <repository>
   <id>maven2-repository.dev.java.net</id>
   <name>Java.net Repository for Maven</name>
   <url>http://download.java.net/maven/2/</url>
   <layout>default</layout>
  </repository>
  <repository>
  <snapshots />
   <id>ibiblio</id>
   <url>http://www.ibiblio.org/maven2/</url>
   </repository>
   <repository>
   <id>JBoss</id>
   <url>http://repository.jboss.com/maven2</url>
  </repository>
 </repositories>
 <dependencies>
  <dependency>
   <groupId>com.sun.faces</groupId>
   <artifactId>jsf-api</artifactId>
   <version>2.0.1</version>
  </dependency>
  <dependency>
   <groupId>com.sun.faces</groupId>
   <artifactId>jsf-impl</artifactId>
   <scope>runtime</scope>
   <version>2.0.1</version>
  </dependency>
  <dependency>
   <groupId>javax.enterprise</groupId>
   <artifactId>cdi-api</artifactId>
   <scope>provided</scope>
   <version>1.0-CR1</version>
  </dependency>
  <dependency>
   <groupId>javax.annotation</groupId>
   <artifactId>jsr250-api</artifactId>
   <version>1.0</version>
  </dependency>
  <dependency>
   <groupId>javax.servlet</groupId>
   <artifactId>jstl</artifactId>
   <version>1.2</version>
   <scope>runtime</scope>
  </dependency>
  <dependency>
   <groupId>org.jboss.weld.servlet</groupId>
   <artifactId>weld-servlet</artifactId>
   <version>1.0.0-CR1</version>
   <scope>runtime</scope>
  </dependency>
  <dependency>
   <groupId>org.glassfish.web</groupId>
   <artifactId>el-impl</artifactId>
   <version>2.1.2-b04</version>
   <scope>runtime</scope>
   <exclusions>
    <exclusion>
     <groupId>javax.el</groupId>
     <artifactId>el-api</artifactId>
    </exclusion>
   </exclusions>
  </dependency>
 </dependencies>
</project>