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:

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:

Where Translator is the EJB local interface:

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

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:

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:

A bean can only have one injectable constructor.

Initializer method parameter injection:

And direct field injection:

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:

This is a case where the @Inject annotation is not required at the injection point. The same is true for observer methods (which we’ll meet in Events) and disposer methods.

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:

Where @Synchronous and @Asynchronous are qualifier annotations:

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

Using field injection:

Using initializer method injection:

Using constructor injection:

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:

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:

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:

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

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

An injection point may specify multiple qualifiers:

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

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:

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. From CDI 1.1 onwards the alternative can be enabled for the whole application using @Priority annotation.

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:

Just remember: "There can be only one."

On the other hand, if you really do have an optional or multivalued injection point, you should change the type of your injection point to Instance, as we’ll see in Obtaining a contextual instance by programmatic lookup.

Now there’s one more issue you need to be aware of when using the dependency injection service.

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:

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

Qualifiers can be specified in one of two ways:

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

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 .)

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.

In some cases, we can use an anonymous class:

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.

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:

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

We can now write:

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

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

The following producer method does the work:

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:

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

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:

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 no 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:

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.

The built-in qualifier @New allows us to obtain a dependent object of a specified class.

The class must be a valid managed bean or session bean, but need not be an enabled bean.

This works even if Calculator is already declared with a different scope type, for example:

So the following injected attributes each get a different instance of Calculator:

The calculator field has a conversation-scoped instance of Calculator injected. The newCalculator field has a new instance of Calculator injected, with a lifecycle that is bound to the owning PaymentCalc.

This feature is particularly useful with producer methods, as we’ll see in Producer methods.

The scope of the producer method defaults to @Dependent, and so it will be called every time the container injects this field or any other field that resolves to the same producer method. Thus, there could be multiple instances of the PaymentStrategy object for each user session.

To change this behavior, we can add a @SessionScoped annotation to the method.

Now, when the producer method is called, the returned PaymentStrategy will be bound to the session context. The producer method won’t be called again in the same session.

There’s one potential problem with the code above. The implementations of CreditCardPaymentStrategy are instantiated using the Java new operator. Objects instantiated directly by the application can’t take advantage of dependency injection and don’t have interceptors.

If this isn’t what we want, we can use dependency injection into the producer method to obtain bean instances:

Wait, what if CreditCardPaymentStrategy is a request-scoped bean? Then the producer method has the effect of "promoting" the current request scoped instance into session scope. This is almost certainly a bug! The request scoped object will be destroyed by the container before the session ends, but the reference to the object will be left "hanging" in the session scope. This error will not be detected by the container, so please take extra care when returning bean instances from producer methods!

There’s at least three ways we could go about fixing this bug. We could change the scope of the CreditCardPaymentStrategy implementation, but this would affect other clients of that bean. A better option would be to change the scope of the producer method to @Dependent or @RequestScoped.

But a more common solution is to use the special @New qualifier annotation.

Consider the following producer method:

Then a new dependent instance of CreditCardPaymentStrategy will be created, passed to the producer method, returned by the producer method and finally bound to the session context. The dependent object won’t be destroyed until the Preferences object is destroyed, at the end of the session.

Some producer methods return objects that require explicit destruction. For example, somebody needs to close this JDBC connection:

Destruction can be performed by a matching disposer method, defined by the same class as the producer method:

The disposer method must have at least one parameter, annotated @Disposes, with the same type and qualifiers as the producer method. The disposer method is called automatically when the context ends (in this case, at the end of the request), and this parameter receives the object produced by the producer method. If the disposer method has additional method parameters, the container will look for a bean that satisfies the type and qualifiers of each parameter and pass it to the method automatically.

Since CDI 1.1 disposer methods may be used for destroying not only objects produced by producer methods but also objects producer by producer fields.

Suppose we want to declare that some of our beans are transactional. The first thing we need is an interceptor binding type to specify exactly which beans we’re interested in:

Now we can easily specify that our ShoppingCart is a transactional object:

Or, if we prefer, we can specify that just one method is transactional:

That’s great, but somewhere along the line we’re going to have to actually implement the interceptor that provides this transaction management aspect. All we need to do is create a standard interceptor, and annotate it @Interceptor and @Transactional.

Interceptors can take advantage of dependency injection:

Multiple interceptors may use the same interceptor binding type.

By default, all interceptors are disabled. We need to enable our interceptor. We can do it using beans.xml descriptor of a bean archive. However, this activation only applies to the beans in that archive. From CDI 1.1 onwards the interceptor can be enabled for the whole application using @Priority annotation.

Whoah! Why the angle bracket stew?

