A bean is exactly what you think it is. Only now, it has a true identity in the container environment.

Prior to Java EE 6, there was no clear definition of the term "bean" in the Java EE platform. Of course, we’ve been calling Java classes used in web and enterprise applications "beans" for years. There were even a couple of different kinds of things called "beans" in EE specifications, including EJB beans and JSF managed beans. Meanwhile, other third-party frameworks such as Spring and Seam introduced their own ideas of what it meant to be a "bean". What we’ve been missing is a common definition.

Java EE 6 finally laid down that common definition in the Managed Beans specification. Managed Beans are defined as container-managed objects with minimal programming restrictions, otherwise known by the acronym POJO (Plain Old Java Object). They support a small set of basic services, such as resource injection, lifecycle callbacks and interceptors. Companion specifications, such as EJB and CDI, build on this basic model. But, at last, there’s a uniform concept of a bean and a lightweight component model that’s aligned across the Java EE platform.

With very few exceptions, almost every concrete Java class that has a constructor with no parameters (or a constructor designated with the annotation @Inject) is a bean. This includes every JavaBean and every EJB session bean. If you’ve already got some JavaBeans or session beans lying around, they’re already beans—you won’t need any additional special metadata.

The JavaBeans and EJBs you’ve been writing every day, up until now, have not been able to take advantage of the new services defined by the CDI specification. But you’ll be able to use every one of them with CDI—allowing the container to create and destroy instances of your beans and associate them with a designated context, injecting them into other beans, using them in EL expressions, specializing them with qualifier annotations, even adding interceptors and decorators to them—without modifying your existing code. At most, you’ll need to add some annotations.

Now let’s see how to create your first bean that actually uses CDI.

Suppose that we have two existing Java classes that we’ve been using for years in various applications. The first class parses a string into a list of sentences:

public class SentenceParser {

   public List<String> parse(String text) { ... }

}

The second existing class is a stateless session bean front-end for an external system that is able to translate sentences from one language to another:

@Stateless

public class SentenceTranslator implements Translator {

   public String translate(String sentence) { ... }

}

Where Translator is the EJB local interface:

@Local

public interface Translator {

   public String translate(String sentence);

}

Unfortunately, we don’t have a class that translates whole text documents. So let’s write a bean for this job:

public class TextTranslator {

   private SentenceParser sentenceParser;

   private Translator sentenceTranslator;


   @Inject

   TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator) {

      this.sentenceParser = sentenceParser;

      this.sentenceTranslator = sentenceTranslator;

   }


   public String translate(String text) {

      StringBuilder sb = new StringBuilder();

      for (String sentence: sentenceParser.parse(text)) {

          sb.append(sentenceTranslator.translate(sentence));

      }

      return sb.toString();

   }

}

But wait! TextTranslator does not have a constructor with no parameters! Is it still a bean? If you remember, a class that does not have a constructor with no parameters can still be a bean if it has a constructor annotated @Inject.

As you’ve guessed, the @Inject annotation has something to do with dependency injection! @Inject may be applied to a constructor or method of a bean, and tells the container to call that constructor or method when instantiating the bean. The container will inject other beans into the parameters of the constructor or method.

We may obtain an instance of TextTranslator by injecting it into a constructor, method or field of a bean, or a field or method of a Java EE component class such as a servlet. The container chooses the object to be injected based on the type of the injection point, not the name of the field, method or parameter.

Let’s create a UI controller bean that uses field injection to obtain an instance of the TextTranslator, translating the text entered by a user:

Alternatively, we may obtain an instance of TextTranslator programmatically from an injected instance of Instance, parameterized with the bean type:

import javax.enterprise.inject.Instance;

import javax.inject.Inject;


....


@Inject Instance<TextTranslator> textTranslatorInstance;

...

public void translate() {

   textTranslatorInstance.get().translate(inputText);

}

Notice that it isn’t necessary to create a getter or setter method to inject one bean into another. CDI can access an injected field directly (even if it’s private!), which sometimes helps eliminate some wasteful code. The name of the field is arbitrary. It’s the field’s type that determines what is injected.

At system initialization time, the container must validate that exactly one bean exists which satisfies each injection point. In our example, if no implementation of Translator is available—if the SentenceTranslator EJB was not deployed—the container would inform us of an unsatisfied dependency. If more than one implementation of Translator were available, the container would inform us of the ambiguous dependency.

