JBoss Weld CDI for Java Platform

In most cases, beans acquire references to other beans through dependency injection. The point at which a bean is injected will specify the type of that bean and a set of qualifiers. With the help of the bean type and qualifiers, Weld determines the implementation of a bean to provide for injection.

A bean type can be a class or interface that is visible to clients that wish to inject it. For instance, an EJB Session Bean implementation is not visible to clients, but its @Local interface is visible.

public class CandyStore extends CommonStore
implements Store<Candy> {
  ...
}

In this Java class, there are four bean types defined: CandyStore, CommonStore, Store<Candy>, and the implicit type java.lang.Object. An interesting point to note is that a parameterized type is considered a bean type by CDI, but only if it contains an actual type parameter and not a wildcard.

We are able to restrict which bean types are valid for any given Java class with the @Typed annotation by providing a defined set of bean types that can be accepted. We can restrict the types from the previous example to only Store<Candy> and the implicit java.lang.Object type, with the following:

@Typed(Store.class)
public class CandyStore extends CommonStore
implements Store<Candy> {
  ...
}

A qualifier allows us to disambiguate a type without the need to leave type-safety and revert to string-based names, which we all know are fodder for runtime errors. All we need for defining a qualifier is to create an annotation that is annotated with @Qualifier.

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

Here, we've defined a qualifier called User. Specifying RUNTIME retention informs the Java VM that we want the annotation information recorded in the class file of any bean that specifies this qualifier, so that it may be read at runtime. The values of TYPE, METHOD, PARAMETER, and FIELD specify valid locations within a bean where the qualifier may be placed.

With our qualifier annotation, we are now able to disambiguate an injection point. The following injection point has a bean type of Account and a qualifier of @User:

@Inject
@User
Account userAccount;

The Weld container searches for a bean that matches the same bean type and all the qualifiers and each injection point that has been defined. If Weld doesn't find exactly one match, an error is reported during startup that there is an ambiguous injection point, which is Weld's way of telling you that there are too many beans that match the bean type and qualifiers.

To inform Weld that a bean has a specific qualifier, we annotate the bean class with it. The following bean would match the injection point from the previous code snippet:

@User
public class UserAccount implements Account {
  ...
}

In the previous examples, we've utilized the CDI scopes that are provided for us, but what is a scope? A scope is the means by which a bean specifies its lifecycle and the visibility of its instances.

For instance, @SessionScoped binds a bean to a user session and is shared across all requests that execute in the context of that session.

A bean can be referenced from non-Java code if it supports Unified EL expressions, such as with JSF and JSP pages, but it requires an EL name to be defined.

The @Named annotation specifies the EL name for a bean, as follows:

@Named("book")
public class HistoryBook implements Serializable {
  ...
}

We can now access the bean in a JSF page:

<h:outputText value="#{book.isbn}" />

If we aren't particular about what EL name a bean is given, we can specify @Named without any value and it will default to the unqualified class name, with the first character converted to lower case. In the previous example, this would give us an EL name of historyBook.

If we need to vary which implementation is chosen depending on the deployment environment or some other factor, we can create an alternative bean that can be activated when needed.

For instance, if we want to create a mock or dummy implementation that is only used in testing environments, we can write the following:

@Alternative
public class DummyLogger extends LoggerImpl {
  ...
}

It's general practice to only annotate a bean with @Alternative when there is at least one other implementation of an interface it implements or any of its bean types, otherwise there wouldn't be anything for it to be an alternative of.

Alternatives are chosen by selecting an alternative in the CDI descriptor file, beans.xml, of the JAR or WAR that uses it.

This topic will be covered in greater detail in Chapter 2, Dependency Injection and Lookup.

As mentioned earlier, the Managed Beans specification was introduced in Java EE 6 to provide a common definition of a Managed Bean. All that's required to create a Managed Bean is to annotate it with @ManagedBean, though CDI doesn't require us to do so.

Earlier in this chapter, we covered the requirements for constructors of a Java class to be a Managed Bean, but the CDI specification states that it must also meet the following conditions:

According to the preceding conditions, Java Persistence API (JPA) entities are also Managed Beans! Trying to use entities as Managed Beans will cause runtime issues when attempting to persist Managed Beans that have been proxied by CDI.

Session Beans can take advantage of CDI just like any other bean, though there are a few restrictions due to Session Beans having their lifecycle managed separate to CDI.

Message-driven and entity beans are not contextual objects in the CDI sense, so they are not able to be injected into other beans. It is possible to inject beans into a message-driven bean, and use interceptors and decorators to utilize some of the CDI functionalities that are available.

As the EJB container controls the lifecycle of a stateless Session Bean and a singleton Session Bean, there is no need to specify any CDI scope for these, but a stateful Session Bean may use any scope it requires.

In these final two sections, we will introduce producers, both method and field, which can be used to provide a CDI bean that isn't a Java class, per se. Producers are often useful in a situation where it is not known during development which particular qualified bean instance needs to be used, and producers allow us to create a bean that depends on runtime information for its creation.

Producers provide a source for new bean instances. A producer will be invoked by Weld when there is no instance of that bean in the required context.

We will cover producers in detail in Chapter 5, Producers.

public class AccountManager {
  @Produces
  @User
  Account getUserAccount() {
    ...
  }
}

@Inject
@User
Account userAccount;

public class AccountManager {
  @Produces
  @User
  Account userAccount = ...;
}