Well, having the XML declaration is actually a good thing. It solves two problems:

Having two interceptors without @Priority, we could specify that our security interceptor runs before our transaction interceptor.

Or we could turn them both off in our test environment by simply not mentioning them in beans.xml! Ah, so simple.

It gets quite tricky when used along with interceptors annotated with @Priority. Interceptors enabled using @Priority are called before interceptors enabled using beans.xml, the lower priority values are called first.

Suppose we want to add some extra information to our @Transactional annotation:

CDI will use the value of requiresNew to choose between two different interceptors, TransactionInterceptor and RequiresNewTransactionInterceptor.

Now we can use RequiresNewTransactionInterceptor like this:

But what if we only have one interceptor and we want the container to ignore the value of requiresNew when binding interceptors? Perhaps this information is only useful for the interceptor implementation. We can use the @Nonbinding annotation:

Usually we use combinations of interceptor bindings types to bind multiple interceptors to a bean. For example, the following declaration would be used to bind TransactionInterceptor and SecurityInterceptor to the same bean:

However, in very complex cases, an interceptor itself may specify some combination of interceptor binding types:

Then this interceptor could be bound to the checkout() method using any one of the following combinations:

One limitation of the Java language support for annotations is the lack of annotation inheritance. Really, annotations should have reuse built in, to allow this kind of thing to work:

Well, fortunately, CDI works around this missing feature of Java. We may annotate one interceptor binding type with other interceptor binding types (termed a meta-annotation). The interceptor bindings are transitive — any bean with the first interceptor binding inherits the interceptor bindings declared as meta-annotations.

Now, any bean annotated @Action will be bound to both TransactionInterceptor and SecurityInterceptor. (And even TransactionalSecureInterceptor, if it exists.)

The @Interceptors annotation defined by the Interceptors specification (and used by the Managed Beans and EJB specifications) is still supported in CDI.

However, this approach suffers the following drawbacks:

Therefore, we recommend the use of CDI-style interceptor bindings.

Decorators have a special injection point, called the delegate injection point, with the same type as the beans they decorate, and the annotation @Delegate. There must be exactly one delegate injection point, which can be a constructor parameter, initializer method parameter or injected field.

A decorator is bound to any bean which:

This delegate injection point specifies that the decorator is bound to all beans that implement Account:

A delegate injection point may specify any number of qualifier annotations. The decorator will only be bound to beans with the same qualifiers.

The decorator may invoke the delegate object, which has much the same effect as calling InvocationContext.proceed() from an interceptor. The main difference is that the decorator can invoke any business method on the delegate object.

By default, all decorators are disabled. We need to enable our decorator. We can do it using beans.xml descriptor of a bean archive. However, this activation only applies to the beans in that archive. From CDI 1.1 onwards the decorator can be enabled for the whole application using @Priority annotation.

This declaration serves the same purpose for decorators that the <interceptors> declaration serves for interceptors:

Decorators enabled using @Priority are called before decorators enabled using beans.xml, the lower priority values are called first.

The event object carries state from producer to consumer. The event object is nothing more than an instance of a concrete Java class. (The only restriction is that an event type may not contain type variables). An event may be assigned qualifiers, which allows observers to distinguish it from other events of the same type. The qualifiers function like topic selectors, allowing an observer to narrow the set of events it observes.

An event qualifier is just a normal qualifier, defined using @Qualifier. Here’s an example:

An observer method is a method of a bean with a parameter annotated @Observes.

The annotated parameter is called the event parameter. The type of the event parameter is the observed event type, in this case Document. The event parameter may also specify qualifiers.

An observer method need not specify any event qualifiers—in this case it is interested in every event whose type is assignable to the observed event type. Such observer will trigger on both events shown below:

If the observer does specify qualifiers, it will be notified of an event if the event object is assignable to the observed event type, and if the set of observed event qualifiers is a subset of all the event qualifiers of the event.

The observer method may have additional parameters, which are injection points:

Event producers fire events using an instance of the parameterized Event interface. An instance of this interface is obtained by injection:

A producer raises events by calling the fire() method of the Event interface, passing the event object:

This particular event will be delivered to every observer method that:

The container simply calls all the observer methods, passing the event object as the value of the event parameter. If any observer method throws an exception, the container stops calling observer methods, and the exception is rethrown by the fire() method.

Qualifiers can be applied to an event in one of two ways:

Specifying the qualifiers at the injection point is far simpler:

Then, every event fired via this instance of Event has the event qualifier @Updated. The event is delivered to every observer method that:

The downside of annotating the injection point is that we can’t specify the qualifier dynamically. CDI lets us obtain a qualifier instance by subclassing the helper class AnnotationLiteral. That way, we can pass the qualifier to the select() method of Event.

Events can have multiple event qualifiers, assembled using any combination of annotations at the Event injection point and qualifier instances passed to the select() method.

By default, if there is no instance of an observer in the current context, the container will instantiate the observer in order to deliver an event to it. This behavior isn’t always desirable. We may want to deliver events only to instances of the observer that already exist in the current contexts.

A conditional observer is specified by adding receive = IF_EXISTS to the @Observes annotation.

An event qualifier type may have annotation members:

The member value is used to narrow the messages delivered to the observer:

Event qualifier type members may be specified statically by the event producer, via annotations at the event notifier injection point:

Alternatively, the value of the event qualifier type member may be determined dynamically by the event producer. We start by writing an abstract subclass of AnnotationLiteral:

The event producer passes an instance of this class to select():

Event qualifiers may be combined, for example:

An observer method is only notified if all the observed qualifiers are specified when the event is fired. Assume the following observers in this example:

All of these observer methods will be notified.

However, if there were also an observer method:

It would not be notified, as @Personal is not a qualifier of the event being fired.

Transactional observers receive their event notifications during the before or after completion phase of the transaction in which the event was raised. For example, the following observer method needs to refresh a query result set that is cached in the application context, but only when transactions that update the Category tree succeed:

There are five kinds of transactional observers:

Transactional observers are very important in a stateful object model because state is often held for longer than a single atomic transaction.

Imagine that we have cached a JPA query result set in the application scope:

From time to time, a Product is created or deleted. When this occurs, we need to refresh the Product catalog. But we should wait until after the transaction completes successfully before performing this refresh!

The bean that creates and deletes `Product`s could raise events, for example:

And now Catalog can observe the events after successful completion of the transaction:

A stereotype may specify a default scope for beans annotated with the stereotype. For example:

A particular action may still override this default if necessary:

Naturally, overriding a single default isn’t much use. But remember, stereotypes can define more than just the default scope.

A stereotype may specify a set of interceptor bindings to be inherited by all beans with that stereotype.

This helps us get technical concerns, like transactions and security, even further away from the business code!

We can specify that all beans with a certain stereotype have a defaulted EL name when a name is not explicitly defined for that bean. All we need to do is add an empty @Named annotation:

Now, the LoginAction bean will have the defaulted name loginAction.

A stereotype can indicate that all beans to which it is applied are `@Alternative`s. An alternative stereotype lets us classify beans by deployment scenario.

We can apply an alternative stereotype to a whole set of beans, and activate them all with one line of code in beans.xml.

This may blow your mind a bit, but stereotypes may declare other stereotypes, which we’ll call stereotype stacking. You may want to do this if you have two distinct stereotypes which are meaningful on their own, but in other situation may be meaningful when combined.

Here’s an example that combines the @Action and @Auditable stereotypes:

CDI defines one standard stereotype, @Model, which is expected to be used frequently in web applications:

Instead of using JSF managed beans, just annotate a bean @Model, and use it directly in your JSF view!

CDI lets you override the implementation of a bean type at deployment time using an alternative. For example, the following bean provides a default implementation of the PaymentProcessor interface:

But in our staging environment, we don’t really want to submit payments to the external system, so we override that implementation of PaymentProcessor with a different bean:

or

We’ve already seen how we can enable this alternative by listing its class in the beans.xml descriptor.

But suppose we have many alternatives in the staging environment. It would be much more convenient to be able to enable them all at once. So let’s make @Staging an @Alternative stereotype and annotate the staging beans with this stereotype instead. You’ll see how this level of indirection pays off. First, we create the stereotype:

Then we replace the @Alternative annotation on our bean with @Staging:

Finally, we activate the @Staging stereotype in the beans.xml descriptor:

Now, no matter how many staging beans we have, they will all be enabled at once.

When we enable an alternative, does that mean the default implementation is disabled? Well, not exactly. If the default implementation has a qualifier, for instance @LargeTransaction, and the alternative does not, you could still inject the default implementation.

So we haven’t completely replaced the default implementation in this deployment of the system. The only way one bean can completely override a second bean at all injection points is if it implements all the bean types and declares all the qualifiers of the second bean. However, if the second bean declares a producer method or observer method, then even this is not enough to ensure that the second bean is never called! We need something extra.

CDI provides a special feature, called specialization, that helps the developer avoid these traps. Specialization is a way of informing the system of your intent to completely replace and disable an implementation of a bean.

When the goal is to replace one bean implementation with a second, to help prevent developer error, the first bean may:

explicitly declare that it specializes the second bean:

When an enabled bean specializes another bean, the other bean is never instantiated or called by the container. Even if the other bean defines a producer or observer method, the method will never be called.

So why does specialization work, and what does it have to do with inheritance?

Since we’re informing the container that our alternative bean is meant to stand in as a replacement for the default implementation, the alternative implementation automatically inherits all qualifiers of the default implementation. Thus, in our example, MockCreditCardPaymentProcessor inherits the qualifiers @Default and @CreditCard.

Furthermore, if the default implementation declares a bean EL name using @Named, the name is inherited by the specializing alternative bean.

The CDI specification uses the term resource to refer, generically, to any of the following kinds of object which might be available in the Java EE component environment:

We declare a resource by annotating a producer field with a component environment injection annotation: @Resource, @EJB, @PersistenceContext, @PersistenceUnit or @WebServiceRef.

The field may be static (but not final).

A resource declaration really contains two pieces of information:

These resources can now be injected in the usual way.

The bean type and qualifiers of the resource are determined by the producer field declaration.

It might seem like a pain to have to write these extra producer field declarations, just to gain an additional level of indirection. You could just as well use component environment injection directly, right? But remember that you’re going to be using resources like the EntityManager in several different beans. Isn’t it nicer and more typesafe to write

instead of

all over the place?

In the Java EE environment, the container provides the following built-in beans, all with the qualifier @Default:

All managed beans may take advantage of Java EE component environment injection using @Resource, @EJB, @PersistenceContext, @PersistenceUnit and @WebServiceRef. We’ve already seen a couple of examples of this, though we didn’t pay much attention at the time:

The Java EE @PostConstruct and @PreDestroy callbacks are also supported for all managed beans. The @PostConstruct method is called after all injection has been performed.

Of course, we advise that component environment injection be used to define CDI resources, and that typesafe injection be used in application code.

It’s easy to use a bean from a servlet in Java EE. Simply inject the bean using field or initializer method injection.

Since instances of servlets are shared across all incoming threads, the bean client proxy takes care of routing method invocations from the servlet to the correct instances of Credentials and Login for the current request and HTTP session.

CDI injection applies to all EJBs, even when they aren’t CDI beans. In particular, you can use CDI injection in message-driven beans, which are by nature not contextual objects.

You can even use interceptor bindings for message-driven Beans.

Please note that there is no session or conversation context available when a message is delivered to a message-driven bean. Only @RequestScoped and @ApplicationScoped beans are available.

But how about beans which send JMS messages?

Sending messages using JMS can be quite complex, because of the number of different objects you need to deal with. For queues we have Queue, QueueConnectionFactory, QueueConnection, QueueSession and QueueSender. For topics we have Topic, TopicConnectionFactory, TopicConnection, TopicSession and TopicPublisher. Each of these objects has its own lifecycle and threading model that we need to worry about.

You can use producer fields and methods to prepare all of these resources for injection into a bean:

In this example, we can just inject the prepared MessageProducer, Connection or QueueSession:

The lifecycle of the injected JMS objects is completely controlled by the container.

CDI doesn’t define any special deployment archive. You can package CDI beans in JARs, EJB JARs or WARs—any deployment location in the application classpath. However, the archive must be a "bean archive".

Unlike CDI 1.0, the CDI 1.1 specification recognizes two types of bean archives. The type determines the way the container discovers CDI beans in the archive.

The first step in creating a portable extension is to write a class that implements Extension. This marker interface does not define any methods, but it’s needed to satisfy the requirements of Java SE’s service provider architecture.

Next, we need to register our extension as a service provider by creating a file named META-INF/services/javax.enterprise.inject.spi.Extension, which contains the name of our extension class:

An extension is not a bean, exactly, since it is instantiated by the container during the initialization process, before any beans or contexts exist. However, it can be injected into other beans once the initialization process is complete.

And, like beans, extensions can have observer methods. Usually, the observer methods observe container lifecycle events.

During the initialization process, the container fires a series of events, including:

Extensions may observe these events:

In fact, the extension can do a lot more than just observe. The extension is permitted to modify the container’s metamodel and more. Here’s a very simple example:

The observer method may inject a BeanManager

An extension observer method is not allowed to inject any other object.

The nerve center for extending CDI is the BeanManager object. The BeanManager interface lets us obtain beans, interceptors, decorators, observers and contexts programmatically.

Any bean or other Java EE component which supports injection can obtain an instance of BeanManager via injection:

Alternatively, a BeanManager reference may be obtained from CDI via a static method call.

Java EE components may obtain an instance of BeanManager from JNDI by looking up the name java:comp/BeanManager. Any operation of BeanManager may be called at any time during the execution of the application.