Before we get too deep in the details, let’s pause and examine a bean’s anatomy. What aspects of the bean are significant, and what gives it its identity? Instead of just giving examples of beans, we’re going to define what makes something a bean.

Enough hand-waving. More formally, the anatomy of a bean, according to the spec:

Let’s see what all this new terminology means.

We’ve already seen two types of beans: JavaBeans and EJB session beans. Is that the whole story? Actually, it’s just the beginning. Let’s explore the various kinds of beans that CDI implementations must support out-of-the-box.

The @Inject annotation lets us define an injection point that is injected during bean instantiation. Injection can occur via three different mechanisms.

Bean constructor parameter injection:

public class Checkout {


   private final ShoppingCart cart;


   @Inject

   public Checkout(ShoppingCart cart) {

      this.cart = cart;

   }


}

A bean can only have one injectable constructor.

Initializer method parameter injection:

public class Checkout {


   private ShoppingCart cart;


   @Inject

   void setShoppingCart(ShoppingCart cart) {

      this.cart = cart;

   }


}

And direct field injection:

public class Checkout {


   private @Inject ShoppingCart cart;


}

Dependency injection always occurs when the bean instance is first instantiated by the container. Simplifying just a little, things happen in this order:

(The only complication is that the container might call initializer methods declared by a superclass before initializing injected fields declared by a subclass.)

CDI also supports parameter injection for some other methods that are invoked by the container. For instance, parameter injection is supported for producer methods:

@Produces Checkout createCheckout(ShoppingCart cart) {

    return new Checkout(cart);

}

The CDI specification defines a procedure, called typesafe resolution, that the container follows when identifying the bean to inject to an injection point. This algorithm looks complex at first, but once you understand it, it’s really quite intuitive. Typesafe resolution is performed at system initialization time, which means that the container will inform the developer immediately if a bean’s dependencies cannot be satisfied.

The purpose of this algorithm is to allow multiple beans to implement the same bean type and either:

Obviously, if you have exactly one bean of a given type, and an injection point with that same type, then bean A is going to go into slot A. That’s the simplest possible scenario. When you first start your application, you’ll likely have lots of those.

But then, things start to get complicated. Let’s explore how the container determines which bean to inject in more advanced cases. We’ll start by taking a closer look at qualifiers.

If we have more than one bean that implements a particular bean type, the injection point can specify exactly which bean should be injected using a qualifier annotation. For example, there might be two implementations of PaymentProcessor:

@Synchronous

public class SynchronousPaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }

}

@Asynchronous

public class AsynchronousPaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }

}

Where @Synchronous and @Asynchronous are qualifier annotations:

@Qualifier

@Retention(RUNTIME)

@Target({TYPE, METHOD, FIELD, PARAMETER})

public @interface Synchronous {}

@Qualifier

@Retention(RUNTIME)

@Target({TYPE, METHOD, FIELD, PARAMETER})

public @interface Asynchronous {}

A client bean developer uses the qualifier annotation to specify exactly which bean should be injected.

Using field injection:

@Inject @Synchronous PaymentProcessor syncPaymentProcessor;

@Inject @Asynchronous PaymentProcessor asyncPaymentProcessor;

Using initializer method injection:

@Inject

public void setPaymentProcessors(@Synchronous PaymentProcessor syncPaymentProcessor,

                                 @Asynchronous PaymentProcessor asyncPaymentProcessor) {

   this.syncPaymentProcessor = syncPaymentProcessor;

   this.asyncPaymentProcessor = asyncPaymentProcessor;

}

Using constructor injection:

@Inject

public Checkout(@Synchronous PaymentProcessor syncPaymentProcessor,

                @Asynchronous PaymentProcessor asyncPaymentProcessor) {

   this.syncPaymentProcessor = syncPaymentProcessor;

   this.asyncPaymentProcessor = asyncPaymentProcessor;

}

Qualifier annotations can also qualify method arguments of producer, disposer and observer methods. Combining qualified arguments with producer methods is a good way to have an implementation of a bean type selected at runtime based on the state of the system:

@Produces

PaymentProcessor getPaymentProcessor(@Synchronous PaymentProcessor syncPaymentProcessor,

                                     @Asynchronous PaymentProcessor asyncPaymentProcessor) {

   return isSynchronous() ? syncPaymentProcessor : asyncPaymentProcessor;

}

If an injected field or a parameter of a bean constructor or initializer method is not explicitly annotated with a qualifier, the default qualifier,@Default, is assumed.

Now, you may be thinking, "What’s the different between using a qualifier and just specifying the exact implementation class you want?" It’s important to understand that a qualifier is like an extension of the interface. It does not create a direct dependency to any particular implementation. There may be multiple alternative implementations of @Asynchronous PaymentProcessor!

Whenever a bean or injection point does not explicitly declare a qualifier, the container assumes the qualifier @Default. From time to time, you’ll need to declare an injection point without specifying a qualifier. There’s a qualifier for that too. All beans have the qualifier @Any. Therefore, by explicitly specifying @Any at an injection point, you suppress the default qualifier, without otherwise restricting the beans that are eligible for injection.

This is especially useful if you want to iterate over all beans with a certain bean type. For example:

import javax.enterprise.inject.Instance;


...


@Inject

void initServices(@Any Instance<Service> services) {

   for (Service service: services) {

      service.init();

   }

}

Java annotations can have members. We can use annotation members to further discriminate a qualifier. This prevents a potential explosion of new annotations. For example, instead of creating several qualifiers representing different payment methods, we could aggregate them into a single annotation with a member:

@Qualifier

@Retention(RUNTIME)

@Target({METHOD, FIELD, PARAMETER, TYPE})

public @interface PayBy {

   PaymentMethod value();

}

Then we select one of the possible member values when applying the qualifier:

private @Inject @PayBy(CHECK) PaymentProcessor checkPayment;

We can force the container to ignore a member of a qualifier type by annotating the member @Nonbinding.

@Qualifier

@Retention(RUNTIME)

@Target({METHOD, FIELD, PARAMETER, TYPE})

public @interface PayBy {

   PaymentMethod value();

   @Nonbinding String comment() default "";

}

An injection point may specify multiple qualifiers:

@Inject @Synchronous @Reliable PaymentProcessor syncPaymentProcessor;

Then only a bean which has both qualifier annotations would be eligible for injection.

@Synchronous @Reliable

public class SynchronousReliablePaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }

}

Alternatives are beans whose implementation is specific to a particular client module or deployment scenario. This alternative defines a mock implementation of both @Synchronous PaymentProcessor and @Asynchronous PaymentProcessor, all in one:

@Alternative @Synchronous @Asynchronous

public class MockPaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }

}

By default, @Alternative beans are disabled. We need to enable an alternative in the beans.xml descriptor of a bean archive to make it available for instantiation and injection. However, this activation only applies to the beans in that archive.

<beans

   xmlns="http://xmlns.jcp.org/xml/ns/javaee"

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xsi:schemaLocation="

      http://xmlns.jcp.org/xml/ns/javaee

      http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd">

   <alternatives>

         <class>org.mycompany.mock.MockPaymentProcessor</class>

   </alternatives>

</beans>

From CDI 1.1 onwards the alternative can be enabled for the whole application using @Priority annotation.

@Priority(100) @Alternative @Synchronous @Asynchronous

public class MockPaymentProcessor implements PaymentProcessor {

   public void process(Payment payment) { ... }

}

When an ambiguous dependency exists at an injection point, the container attempts to resolve the ambiguity by looking for an enabled alternative among the beans that could be injected. If there is exactly one enabled alternative, that’s the bean that will be injected. If there are more beans with priority, the one with the highest priority value is selected.

The typesafe resolution algorithm fails when, after considering the qualifier annotations on all beans that implement the bean type of an injection point and filtering out disabled beans (@Alternative beans which are not explicitly enabled), the container is unable to identify exactly one bean to inject. The container will abort deployment, informing us of the unsatisfied or ambiguous dependency.

During the course of your development, you’re going to encounter this situation. Let’s learn how to resolve it.

To fix an unsatisfied dependency, either:

To fix an ambiguous dependency, either:

Clients of an injected bean do not usually hold a direct reference to a bean instance, unless the bean is a dependent object (scope @Dependent).

Imagine that a bean bound to the application scope held a direct reference to a bean bound to the request scope. The application-scoped bean is shared between many different requests. However, each request should see a different instance of the request scoped bean—the current one!