Let’s study some of the interfaces exposed by the BeanManager.

Application components which cannot obtain a BeanManager reference via injection nor JNDI lookup can get the reference from the javax.enterprise.inject.spi.CDI class via a static method call:

The CDI class can be used directly to programmatically lookup CDI beans as described in Obtaining a contextual instance by programmatic lookup

The first thing that a framework developer is going to look for in the portable extension SPI is a way to inject CDI beans into objects which are not under the control of CDI. The InjectionTarget interface makes this very easy.

Instances of the interface Bean represent beans. There is an instance of Bean registered with the BeanManager object for every bean in the application. There are even Bean objects representing interceptors, decorators and producer methods.

The BeanAttributes interface exposes all the interesting things we discussed in The anatomy of a bean.

The Bean interface extends the BeanAttributes interface and defines everything the container needs to manage instances of a certain bean.

There’s an easy way to find out what beans exist in the application:

The Bean interface makes it possible for a portable extension to provide support for new kinds of beans, beyond those defined by the CDI specification. For example, we could use the Bean interface to allow objects managed by another framework to be injected into beans.

The most common kind of CDI portable extension registers a bean (or beans) with the container.

In this example, we make a framework class, SecurityManager available for injection. To make things a bit more interesting, we’re going to delegate back to the container’s InjectionTarget to perform instantiation and injection upon the SecurityManager instance.

But a portable extension can also mess with beans that are discovered automatically by the container.

One of the most interesting things that an extension class can do is process the annotations of a bean class before the container builds its metamodel.

Let’s start with an example of an extension that provides support for the use of @Named at the package level. The package-level name is used to qualify the EL names of all beans defined in that package. The portable extension uses the ProcessAnnotatedType event to wrap the AnnotatedType object and override the value() of the @Named annotation.

Here’s a second example, which adds the @Alternative annotation to any class which implements a certain Service interface.

The AnnotatedType is not the only thing that can be wrapped by an extension.

Wrapping an AnnotatedType is a low-level approach to overriding CDI metadata by adding, removing or replacing annotations. Since version 1.1, CDI provides a higher-level facility for overriding attributes of beans discovered by the CDI container.

The BeanAttributes interface exposes attributes of a bean. The container fires a ProcessBeanAttributes event for each enabled bean, interceptor and decorator before this object is registered. Similarly to the ProcessAnnotatedType, this event allows an extension to modify attributes of a bean or to veto the bean entirely.

The BeanManager provides two utility methods for creating the BeanAttributes object from scratch:

The InjectionTarget interface exposes operations for producing and disposing an instance of a component, injecting its dependencies and invoking its lifecycle callbacks. A portable extension may wrap the InjectionTarget for any Java EE component that supports injection, allowing it to intercept any of these operations when they are invoked by the container.

Here’s a CDI portable extension that reads values from properties files and configures fields of Java EE components, including servlets, EJBs, managed beans, interceptors and more. In this example, properties for a class such as org.mydomain.blog.Blogger go in a resource named org/mydomain/blog/Blogger.properties, and the name of a property must match the name of the field to be configured. So Blogger.properties could contain:

The portable extension works by wrapping the containers InjectionTarget and setting field values from the inject() method.

CDI provides a way to override the metadata of an InjectionPoint. This works similarly to how metadata of a bean may be overridden using BeanAttributes.

For every injection point of each component supporting injection CDI fires an event of type javax.enterprise.inject.spi.ProcessInjectionPoint

An extension may either completely override the injection point metadata or alter it by wrapping the InjectionPoint object obtained from ProcessInjectionPoint.getInjectionPoint()

There’s a lot more to the portable extension SPI than what we’ve discussed here. Check out the CDI spec or Javadoc for more information. For now, we’ll just mention one more extension point.

An event of type javax.enterprise.inject.spi.AfterTypeDiscovery is fired when the container has fully completed the type discovery process and before it begins the bean discovery process.

This event exposes a list of enabled alternatives, interceptors and decorators. Extensions may manipulate these collections directly to add, remove or change the order of the enabled records.

In addition, an AnnotatedType can be added to the types which will be scanned during bean discovery, with an identifier, which allows multiple annotated types, based on the same underlying type, to be defined.

The Context and AlterableContext interface support addition of new scopes to CDI, or extension of the built-in scopes to new environments.

For example, we might implement Context to add a business process scope to CDI, or to add support for the conversation scope to an application that uses Wicket.

AlterableContext was introduced in CDI 1.1. The destroy method allows an application to remove instances of contextual objects from a context.

For more information on implementing a custom context see this blog post.