Now imagine that a bean bound to the session scope holds a direct reference to a bean bound to the application scope. From time to time, the session context is serialized to disk in order to use memory more efficiently. However, the application scoped bean instance should not be serialized along with the session scoped bean! It can get that reference any time. No need to hoard it!

Therefore, unless a bean has the default scope @Dependent, the container must indirect all injected references to the bean through a proxy object. This client proxy is responsible for ensuring that the bean instance that receives a method invocation is the instance that is associated with the current context. The client proxy also allows beans bound to contexts such as the session context to be serialized to disk without recursively serializing other injected beans.

Unfortunately, due to limitations of the Java language, some Java types cannot be proxied by the container. If an injection point declared with one of these types resolves to a bean with any scope other than @Dependent, the container will abort deployment, informing us of the problem.

The following Java types cannot be proxied by the container:

It’s usually very easy to fix an unproxyable dependency problem. If an injection point of type X results in an unproxyable dependency, simply:

In certain situations, injection is not the most convenient way to obtain a contextual reference. For example, it may not be used when:

In these situations, the application may obtain an instance of the interface Instance, parameterized for the bean type, by injection:

@Inject Instance<PaymentProcessor> paymentProcessorSource;

The get() method of Instance produces a contextual instance of the bean.

PaymentProcessor p = paymentProcessorSource.get();

Qualifiers can be specified in one of two ways:

Specifying the qualifiers at the injection point is much, much easier:

@Inject @Asynchronous Instance<PaymentProcessor> paymentProcessorSource;

Now, the PaymentProcessor returned by get() will have the qualifier @Asynchronous.

Alternatively, we can specify the qualifier dynamically. First, we add the @Any qualifier to the injection point, to suppress the default qualifier. (All beans have the qualifier @Any .)

import javax.enterprise.inject.Instance;


...


@Inject @Any Instance<PaymentProcessor> paymentProcessorSource;

Next, we need to obtain an instance of our qualifier type. Since annotations are interfaces, we can’t just write new Asynchronous(). It’s also quite tedious to create a concrete implementation of an annotation type from scratch. Instead, CDI lets us obtain a qualifier instance by subclassing the helper class AnnotationLiteral.

class AsynchronousQualifier

extends AnnotationLiteral<Asynchronous> implements Asynchronous {}

In some cases, we can use an anonymous class:

PaymentProcessor p = paymentProcessorSource

   .select(new AnnotationLiteral<Asynchronous>() {});

However, we can’t use an anonymous class to implement a qualifier type with members.

Now, finally, we can pass the qualifier to the select() method of Instance.

Annotation qualifier = synchronously ?

      new SynchronousQualifier() : new AsynchronousQualifier();

PaymentProcessor p = anyPaymentProcessor.select(qualifier).get().process(payment);

There are certain kinds of dependent objects (beans with scope @Dependent) that need to know something about the object or injection point into which they are injected in order to be able to do what they do. For example:

A bean with scope @Dependent may inject an instance of InjectionPoint and access metadata relating to the injection point to which it belongs.

Let’s look at an example. The following code is verbose, and vulnerable to refactoring problems:

Logger log = Logger.getLogger(MyClass.class.getName());

This clever little producer method lets you inject a JDK Logger without explicitly specifying the log category:

import javax.enterprise.inject.spi.InjectionPoint;

import javax.enterprise.inject.Produces;


class LogFactory {


   @Produces Logger createLogger(InjectionPoint injectionPoint) {

      return Logger.getLogger(injectionPoint.getMember().getDeclaringClass().getName());

   }


}

We can now write:

@Inject Logger log;

Not convinced? Then here’s a second example. To inject HTTP parameters, we need to define a qualifier type:

@Qualifier

@Retention(RUNTIME)

@Target({TYPE, METHOD, FIELD, PARAMETER})

public @interface HttpParam {

   @Nonbinding public String value();

}

We would use this qualifier type at injection points as follows:

@HttpParam("username") @Inject String username;

@HttpParam("password") @Inject String password;

The following producer method does the work:

import javax.enterprise.inject.Produces;

import javax.enterprise.inject.spi.InjectionPoint;


class HttpParams


   @Produces @HttpParam("")

   String getParamValue(InjectionPoint ip) {

      ServletRequest request = (ServletRequest) FacesContext.getCurrentInstance().getExternalContext().getRequest();

      return request.getParameter(ip.getAnnotated().getAnnotation(HttpParam.class).value());

   }


}

Note that acquiring of the request in this example is JSF-centric. For a more generic solution you could write your own producer for the request and have it injected as a method parameter.

Note also that the value() member of the HttpParam annotation is ignored by the container since it is annotated @Nonbinding.

The container provides a built-in bean that implements the InjectionPoint interface:

public interface InjectionPoint {

   public Type getType();

   public Set<Annotation> getQualifiers();

   public Bean<?> getBean();

   public Member getMember();

   public Annotated getAnnotated();

   public boolean isDelegate();

   public boolean isTransient();

}

CDI features an extensible context model. It’s possible to define new scopes by creating a new scope type annotation:

@ScopeType

@Retention(RUNTIME)

@Target({TYPE, METHOD})

public @interface ClusterScoped {}

Of course, that’s the easy part of the job. For this scope type to be useful, we will also need to define a Context object that implements the scope! Implementing a Context is usually a very technical task, intended for framework development only.

We can apply a scope type annotation to a bean implementation class to specify the scope of the bean:

@ClusterScoped

public class SecondLevelCache { ... }

Usually, you’ll use one of CDI’s built-in scopes.

CDI defines four built-in scopes:

For a web application that uses CDI, any servlet request has access to active request, session and application scopes. Furthermore, since CDI 1.1 the conversation context is active during every servlet request.

The request and application scopes are also active:

If the application tries to invoke a bean with a scope that does not have an active context, a ContextNotActiveException is thrown by the container at runtime.

Managed beans with scope @SessionScoped or @ConversationScoped must be serializable, since the container passivates the HTTP session from time to time.

Three of the four built-in scopes should be extremely familiar to every Java EE developer, so let’s not waste time discussing them here. One of the scopes, however, is new.

The conversation scope is a bit like the traditional session scope in that it holds state associated with a user of the system, and spans multiple requests to the server. However, unlike the session scope, the conversation scope:

A conversation represents a task—a unit of work from the point of view of the user. The conversation context holds state associated with what the user is currently working on. If the user is doing multiple things at the same time, there are multiple conversations.

The conversation context is active during any servlet request (since CDI 1.1). Most conversations are destroyed at the end of the request. If a conversation should hold state across multiple requests, it must be explicitly promoted to a long-running conversation.

In addition to the four built-in scopes, CDI also supports two pseudo-scopes. The first is the singleton pseudo-scope, which we specify using the annotation @Singleton.

You can guess what "singleton" means here. It means a bean that is instantiated once. Unfortunately, there’s a little problem with this pseudo-scope. Beans with scope @Singleton don’t have a proxy object. Clients hold a direct reference to the singleton instance. So we need to consider the case of a client that can be serialized, for example, any bean with scope @SessionScoped or @ConversationScoped, any dependent object of a bean with scope @SessionScoped or @ConversationScoped, or any stateful session bean.

Now, if the singleton instance is a simple, immutable, serializable object like a string, a number or a date, we probably don’t mind too much if it gets duplicated via serialization. However, that makes it stop being a true singleton, and we may as well have just declared it with the default scope.

There are several ways to ensure that the singleton bean remains a singleton when its client gets serialized:

A fourth, better solution is to instead use @ApplicationScoped, allowing the container to proxy the bean, and take care of serialization problems automatically.

Finally, CDI features the so-called dependent pseudo-scope. This is the default scope for a bean which does not explicitly declare a scope type.

For example, this bean has the scope type @Dependent:

public class Calculator { ... }

An instance of a dependent bean is never shared between different clients or different injection points. It is strictly a dependent object of some other object. It is instantiated when the object it belongs to is created, and destroyed when the object it belongs to is destroyed.

If a Unified EL expression refers to a dependent bean by EL name, an instance of the bean is instantiated every time the expression is evaluated. The instance is not reused during any other expression evaluation.

Beans with scope @Dependent don’t need a proxy object. The client holds a direct reference to its instance.

CDI makes it easy to obtain a dependent instance of a bean, even if the bean is already declared as a bean with some other scope type.