# Weld - JSR-299 Reference Implementation

## JSR-299: The new Java standard for dependency injection and contextual lifecycle management

### Nicola Benaglia

Italian Translation

Spanish Translation

### Eun-Ju Ki,

Korean Translation

### Francesco Milesi

Italian Translation

### Sean Wu

Simplified Chinese Translation

A note about naming and nomenclature
I. Beans
1. Introduction
1.1. What is a bean?
1.2. Getting our feet wet
2.1. The anatomy of a bean
2.1.1. Bean types, qualifiers and dependency injection
2.1.2. Scope
2.1.3. EL name
2.1.4. Alternatives
2.1.5. Interceptor binding types
2.2. What kinds of classes are beans?
2.2.1. Managed beans
2.2.2. Session beans
2.2.3. Producer methods
2.2.4. Producer fields
3. JSF web application example
4. Dependency injection and programmatic lookup
4.1. Injection points
4.2. What gets injected
4.3. Qualifier annotations
4.4. The built-in qualifiers @Default and @Any
4.5. Qualifiers with members
4.6. Multiple qualifiers
4.7. Alternatives
4.8. Fixing unsatisfied and ambiguous dependencies
4.9. Client proxies
4.10. Obtaining a contextual instance by programmatic lookup
4.11. The InjectionPoint object
5. Scopes and contexts
5.1. Scope types
5.2. Built-in scopes
5.3. The conversation scope
5.3.1. Conversation demarcation
5.3.2. Conversation propagation
5.3.3. Conversation timeout
5.4. The singleton pseudo-scope
5.5. The dependent pseudo-scope
5.6. The @New qualifier
6. Getting started with Weld
6.1. Prerequisites
6.2. Deploying to JBoss AS
6.3. Deploying to GlassFish
6.4. Deploying to Apache Tomcat
6.4.1. Deploying with Ant
6.4.2. Deploying with Maven
6.5. Deploying to Jetty
7. Diving into the Weld examples
7.1. The numberguess example in depth
7.1.1. The numberguess example in Apache Tomcat or Jetty
7.2. The numberguess example for Java SE with Swing
7.2.1. Creating the Eclipse project
7.2.2. Running the example from Eclipse
7.2.3. Running the example from the command line
7.2.4. Understanding the code
7.3. The translator example in depth
III. Loose coupling with strong typing
8. Producer methods
8.1. Scope of a producer method
8.2. Injection into producer methods
8.3. Use of @New with producer methods
8.4. Disposer methods
9. Interceptors
9.1. Interceptor bindings
9.2. Implementing interceptors
9.3. Enabling interceptors
9.4. Interceptor bindings with members
9.5. Multiple interceptor binding annotations
9.6. Interceptor binding type inheritance
9.7. Use of @Interceptors
10. Decorators
10.1. Delegate object
10.2. Enabling decorators
11. Events
11.2. Event observers
11.3. Event producers
11.4. Conditional observer methods
11.5. Event qualifiers with members
11.6. Multiple event qualifiers
11.7. Transactional observers
12. Stereotypes
12.1. Default scope for a stereotype
12.2. Interceptor bindings for stereotypes
12.3. Name defaulting with stereotypes
12.4. Alternative stereotypes
12.5. Stereotype stacking
12.6. Built-in stereotypes
13. Specialization, inheritance and alternatives
13.1. Using alternative stereotypes
13.2. A minor problem with alternatives
13.3. Using specialization
14. Java EE component environment resources
14.1. Defining a resource
14.2. Typesafe resource injection
IV. CDI and the Java EE ecosystem
15. Java EE integration
15.1. Built-in beans
15.2. Injecting Java EE resources into a bean
15.3. Calling a bean from a servlet
15.4. Calling a bean from a message-driven bean
15.5. JMS endpoints
15.6. Packaging and deployment
16. Portable extensions
16.1. Creating an Extension
16.2. Container lifecycle events
16.3. The BeanManager object
16.4. The InjectionTarget interface
16.5. The Bean interface
16.6. Registering a Bean
16.7. Wrapping an AnnotatedType
16.8. Wrapping an InjectionTarget
16.9. The Context interface
17. Next steps
V. Weld Reference Guide
18. Application servers and environments supported by Weld
18.1. Using Weld with JBoss AS
18.2. GlassFish
18.3. Servlet containers (such as Tomcat or Jetty)
18.3.1. Tomcat
18.3.2. Jetty
18.4. Java SE
18.4.1. CDI SE Module
18.4.2. Bootstrapping CDI SE
18.4.4. Setting the Classpath
19. Context Management
19.1. Managing the built in contexts
20. Configuration
20.1. Excluding classes from scanning and deployment
A. Integrating Weld into other environments
A.1. The Weld SPI
A.1.1. Deployment structure
A.1.2. EJB descriptors
A.1.3. EE resource injection and resolution services
A.1.4. EJB services
A.1.5. JPA services
A.1.6. Transaction Services
A.1.7. Resource Services
A.1.8. Injection Services
A.1.9. Security Services
A.1.10. Bean Validation Services
A.1.11. Identifying the BDA being addressed
A.1.12. The bean store
A.1.13. The application context
A.1.14. Initialization and shutdown
A.2. The contract with the container

# Part I. Beans

The JSR-299 specification (CDI) defines a set of complementary services that help improve the structure of application code. CDI layers an enhanced lifecycle and interaction model over existing Java component types, including managed beans and Enterprise Java Beans. The CDI services provide:

• an improved lifecycle for stateful objects, bound to well-defined contexts,

• a typesafe approach to dependency injection,

• object interaction via an event notification facility,

• a better approach to binding interceptors to objects, along with a new kind of interceptor, called a decorator, that is more appropriate for use in solving business problems, and

• an SPI for developing portable extensions to the container.

The CDI services are a core aspect of the Java EE platform and include full support for Java EE modularity and the Java EE component architecture. But the specification does not limit the use of CDI to the Java EE environment. In the Java SE environment, the services might be provided by a standalone CDI implementation like Weld (see Section 18.4.1, “CDI SE Module”), or even by a container that also implements the subset of EJB defined for embedded usage by the EJB 3.1 specification. CDI is especially useful in the context of web application development, but the problems it solves are general development concerns and it is therefore applicable to a wide variety of application.

An object bound to a lifecycle context is called a bean. CDI includes built-in support for several different kinds of bean, including the following Java EE component types:

• managed beans, and

• EJB session beans.

Both managed beans and EJB session beans may inject other beans. But some other objects, which are not themselves beans in the sense used here, may also have beans injected via CDI. In the Java EE platform, the following kinds of component may have beans injected:

• message-driven beans,

• interceptors,

• servlets, servlet filters and servlet event listeners,

• JAX-WS service endpoints and handlers, and

• JSP tag handlers and tag library event listeners.

CDI relieves the user of an unfamiliar API of the need to answer the following questions:

• What is the lifecycle of this object?

• How many simultaneous clients can it have?

• Do I need to explicitly destroy it?

• Where should I keep the reference to it when I'm not currently using it?

• How can I define an alternative implementation, so that the implementation can vary at deployment time?

• How should I go about sharing this object between other objects?

CDI is more than a framework. It's a whole, rich programming model. The theme of CDI is loose-coupling with strong typing. Let's study what that phrase means.

A bean specifies only the type and semantics of other beans it depends upon. It need not be aware of the actual lifecycle, concrete implementation, threading model or other clients of any bean it interacts with. Even better, the concrete implementation, lifecycle and threading model of a bean may vary according to the deployment scenario, without affecting any client. This loose-coupling makes your code easier to maintain.

Events, interceptors and decorators enhance the loose-coupling inherent in this model:

• event notifications decouple event producers from event consumers,

• interceptors decouple technical concerns from business logic, and

• decorators allow business concerns to be compartmentalized.

What's even more powerful (and comforting) is that CDI provides all these facilities in a typesafe way. CDI never relies on string-based identifiers to determine how collaborating objects fit together. Instead, CDI uses the typing information that is already available in the Java object model, augmented using a new programming pattern, called qualifier annotations, to wire together beans, their dependencies, their interceptors and decorators, and their event consumers. Usage of XML descriptors is minimized to truly deployment-specific information.

But CDI isn't a restrictive programming model. It doesn't tell you how you should to structure your application into layers, how you should handle persistence, or what web framework you have to use. You'll have to decide those kinds of things for yourself.

CDI even provides a comprehensive SPI, allowing other kinds of object defined by future Java EE specifications or by third-party frameworks to be cleanly integrated with CDI, take advantage of the CDI services, and interact with any other kind of bean.

CDI was influenced by a number of existing Java frameworks, including Seam, Guice and Spring. However, CDI has its own, very distinct, character: more typesafe than Seam, more stateful and less XML-centric than Spring, more web and enterprise-application capable than Guice. But it couldn't have been any of these without inspiration from the frameworks mentioned and lots of collaboration and hard work by the JSR-299 Expert Group (EG).

Finally, CDI is a Java Community Process (JCP) standard. Java EE 6 requires that all compliant application servers provide support for JSR-299 (even in the web profile).

## Chapter 1. Introduction

So you're keen to get started writing your first bean? Or perhaps you're skeptical, wondering what kinds of hoops the CDI specification will make you jump through! The good news is that you've probably already written and used hundreds, perhaps thousands of beans. CDI just makes it easier to actually use them to build an application!

## 1.2. Getting our feet wet

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:

@Named @RequestScoped
public class TranslateController {
@Inject TextTranslator textTranslator;

private String inputText;
private String translation;

// JSF action method, perhaps
public void translate() {
translation = textTranslator.translate(inputText);
}

public String getInputText() {
return inputText;
}

public void setInputText(String text) {
this.inputText = text;
}

public String getTranslation() {
return translation;
}
}
 Field injection of TextTranslator instance

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

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

## Chapter 2. More about beans

A bean is usually an application class that contains business logic. It may be called directly from Java code, or it may be invoked via the Unified EL. A bean may access transactional resources. Dependencies between beans are managed automatically by the container. Most beans are stateful and contextual. The lifecycle of a bean is always managed by the container.

Let's back up a second. What does it really mean to be contextual? Since beans may be stateful, it matters which bean instance I have. Unlike a stateless component model (for example, stateless session beans) or a singleton component model (such as servlets, or singleton beans), different clients of a bean see the bean in different states. The client-visible state depends upon which instance of the bean the client has a reference to.

However, like a stateless or singleton model, but unlike stateful session beans, the client does not control the lifecycle of the instance by explicitly creating and destroying it. Instead, the scope of the bean determines:

• the lifecycle of each instance of the bean and

• which clients share a reference to a particular instance of the bean.

For a given thread in a CDI application, there may be an active context associated with the scope of the bean. This context may be unique to the thread (for example, if the bean is request scoped), or it may be shared with certain other threads (for example, if the bean is session scoped) or even all other threads (if it is application scoped).

Clients (for example, other beans) executing in the same context will see the same instance of the bean. But clients in a different context may see a different instance (depending on the relationship between the contexts).

One great advantage of the contextual model is that it allows stateful beans to be treated like services! The client need not concern itself with managing the lifecycle of the bean it's using, nor does it even need to know what that lifecycle is. Beans interact by passing messages, and the bean implementations define the lifecycle of their own state. The beans are loosely coupled because:

• they interact via well-defined public APIs

• their lifecycles are completely decoupled

We can replace one bean with another different bean that implements the same interface and has a different lifecycle (a different scope) without affecting the other bean implementation. In fact, CDI defines a simple facility for overriding bean implementations at deployment time, as we will see in Section 4.7, “Alternatives”.

Note that not all clients of a bean are beans themselves. Other objects such as servlets or message-driven beans—which are by nature not injectable, contextual objects—may also obtain references to beans by injection.

## 2.1. The anatomy of 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.

### 2.1.1. Bean types, qualifiers and dependency injection

Beans usually acquire references to other beans via dependency injection. Any injected attribute specifies a "contract" that must be satisfied by the bean to be injected. The contract is:

A bean type is a user-defined class or interface; a type that is client-visible. If the bean is an EJB session bean, the bean type is the @Local interface or bean-class local view. A bean may have multiple bean types. For example, the following bean has four bean types:

public class BookShop
implements Shop<Book> {
...
}

The bean types are BookShop, Business and Shop<Book>, as well as the implicit type java.lang.Object. (Notice that a parameterized type is a legal bean type).

Meanwhile, this session bean has only the local interfaces BookShop, Auditable and java.lang.Object as bean types, since the bean class, BookShopBean is not a client-visible type.

@Stateful
public class BookShopBean
implements BookShop, Auditable {
...
}

Bean types may be restricted to an explicit set by annotating the bean with the @Typed annotation and listing the classes that should be bean types. For instance, the bean types of this bean have been restricted to Shop<Book>, together with java.lang.Object:

@Typed(Shop.class)
public class BookShop
implements Shop<Book> {
...
}

Sometimes, a bean type alone does not provide enough information for the container to know which bean to inject. For instance, suppose we have two implementations of the PaymentProcessor interface: CreditCardPaymentProcessor and DebitPaymentProcessor. Injecting a field of type PaymentProcessor introduces an ambiguous condition. In these cases, the client must specify some additional quality of the implementation it is interested in. We model this kind of "quality" using a qualifier.

A qualifier is a user-defined annotation that is itself annotated @Qualifer. A qualifier annotation is an extension of the type system. It lets us disambiguate a type without having to fall back to string-based names. Here's an example of a qualifier annotation:

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

You may not be used to seeing the definition of an annotation. In fact, this might be the first time you've encountered one. With CDI, annotation definitions will become a familiar artifact as you'll be creating them from time to time.

## Note

Pay attention to the names of the built-in annotations in CDI and EJB. You'll notice that they are often adjectives. We encourage you to follow this convention when creating your custom annotations, since they serve to describe the behaviors and roles of the class.

Now that we have defined a qualifier annotation, we can use it to disambiguate an injection point. The following injection point has the bean type PaymentProcessor and qualifier @CreditCard:

@Inject @CreditCard PaymentProcessor paymentProcessor

For each injection point, the container searches for a bean which satisfies the contract, one which has the bean type and all the qualifiers. If it finds exactly one matching bean, it injects an instance of that bean. If it doesn't, it reports an error to the user.

How do we specify that qualifiers of a bean? By annotating the bean class, of course! The following bean has the qualifier @CreditCard and implements the bean type PaymentProcessor. Therefore, it satisfies our qualified injection point:

@CreditCard
public class CreditCardPaymentProcessor
implements PaymentProcessor { ... }

## Note

If a bean or an injection point does not explicitly specify a qualifier, it has the default qualifier, @Default.

That's not quite the end of the story. CDI also defines a simple resolution rule that helps the container decide what to do if there is more than one bean that satisfies a particular contract. We'll get into the details in Chapter 4, Dependency injection and programmatic lookup.

### 2.1.3. EL name

If you want to reference a bean in non-Java code that supports Unified EL expressions, for example, in a JSP or JSF page, you must assign the bean an EL name.

The EL name is specified using the @Named annotation, as shown here:

public @SessionScoped @Named("cart")
class ShoppingCart implements Serializable { ... }

Now we can easily use the bean in any JSF or JSP page:


<h:dataTable value="#{cart.lineItems}" var="item">
...
</h:dataTable>


We can let CDI choose a name for us by leaving off the value of the @Named annotation:

public @SessionScoped @Named
class ShoppingCart implements Serializable { ... }

The name defaults to the unqualified class name, decapitalized; in this case, shoppingCart.

## Chapter 3. JSF web application example

Let's illustrate these ideas with a full example. We're going to implement user login/logout for an application that uses JSF. First, we'll define a request-scoped bean to hold the username and password entered during login, with constraints defined using annotations from the Bean Validation specification:

@Named @RequestScoped
public class Credentials {

@NotNull @Length(min=3, max=25)

@NotNull @Length(min=6, max=20)
}

This bean is bound to the login prompt in the following JSF form:

<h:form>
<f:validateBean>
</f:validateBean>
</h:panelGrid>
</h:form>

Users are represented by a JPA entity:

@Entity
public class User {
private @NotNull @Length(min=3, max=25) @Id String username;
private @NotNull @Length(min=6, max=20) String password;

}

(Note that we're also going to need a persistence.xml file to configure the JPA persistence unit containing User.)

The actual work is done by a session-scoped bean that maintains information about the currently logged-in user and exposes the User entity to other beans:

@SessionScoped @Named
public class Login implements Serializable {

@Inject Credentials credentials;
@Inject @UserDatabase EntityManager userDatabase;

private User user;

List<User> results = userDatabase.createQuery(
.getResultList();

if (!results.isEmpty()) {
user = results.get(0);
}
else {
}
}

public void logout() {
user = null;
}

public boolean isLoggedIn() {
return user != null;
}

@Produces @LoggedIn User getCurrentUser() {
return user;
}

}

@LoggedIn and @UserDatabase are custom qualifier annotations:

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

We need an adaptor bean to expose our typesafe EntityManager:

class UserDatabaseProducer {
@Produces @UserDatabase @PersistenceContext
static EntityManager userDatabase;
}

Now DocumentEditor, or any other bean, can easily inject the current user:

public class DocumentEditor {
@Inject Document document;
@Inject @LoggedIn User currentUser;
@Inject @DocumentDatabase EntityManager docDatabase;

public void save() {
document.setCreatedBy(currentUser);
docDatabase.persist(document);
}
}

Or we can reference the current user in a JSF view:


</h:panelGroup>


Hopefully, this example gave you a taste of the CDI programming model. In the next chapter, we'll explore dependency injection in greater depth.

## Chapter 4. Dependency injection and programmatic lookup

One of the most significant features of CDI—certainly the most recognized—is dependency injection; excuse me, typesafe dependency injection.

## 4.1. Injection points

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);
}

## 4.3. Qualifier annotations

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 alterative implementations of @Asynchronous PaymentProcessor!

## 4.5. Qualifiers with members

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 appling 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 "";
}

## 4.6. Multiple qualifiers

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

## 4.7. Alternatives

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. This activation only applies to the beans in that archive.


<beans
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
<alternatives>
<class>org.mycompany.mock.MockPaymentProcessor</class>
</alternatives>
</beans>


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.

## 4.8. Fixing unsatisfied and ambiguous dependencies

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:

See this FAQ for step-by-step instructions for how to resolve an ambigous resolution exception between a raw bean type and a producer method that returns the same bean type.

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 Section 4.10, “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.

## 4.10. Obtaining a contextual instance by programmatic lookup

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

@Inject @Any Instance<PaymentProcessor> paymentProcessorSource;

Next, we need to obtain an instance of our qualifier type. Since annotatons 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.

abstract 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);

## 4.11. The InjectionPoint object

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:

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:

@BindingType
@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") String username;
@HttpParam("password") String password;

The following producer method does the work:

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 prodcuer 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();
}

## Chapter 5. Scopes and contexts

So far, we've seen a few examples of scope type annotations. The scope of a bean determines the lifecycle of instances of the bean. The scope also determines which clients refer to which instances of the bean. According to the CDI specification, a scope determines:

• When a new instance of any bean with that scope is created

• When an existing instance of any bean with that scope is destroyed

• Which injected references refer to any instance of a bean with that scope

For example, if we have a session-scoped bean, CurrentUser, all beans that are called in the context of the same HttpSession will see the same instance of CurrentUser. This instance will be automatically created the first time a CurrentUser is needed in that session, and automatically destroyed when the session ends.

## Note

JPA entities aren't a great fit for this model. Entities have their whole own lifecycle and identity model which just doesn't map naturally to the model used in CDI. Therefore, we recommend against treating entities as CDI beans. You're certainly going to run into problems if you try to give an entity a scope other than the default scope @Dependent. The client proxy will get in the way if you try to pass an injected instance to the JPA EntityManager.

## 5.3. The conversation scope

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 JSF request. 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.

### 5.3.1. Conversation demarcation

CDI provides a built-in bean for controlling the lifecycle of conversations in a JSF application. This bean may be obtained by injection:

@Inject Conversation conversation;

To promote the conversation associated with the current request to a long-running conversation, call the begin() method from application code. To schedule the current long-running conversation context for destruction at the end of the current request, call end().

In the following example, a conversation-scoped bean controls the conversation with which it is associated:

@ConversationScoped @Stateful
public class OrderBuilder {
private Order order;
private @Inject Conversation conversation;
private @PersistenceContext(type = EXTENDED) EntityManager em;

@Produces public Order getOrder() {
return order;
}

public Order createOrder() {
order = new Order();
conversation.begin();
return order;
}

public void addLineItem(Product product, int quantity) {
}

public void saveOrder(Order order) {
em.persist(order);
conversation.end();
}

@Remove
public void destroy() {}
}

This bean is able to control its own lifecycle through use of the Conversation API. But some other beans have a lifecycle which depends completely upon another object.

Weld, the JSR-299 Reference Implementation (RI), is being developed as part of the Seam project. You can download the latest community release of Weld from the download page. Information about the Weld source code repository and instructions about how to obtain and build the source can be found on the same page.

Weld provides a complete SPI allowing Java EE containers such as JBoss AS and GlassFish to use Weld as their built-in CDI implementation. Weld also runs in servlet engines like Tomcat and Jetty, or even in a plain Java SE environment.

Weld comes with an extensive library of examples, which are a great starting point from which to learn CDI.

## Chapter 6. Getting started with Weld

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

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

## 6.2. Deploying to JBoss AS

To deploy the examples to JBoss AS, you'll need JBoss AS 6.0.0 or above. If a release of the JBoss AS 6.0 line isn't yet available, you can download a nightly snapshot. The reason JBoss AS 6.0.0 or above is required is because it's the first release that has both CDI and Bean Validation support built-in, making it close enough to Java EE 6 to run the examples. The good news is that there are no additional modifications you have to make to the server. It's ready to go!

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

$> unzip jboss-6.0.*.zip$> mv jboss-6.0.*/ jboss-as-6.0

In order for the build scripts to know where to deploy the example, you have to tell them where to find your JBoss AS installation (i.e., JBOSS_HOME). Create a new file named local.build.properties in the examples directory of the Weld distribution and assign the path of your JBoss AS installation to the property key jboss.home, as follows:

jboss.home=/path/to/jboss-as-6.0

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

$> cd examples/jsf/numberguess$> ant deploy

If you haven't already, start JBoss AS. You can either start JBoss AS from a Linux shell:

$> cd /path/to/jboss-as-6.0$> ./bin/run.sh

a Windows command window:

$> cd c:\path\to\jboss-as-6.0\bin$> run

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

## Note

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

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

## Note

The Ant build script includes additional targets for JBoss AS to deploy and undeploy the archive in either exploded or packaged format and to tidy things up.

• ant restart - deploy the example in exploded format to JBoss AS

• ant explode - update an exploded example, without restarting the deployment

• ant deploy - deploy the example in compressed jar format to JBoss AS

• ant undeploy - remove the example from JBoss AS

• ant clean - clean the example

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

$> cd examples/jsf/translator$> ant deploy

## Note

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

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

## 6.3. Deploying to GlassFish

Deploying to GlassFish should be easy and familiar, right? After all, it's the Java EE 6 reference implementation and Weld is the JSR-299 reference implementation, meaning Weld gets bundled with GlassFish. So yes, it's all quite easy and familiar.

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

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

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

If you've deployed either of the starter examples, weld-numberguess or weld-translator, to JBoss AS, then you already have the deployable artifact you need. If not, switch to either of the two directories and build it.

$> cd examples/jsf/numberguess (or examples/jsf/translator)$> ant package

The deployable archive for the weld-numberguess, named weld-numberguess.war, ends up in the example's target directory. The archive for the weld-translator example, named weld-translator.ear, ends up in the example's ear/target directory. All you need to do now is deploy them to GlassFish.

One way to deploy applications to GlassFish is by using the GlassFish Admin Console. To get the Admin Console running, you need to start a GlassFish domain, in our case domain1. Switch to the bin folder in the directory where you installed GlassFish and execute the following command:

$> asadmin start-domain domain1 After a few seconds you can visit the Admin Console in the browser at the URL http://localhost:4848. In the tree on the left-hand side of the page, click on "Applications", then click on the "Deploy..." button under the heading "Applications" and select the deployable artifact for either of the two examples. The deployer should recognize that you have selected a Java EE artifact and allow you to start it. You can see the examples running at either http://localhost:7070/weld-numberguess or http://localhost:7070/weld-translator, depending on which example you deployed. Alternatively, you can deploy the application to GlassFish using the asadmin command: $> asadmin deploy target/weld-numberguess.war

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

## 6.4. Deploying to Apache Tomcat

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

Weld comes with a servlet listener which bootstraps the CDI environment, registers the BeanManager in JNDI and provides injection into servlets. Basically, it emulates some of the work done by the Java EE container. (But you don't get enterprise features such as session beans and container-managed transactions.)

$> unzip apache-tomcat-6.0.18.zip You have two choices for how you can deploy the application to Tomcat. You can deploy it by pushing the artifact to the hot deploy directory using Ant or you can deploy to the server across HTTP using a Maven plugin. The Ant approach doesn't require that you have Maven installed, so we'll start there. If you want to use Maven, you can just skip ahead. ## 6.5. Deploying to Jetty Support for Jetty in the examples is a more recent addition. Since Jetty is traditionally used with Maven, there are no Ant targets. You must invoke the Maven build directly to deploy the examples to Jetty out of the box. Also, only the weld-numberguess example is configured for Jetty support at the time of writing. If you've read through the entire Tomcat section, then you're all ready to go. The Maven build parallels the embedded Tomcat deployment. If not, don't worry. We'll still go over everything that you need to know again in this section. The Maven POM (pom.xml) includes a profile named jetty that activates the Maven Jetty plugin, which you can use to start Jetty in embedded mode and deploy the application in place. You don't need anything else installed except to have the Maven command (mvn) on your path. The rest will be downloaded from the internet when the build is run. To run the weld-numberguess example on Jetty, switch to the example directory and execute the inplace goal of the Maven war plugin followed by the run goal of the Maven Jetty plugin with the jetty profile enabled, as follows: $> cd examples/jsf/numberguess
$> mvn war:inplace jetty:run -Pjetty The log output of Jetty will be shown in the console. Once Jetty reports that the application has deployed, you can access it at the following local URL: http://localhost:9090/weld-numberguess. The port is defined in the Maven Jetty plugin configuration within the jetty profile. Any changes to assets in src/main/webapp take effect immediately. If a change to a webapp configuration file is made, the application may automatically redeploy. The redeploy behavior can be fined-tuned in the plugin configuration. If you make a change to a classpath resource, you need to execute a build and the inplace goal of the Maven war plugin, again with the jetty profile enabled. $> mvn compile war:inplace -Pjetty

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

You have two options if you want to run the example on Jetty from the IDE. You can either install the m2eclispe[link] plugin and run the goals as described above. Your other option is to start the Jetty container from a Java application.

First, initialize the Eclipse project:

$> mvn clean eclipse:clean eclipse:eclipse -Pjetty-ide Next, assemble all the necessary resources under src/main/webapp: $> mvn war:inplace -Pjetty-ide

Now, you are ready to run the server in Eclipse. Import the project into your Eclipse workspace using "Import Existing Project into Workspace. Then, find the start class in src/jetty/java and run its main method as a Java Application. Jetty will launch. You can view the application at the following local URL: http://localhost:8080. Pay particular attention to the port in the URL and the lack of a trailing context path.

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

## Chapter 7. Diving into the Weld examples

It's time to pull the covers back and dive into the internals of Weld example applications. Let's start with the simpler of the two examples, weld-numberguess.

## 7.1. The numberguess example in depth

In the numberguess application you get 10 attempts to guess a number between 1 and 100. After each attempt, you're told whether your guess was too high or too low.

The numberguess example is comprised of a number of beans, configuration files and Facelets (JSF) views, packaged as a war module. Let's start by examining the configuration files.

All the configuration files for this example are located in WEB-INF/, which can be found in the src/main/webapp directory of the example. First, we have the JSF 2.0 version of faces-config.xml. A standardized version of Facelets is the default view handler in JSF 2.0, so there's really nothing that we have to configure. Thus, the configuration consists of only the root element.


<faces-config version="2.0"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd">
</faces-config>


There's also an empty beans.xml file, which tells the container to look for beans in this application and to activate the CDI services.

Finally, there's the familiar web.xml:


<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

<display-name>weld-jsf-numberguess-war</display-name>
ml_plain">   <description>Weld JSF numberguess example (war)</description>

<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
ml_plain">   </servlet>

<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.jsf</url-pattern>
ml_plain">   </servlet-mapping>

<context-param>
<param-name>javax.faces.DEFAULT_SUFFIX</param-name>
<param-value>.xhtml</param-value>
ml_plain">   </context-param>

<session-config>
<session-timeout>10</session-timeout>
</session-config>

</web-app>

 Enable and initialize the JSF servlet Configure requests for URLs ending in .jsf to be handled by JSF Tell JSF that we will be giving our JSF views (Facelets templates) an extension of .xhtml Configure a session timeout of 10 minutes

Let's take a look at the main JSF view, src/main/webapp/home.xhtml.


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<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">
ml_plain">
<ui:composition template="/template.xhtml">
<ui:define name="content">
<h1>Guess a number...</h1>
ml_plain">         <h:form id="numberGuess">
<div style="color: red">
<h:messages id="messages" globalOnly="false"/>
<h:outputText id="Higher" value="Higher!"
rendered="#{game.number gt game.guess and game.guess ne 0}"/>
<h:outputText id="Lower" value="Lower!"
rendered="#{game.number lt game.guess and game.guess ne 0}"/>
</div>
ml_plain">
<div>
I'm thinking of a number between #{game.smallest} and #{game.biggest}.
You have #{game.remainingGuesses} guesses remaining.
</div>

<div>
ml_plain">               Your guess:
<h:inputText id="inputGuess" value="#{game.guess}"
ml_plain">                  size="3" required="true" disabled="#{game.number eq game.guess}"
ml_plain">                  validator="#{game.validateNumberRange}"/>
<h:commandButton id="guessButton" value="Guess"
action="#{game.check}" disabled="#{game.number eq game.guess}"/>
</div>
<div>
<h:commandButton id="restartButton" value="Reset" action="#{game.reset}" immediate="true"/>
</div>
</h:form>
</ui:define>
</ui:composition>
</html>

 Facelets is the built-in templating language for JSF. Here we are wrapping our page in a template which defines the layout. There are a number of messages which can be sent to the user, "Higher!", "Lower!" and "Correct!" As the user guesses, the range of numbers they can guess gets smaller - this sentence changes to make sure they know the number range of a valid guess. This input field is bound to a bean property using a value expression. A validator binding is used to make sure the user doesn't accidentally input a number outside of the range in which they can guess - if the validator wasn't here, the user might use up a guess on an out of bounds number. And, of course, there must be a way for the user to send their guess to the server. Here we bind to an action method on the bean.

The example exists of 4 classes, the first two of which are qualifiers. First, there is the @Random qualifier, used for injecting a random number:

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

There is also the @MaxNumber qualifier, used for injecting the maximum number that can be injected:

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


The application-scoped Generator class is responsible for creating the random number, via a producer method. It also exposes the maximum possible number via a producer method:

@ApplicationScoped
public class Generator implements Serializable {

private java.util.Random random = new java.util.Random(System.currentTimeMillis());

private int maxNumber = 100;

java.util.Random getRandom() {
return random;
}

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

@Produces @MaxNumber int getMaxNumber() {
return maxNumber;
}

}

The Generator is application scoped, so we don't get a different random each time.

The final bean in the application is the session-scoped Game class. This is the primary entry point of the application. It's responsible for setting up or resetting the game, capturing and validating the user's guess and providing feedback to the user with a FacesMessage. We've used the post-construct lifecycle method to initialize the game by retrieving a random number from the @Random Instance<Integer> bean.

You'll notice that we've also added the @Named annotation to this class. This annotation is only required when you want to make the bean accessible to a JSF view via EL (i.e., #{game}).

@Named
@SessionScoped
public class Game implements Serializable {

private int number;
private int guess;
private int smallest;
private int biggest;
private int remainingGuesses;

@Inject @MaxNumber private int maxNumber;
@Inject @Random Instance<Integer> randomNumber;

public Game() {}

public void check() {
if (guess > number) {
biggest = guess - 1;
}
else if (guess < number) {
smallest = guess + 1;
}
else if (guess == number) {
}
remainingGuesses--;
}

@PostConstruct
public void reset() {
this.smallest = 0;
this.guess = 0;
this.remainingGuesses = 10;
this.biggest = maxNumber;
this.number = randomNumber.get();
}

public void validateNumberRange(FacesContext context,  UIComponent toValidate, Object value) {
if (remainingGuesses <= 0) {
FacesMessage message = new FacesMessage("No guesses left!");
((UIInput) toValidate).setValid(false);
return;
}
int input = (Integer) value;

if (input < smallest || input > biggest) {
((UIInput) toValidate).setValid(false);

FacesMessage message = new FacesMessage("Invalid guess");
}
}

public int getNumber() {
return number;
}

public int getGuess() {
return guess;
}

public void setGuess(int guess) {
this.guess = guess;
}

public int getSmallest() {
return smallest;
}

public int getBiggest() {
return biggest;
}

public int getRemainingGuesses() {
return remainingGuesses;
}

}

## 7.2. The numberguess example for Java SE with Swing

This example shows how to use the Weld SE extension to in a Java SE based Swing application with no EJB or servlet dependencies. This example can be found in the examples/se/numberguess folder of the Weld distribution.

### 7.2.1. Creating the Eclipse project

If you have m2eclipse installed, you can open any Maven project directly. From within Eclipse, select File -> Import... -> Maven Projects. Then, browse to the location of the Weld SE numberguess example. You should see that Eclipse recognizes the existence of a Maven project.

This will create a project in your workspace called weld-se-numberguess.

If you are not using the m2eclipse plugin, you have to follow different steps to import the project. First, switch into the Weld SE numberguess example, then execute the Maven Eclipse plugin with the jetty profile activated, as follows:

It's time to get the example running!

### 7.2.4. Understanding the code

Let's have a look at the significant code and configuration files that make up this example.

As usual, there is an empty beans.xml file in the root package (src/main/resources/beans.xml), which marks this application as a CDI application.

The game's main logic is located in Game.java. Here is the code for that class, highlighting the ways in which this differs from the web application version:

@ApplicationScoped
public class Game
{

public static final int MAX_NUM_GUESSES = 10;

private Integer number;
private int guess = 0;
private int smallest = 0;

@Inject
@MaxNumber
private int maxNumber;

private int biggest;
private int remainingGuesses = MAX_NUM_GUESSES;
private boolean validNumberRange = true;

@Inject
Generator rndGenerator;

public Game()
{
}

...

public boolean isValidNumberRange()
{
return validNumberRange;
}

public boolean isGameWon()
{
return guess == number;
}

public boolean isGameLost()
{
return guess != number && remainingGuesses <= 0;
}

public boolean check()
{
boolean result = false;

if (checkNewNumberRangeIsValid())
{
if (guess > number)
{
biggest = guess - 1;
}

if (guess < number)
{
smallest = guess + 1;
}

if (guess == number)
{
result = true;
}

remainingGuesses--;
}

return result;
}

private boolean checkNewNumberRangeIsValid()
{
return validNumberRange = ((guess >= smallest) && (guess <= biggest));
}

@PostConstruct
public void reset()
{
this.smallest = 0;
this.guess = 0;
this.remainingGuesses = 10;
this.biggest = maxNumber;
this.number = rndGenerator.next();
}
}
 The bean is application scoped rather than session scoped, since an instance of a Swing application typically represents a single 'session'. Notice that the bean is not named, since it doesn't need to be accessed via EL. In Java SE there is no JSF FacesContext to which messages can be added. Instead the Game class provides additional information about the state of the current game including: If the game has been won or lost If the most recent guess was invalid This allows the Swing UI to query the state of the game, which it does indirectly via a class called MessageGenerator, in order to determine the appropriate messages to display to the user during the game. Since there is no dedicated validation phase, validation of user input is performed during the check() method. The reset() method makes a call to the injected rndGenerator in order to get the random number at the start of each game. Note that it can't use Instance.get() like the JSF example does because there will not be any active contexts like there are during a JSF request.

The MessageGenerator class depends on the current instance of Game and queries its state in order to determine the appropriate messages to provide as the prompt for the user's next guess and the response to the previous guess. The code for MessageGenerator is as follows:

public class MessageGenerator
{
@Inject
private Game game;

public String getChallengeMessage()
{
StringBuilder challengeMsg = new StringBuilder("I'm thinking of a number between ");
challengeMsg.append(game.getSmallest());
challengeMsg.append(" and ");
challengeMsg.append(game.getBiggest());
challengeMsg.append(". Can you guess what it is?");

return challengeMsg.toString();
}

public String getResultMessage()
{
if (game.isGameWon())
{
return "You guessed it! The number was " + game.getNumber();
}
else if (game.isGameLost())
{
return "You are fail! The number was " + game.getNumber();
}
else if (!game.isValidNumberRange())
{
return "Invalid number range!";
}
else if (game.getRemainingGuesses() == Game.MAX_NUM_GUESSES)
{
return "What is your first guess?";
}
else
{
String direction = null;

if (game.getGuess() < game.getNumber())
{
direction = "Higher";
}
else
{
direction = "Lower";
}

return direction + "! You have " + game.getRemainingGuesses() + " guesses left.";
}
}
}
 The instance of Game for the application is injected here. The Game's state is interrogated to determine the appropriate challenge message ... ... and again to determine whether to congratulate, console or encourage the user to continue.

Finally we come to the NumberGuessFrame class which provides the Swing front end to our guessing game.

public class NumberGuessFrame extends javax.swing.JFrame
{
@Inject
private Game game;

@Inject
private MessageGenerator msgGenerator;

public void start(@Observes ContainerInitialized event)
{
java.awt.EventQueue.invokeLater(new Runnable()
{
public void run()
{
initComponents();
setVisible(true);
}
});
}

private void initComponents()
{

buttonPanel = new javax.swing.JPanel();
mainMsgPanel = new javax.swing.JPanel();
mainLabel = new javax.swing.JLabel();
messageLabel = new javax.swing.JLabel();
guessText = new javax.swing.JTextField();
...
mainLabel.setText(msgGenerator.getChallengeMessage());

messageLabel.setText(msgGenerator.getResultMessage());
...
}

private void guessButtonActionPerformed( java.awt.event.ActionEvent evt )
{
int guess =  Integer.parseInt(guessText.getText());
game.setGuess( guess );
game.check();
refreshUI();
}

private void replayBtnActionPerformed(java.awt.event.ActionEvent evt)
{
game.reset();
refreshUI();
}

private void refreshUI() {
mainLabel.setText( msgGenerator.getChallengeMessage() );
messageLabel.setText( msgGenerator.getResultMessage() );
guessText.setText( "" );
guessesLeftBar.setValue( game.getRemainingGuesses() );
guessText.requestFocus();
}

// swing components
private javax.swing.JPanel borderPanel;
...
private javax.swing.JButton replayBtn;

}
 The injected instance of the game (logic and state). The injected message generator for UI messages. This application is started in the prescribed Weld SE way, by observing the ContainerInitialized event. This method initializes all of the Swing components. Note the use of the msgGenerator here. guessButtonActionPerformed is called when the 'Guess' button is clicked, and it does the following: Gets the guess entered by the user and sets it as the current guess in the Game Calls game.check() to validate and perform one 'turn' of the game Calls refreshUI. If there were validation errors with the input, this will have been captured during game.check() and as such will be reflected in the messages returned by MessageGenerator and subsequently presented to the user. If there are no validation errors then the user will be told to guess again (higher or lower) or that the game has ended either in a win (correct guess) or a loss (ran out of guesses). replayBtnActionPerformed simply calls game.reset() to start a new game and refreshes the messages in the UI.

## 7.3. The translator example in depth

The translator example will take any sentences you enter, and translate them to Latin. (Well, not really, but the stub is there for you to implement, at least. Good luck!)

The translator example is built as an ear and contains EJBs. As a result, it's structure is more complex than the numberguess example.

First, let's take a look at the ear aggregator, which is located in the example's ear directory. Maven automatically generates the application.xml for us from this plugin configuration:


<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-ear-plugin</artifactId>
<configuration>
<modules>
<webModule>
<groupId>org.jboss.weld.examples.jsf.translator</groupId>
<artifactId>weld-jsf-translator-war</artifactId>
<contextRoot>/weld-translator</contextRoot>
</webModule>
</modules>
</configuration>
</plugin>


## Note

If you weren't using Maven to generate these files, you would need META-INF/application.xml:


<application version="5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/application_5.xsd">

<display-name>weld-jsf-translator-ear</display-name>
<description>The Weld JSF translator example (ear)</description>

<module>
<web>
<web-uri>weld-translator.war</web-uri>
<context-root>/weld-translator</context-root>
</web>
</module>
<module>
<ejb>weld-translator.jar</ejb>
</module>
</application>


Next, lets look at the war, which is located in the example's war directory. Just as in the numberguess example, we have a faces-config.xml for JSF 2.0 and a web.xml (to activate JSF) under WEB-INF, both sourced from src/main/webapp/WEB-INF.

More interesting is the JSF view used to translate text. Just as in the numberguess example we have a template, which surrounds the form (ommitted here for brevity):


<h:form id="translator">

<table>
<tr align="center" style="font-weight: bold">
<td>
Your text
</td>
<td>
Translation
</td>
</tr>
<tr>
<td>
<h:inputTextarea id="text" value="#{translator.text}" required="true" rows="5" cols="80"/>
</td>
<td>
<h:outputText value="#{translator.translatedText}"/>
</td>
</tr>
</table>
<div>
<h:commandButton id="button" value="Translate" action="#{translator.translate}"/>
</div>

</h:form>


The user can enter some text in the left-hand textarea, and hit the translate button to see the result to the right.

Finally, let's look at the EJB module, which is located in the example's ejb directory. In src/main/resources/META-INF there is just an empty beans.xml, used to mark the archive as containing beans.

We've saved the most interesting bit to last, the code! The project has two simple beans, SentenceParser and TextTranslator and two session beans, TranslatorControllerBean and SentenceTranslator. You should be getting quite familiar with what a bean looks like by now, so we'll just highlight the most interesting bits here.

Both SentenceParser and TextTranslator are dependent beans, and TextTranslator uses constructor injection:

public class TextTranslator implements Serializable {

private SentenceParser sentenceParser;

@EJB private Translator translator;

@Inject public TextTranslator(SentenceParser sentenceParser) {
this.sentenceParser = sentenceParser;
}

public String translate(String text) {
StringBuilder sb = new StringBuilder();
for (String sentence: sentenceParser.parse(text)) {
sb.append(translator.translate(sentence)).append(". ");
}
return sb.toString().trim();
}

}

TextTranslator uses the simple bean (really just a plain Java class!) SentenceParser to parse the sentence and then calls on the stateless bean with the local business interface Translator to perform the translation. That's where the magic happens. Of course, we couldn't develop a full translator, but it's convincing enough to anyone who doesn't understand Latin!

@Stateless
public class SentenceTranslator implements Translator {

public String translate(String sentence) {
return "Lorem ipsum dolor sit amet";
}

}

Finally, there is UI orientated controller. This is a request scoped, named, stateful session bean, which injects the translator. It collects the text from the user and dispatches it to the translator. The bean also has getters and setters for all the fields on the page.

@Stateful
@RequestScoped
@Named("translator")
public class TranslatorControllerBean implements TranslatorController {

@Inject private TextTranslator translator;

private String inputText;

private String translatedText;

public void translate() {
translatedText = translator.translate(inputText);
}

public String getText() {
return inputText;
}

public void setText(String text) {
this.inputText = text;
}

public String getTranslatedText() {
return translatedText;
}

@Remove public void remove() {}

}

That concludes our short tour of the Weld starter examples. For more information on Weld, please visit http://www.seamframework.org/Weld.

# Part III. Loose coupling with strong typing

## Chapter 8. Producer methods

Producer methods let us overcome certain limitations that arise when a container, instead of the application, is responsible for instantiating objects. They're also the easiest way to integrate objects which are not beans into the CDI environment.

According to the spec:

A producer method acts as a source of objects to be injected, where:

• the objects to be injected are not required to be instances of beans,

• the concrete type of the objects to be injected may vary at runtime or

• the objects require some custom initialization that is not performed by the bean constructor

For example, producer methods let us:

• expose a JPA entity as a bean,

• expose any JDK class as a bean,

• define multiple beans, with different scopes or initialization, for the same implementation class, or

• vary the implementation of a bean type at runtime.

In particular, producer methods let us use runtime polymorphism with CDI. As we've seen, alternative beans are one solution to the problem of deployment-time polymorphism. But once the system is deployed, the CDI implementation is fixed. A producer method has no such limitation:

@SessionScoped
public class Preferences implements Serializable {
private PaymentStrategyType paymentStrategy;
...
@Produces @Preferred
public PaymentStrategy getPaymentStrategy() {
switch (paymentStrategy) {
case CREDIT_CARD: return new CreditCardPaymentStrategy();
case CHECK: return new CheckPaymentStrategy();
case PAYPAL: return new PayPalPaymentStrategy();
default: return null;
}
}
}

Consider an injection point:

@Inject @Preferred PaymentStrategy paymentStrategy;

This injection point has the same type and qualifier annotations as the producer method, so it resolves to the producer method using the usual CDI injection rules. The producer method will be called by the container to obtain an instance to service this injection point.

## 8.2. Injection into producer methods

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:

@Produces @Preferred @SessionScoped
public PaymentStrategy getPaymentStrategy(CreditCardPaymentStrategy ccps,
CheckPaymentStrategy cps,
PayPalPaymentStrategy ppps) {
switch (paymentStrategy) {
case CREDIT_CARD: return ccps;
case CHEQUE: return cps;
case PAYPAL: return ppps;
default: return null;
}
}

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.

## 8.3. Use of @New with producer methods

Consider the following producer method:

@Produces @Preferred @SessionScoped
public PaymentStrategy getPaymentStrategy(@New CreditCardPaymentStrategy ccps,
@New CheckPaymentStrategy cps,
@New PayPalPaymentStrategy ppps) {
switch (paymentStrategy) {
case CREDIT_CARD: return ccps;
case CHEQUE: return cps;
case PAYPAL: return ppps;
default: return null;
}
}

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.

## Chapter 9. Interceptors

Interceptor functionality is defined in the Java Interceptors specification. CDI enhances this functionality with a more sophisticated, semantic, annotation-based approach to binding interceptors to beans.

The Interceptors specification defines two kinds of interception points:

• lifecycle callback interception.

In addition, the EJB specification defines timeout method interception.

A business method interceptor applies to invocations of methods of the bean by clients of the bean:

public class TransactionInterceptor {
@AroundInvoke
public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}

A lifecycle callback interceptor applies to invocations of lifecycle callbacks by the container:

public class DependencyInjectionInterceptor {
@PostConstruct
public void injectDependencies(InvocationContext ctx) { ... }
}

An interceptor class may intercept both lifecycle callbacks and business methods.

A timeout method interceptor applies to invocations of EJB timeout methods by the container:

public class TimeoutInterceptor {
@AroundTimeout
public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}

## 9.1. Interceptor bindings

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:

@InterceptorBinding
@Target({METHOD, TYPE})
@Retention(RUNTIME)
public @interface Transactional {}

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

@Transactional
public class ShoppingCart { ... }

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

public class ShoppingCart {
@Transactional public void checkout() { ... }
}

## 9.2. Implementing interceptors

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.

@Transactional @Interceptor
public class TransactionInterceptor {
@AroundInvoke
public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}

Interceptors can take advantage of dependency injection:

@Transactional @Interceptor
public class TransactionInterceptor {

@Resource UserTransaction transaction;

@AroundInvoke
public Object manageTransaction(InvocationContext ctx) throws Exception { ... }

}

Multiple interceptors may use the same interceptor binding type.

## 9.3. Enabling interceptors

By default, all interceptors are disabled. We need to enable our interceptor in the beans.xml descriptor of a bean archive. This activation only applies to the beans in that archive.


<beans
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
<interceptors>
<class>org.mycompany.myapp.TransactionInterceptor</class>
</interceptors>
</beans>


Whoah! Why the angle bracket stew?

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

For example, we could specify that our security interceptor runs before our transaction interceptor.


<beans
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
<interceptors>
<class>org.mycompany.myapp.SecurityInterceptor</class>
<class>org.mycompany.myapp.TransactionInterceptor</class>
</interceptors>
</beans>


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

## 9.4. Interceptor bindings with members

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

@InterceptorBinding
@Target({METHOD, TYPE})
@Retention(RUNTIME)
public @interface Transactional {
boolean requiresNew() default false;
}

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

@Transactional(requiresNew = true) @Interceptor
public class RequiresNewTransactionInterceptor {
@AroundInvoke
public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}

Now we can use RequiresNewTransactionInterceptor like this:

@Transactional(requiresNew = true)
public class ShoppingCart { ... }

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:

@InterceptorBinding
@Target({METHOD, TYPE})
@Retention(RUNTIME)
public @interface Secure {
@Nonbinding String[] rolesAllowed() default {};
}

## 9.5. Multiple interceptor binding annotations

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:

@Secure(rolesAllowed="admin") @Transactional
public class ShoppingCart { ... }

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

@Transactional @Secure @Interceptor
public class TransactionalSecureInterceptor { ... }

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

public class ShoppingCart {
@Transactional @Secure public void checkout() { ... }
}
@Secure
public class ShoppingCart {
@Transactional public void checkout() { ... }
}
@Transactional
public class ShoppingCart {
@Secure public void checkout() { ... }
}
@Transactional @Secure
public class ShoppingCart {
public void checkout() { ... }
}

## 9.7. Use of @Interceptors

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

@Interceptors({TransactionInterceptor.class, SecurityInterceptor.class})
public class ShoppingCart {
public void checkout() { ... }
}

However, this approach suffers the following drawbacks:

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

## Chapter 10. Decorators

Interceptors are a powerful way to capture and separate concerns which are orthogonal to the application (and type system). Any interceptor is able to intercept invocations of any Java type. This makes them perfect for solving technical concerns such as transaction management, security and call logging. However, by nature, interceptors are unaware of the actual semantics of the events they intercept. Thus, interceptors aren't an appropriate tool for separating business-related concerns.

The reverse is true of decorators. A decorator intercepts invocations only for a certain Java interface, and is therefore aware of all the semantics attached to that interface. Since decorators directly implement operations with business semantics, it makes them the perfect tool for modeling some kinds of business concerns. It also means that a decorator doesn't have the generality of an interceptor. Decorators aren't able to solve technical concerns that cut across many disparate types. Interceptors and decorators, though similar in many ways, are complementary. Let's look at some cases where decorators fit the bill.

Suppose we have an interface that represents accounts:

public interface Account {
public BigDecimal getBalance();
public User getOwner();
public void withdraw(BigDecimal amount);
public void deposit(BigDecimal amount);
}

Several different beans in our system implement the Account interface. However, we have a common legal requirement that; for any kind of account, large transactions must be recorded by the system in a special log. This is a perfect job for a decorator.

A decorator is a bean (possibly even an abstract class) that implements the type it decorates and is annotated @Decorator.

@Decorator
public abstract class LargeTransactionDecorator
implements Account {
...
}

The decorator implements the methods of the decorated type that it wants to intercept.

@Decorator
public abstract class LargeTransactionDecorator
implements Account {
@Inject @Delegate @Any Account account;

@PersistenceContext EntityManager em;

public void withdraw(BigDecimal amount) {
...
}

public void deposit(BigDecimal amount);
...
}
}

Unlike other beans, a decorator may be an abstract class. Therefore, if there's nothing special the decorator needs to do for a particular method of the decorated interface, you don't need to implement that method.

Interceptors for a method are called before decorators that apply to the method.

## 10.1. Delegate object

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.

@Decorator
public abstract class LargeTransactionDecorator
implements Account {
@Inject @Delegate @Any Account account;
...
}

A decorator is bound to any bean which:

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

@Inject @Delegate @Any Account account;

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

@Inject @Delegate @Foreign Account account;

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.

@Decorator
public abstract class LargeTransactionDecorator
implements Account {
@Inject @Delegate @Any Account account;

@PersistenceContext EntityManager em;

public void withdraw(BigDecimal amount) {
account.withdraw(amount);
if ( amount.compareTo(LARGE_AMOUNT)>0 ) {
em.persist( new LoggedWithdrawl(amount) );
}
}

public void deposit(BigDecimal amount);
account.deposit(amount);
if ( amount.compareTo(LARGE_AMOUNT)>0 ) {
em.persist( new LoggedDeposit(amount) );
}
}
}

## 10.2. Enabling decorators

By default, all decorators are disabled. We need to enable our decorator in the beans.xml descriptor of a bean archive. This activation only applies to the beans in that archive.


<beans
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
<decorators>
<class>org.mycompany.myapp.LargeTransactionDecorator</class>
</decorators>
</beans>


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

## Chapter 11. Events

Dependency injection enables loose-coupling by allowing the implementation of the injected bean type to vary, either a deployment time or runtime. Events go one step further, allowing beans to interact with no compile time dependency at all. Event producers raise events that are delivered to event observers by the container.

This basic schema might sound like the familiar observer/observable pattern, but there are a couple of twists:

• not only are event producers decoupled from observers; observers are completely decoupled from producers,

• observers can specify a combination of "selectors" to narrow the set of event notifications they will receive, and

• observers can be notified immediately, or can specify that delivery of the event should be delayed until the end of the current transaction.

The CDI event notification facility uses more or less the same typesafe approach that we've already seen with the dependency injection service.

## 11.5. Event qualifiers with members

An event qualifier type may have annotation members:

@Qualifier
@Target({PARAMETER, FIELD})
@Retention(RUNTIME)
public @interface Role {
RoleType value();
}

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

public void adminLoggedIn(@Observes @Role(ADMIN) LoggedIn event) { ... }

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

@Inject @Role(ADMIN) Event<LoggedIn> loggedInEvent;

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:

abstract class RoleBinding
extends AnnotationLiteral<Role>
implements Role {}

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

documentEvent.select(new RoleBinding() {
public void value() { return user.getRole(); }
}).fire(document);

## 11.6. Multiple event qualifiers

Event qualifier types may be combined, for example:

@Inject @Blog Event<Document> blogEvent;
...
if (document.isBlog()) blogEvent.select(new AnnotationLiteral<Updated>(){}).fire(document);

Observers must completely match the final qualified type of the event. Assume the following observers in this example:

public void afterBlogUpdate(@Observes @Updated @Blog Document document) { ... }
public void afterDocumentUpdate(@Observes @Updated Document document) { ... }
public void onAnyBlogEvent(@Observes @Blog Document document) { ... }
public void onAnyDocumentEvent(@Observes Document document) { ... }}}

The only observer notified will be:

public void afterBlogUpdate(@Observes @Updated @Blog Document document) { ... }

However, if there were also an observer:

public void afterBlogUpdate(@Observes @Any Document document) { ... }

It would also be notified, as @Any acts as an alias for any and all qualifiers.

## 11.7. Transactional observers

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:

public void refreshCategoryTree(@Observes(during = AFTER_SUCCESS) CategoryUpdateEvent event) { ... }

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:

@ApplicationScoped @Singleton
public class Catalog {

@PersistenceContext EntityManager em;

List<Product> products;

@Produces @Catalog
List<Product> getCatalog() {
if (products==null) {
products = em.createQuery("select p from Product p where p.deleted = false")
.getResultList();
}
return products;
}

}

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 Products could raise events, for example:

@Stateless
public class ProductManager {
@PersistenceContext EntityManager em;
@Inject @Any Event<Product> productEvent;

public void delete(Product product) {
em.delete(product);
productEvent.select(new AnnotationLiteral<Deleted>(){}).fire(product);
}

public void persist(Product product) {
em.persist(product);
productEvent.select(new AnnotationLiteral<Created>(){}).fire(product);
}
...
}

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

@ApplicationScoped @Singleton
public class Catalog {
...
void addProduct(@Observes(during = AFTER_SUCCESS) @Created Product product) {
}

void removeProduct(@Observes(during = AFTER_SUCCESS) @Deleted Product product) {
products.remove(product);
}
}

## Chapter 12. Stereotypes

The CDI specification defines a stereotype as follows:

In many systems, use of architectural patterns produces a set of recurring bean roles. A stereotype allows a framework developer to identify such a role and declare some common metadata for beans with that role in a central place.

A stereotype encapsulates any combination of:

• a default scope, and

• a set of interceptor bindings.

A stereotype may also specify that:

• all beans with the stereotype have defaulted bean EL names, or that

• all beans with the stereotype are alternatives.

A bean may declare zero, one or multiple stereotypes. Stereotype annotations may be applied to a bean class or producer method or field.

A stereotype is an annotation, annotated @Stereotype, that packages several other annotations. For instance, the following stereotype identifies action classes in some MVC framework:

@Stereotype
@Retention(RUNTIME)
@Target(TYPE)
...
public @interface Action {}

We use the stereotype by applying the annotation to a bean.

@Action
public class LoginAction { ... }

Of course, we need to apply some other annotations to our stereotype or else it wouldn't be adding much value.

## 12.1. Default scope for a stereotype

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

@RequestScoped
@Stereotype
@Retention(RUNTIME)
@Target(TYPE)
public @interface Action {}

A particular action may still override this default if necessary:

@Dependent @Action
public class DependentScopedLoginAction { ... }

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

## 12.2. Interceptor bindings for stereotypes

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

@RequestScoped
@Transactional(requiresNew=true)
@Secure
@Stereotype
@Retention(RUNTIME)
@Target(TYPE)
public @interface Action {}

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

## 12.3. Name defaulting with stereotypes

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:

@RequestScoped
@Transactional(requiresNew=true)
@Secure
@Named
@Stereotype
@Retention(RUNTIME)
@Target(TYPE)
public @interface Action {}

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

## 12.4. Alternative stereotypes

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

@Alternative
@Stereotype
@Retention(RUNTIME)
@Target(TYPE)
public @interface Mock {}

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

@Mock
public class MockLoginAction extends LoginAction { ... }

## Chapter 13. Specialization, inheritance and alternatives

When you first start developing with CDI, you'll likely be dealing only with a single bean implementation for each bean type. In this case, it's easy to understand how beans get selected for injection. As the complexity of your application grows, multiple occurrences of the same bean type start appearing, either because you have multiple implementations or two beans share a common (Java) inheritance. That's when you have to begin studying the specialization, inheritance and alternative rules to work through unsatisfied or ambiguous dependencies or to avoid certain beans from being called.

The CDI specification recognizes two distinct scenarios in which one bean extends another:

• The second bean specializes the first bean in certain deployment scenarios. In these deployments, the second bean completely replaces the first, fulfilling the same role in the system.

• The second bean is simply reusing the Java implementation, and otherwise bears no relation to the first bean. The first bean may not even have been designed for use as a contextual object.

The second case is the default assumed by CDI. It's possible to have two beans in the system with the same part bean type (interface or parent class). As you've learned, you select between the two implementations using qualifiers.

The first case is the exception, and also requires more care. In any given deployment, only one bean can fulfill a given role at a time. That means one bean needs to be enabled and the other disabled. There are a two modifiers involved: @Alternative and @Specializes. We'll start by looking at alternatives and then show the guarantees that specialization adds.

## 13.1. Using alternative stereotypes

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:

public class DefaultPaymentProcessor
implements PaymentProcessor {
...
}

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:

public @Alternative
class StagingPaymentProcessor
implements PaymentProcessor {
...
}

or

public @Alternative
class StagingPaymentProcessor
extends DefaultPaymentProcessor {
...
}

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:

@Alternative
@Stereotype
@Retention(RUNTIME)
@Target(TYPE)
public @interface Staging {}

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

@Staging
public class StagingPaymentProcessor
implements PaymentProcessor {
...
}

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


<beans
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
<alternatives>
<stereotype>org.mycompany.myapp.Staging</stereotype>
</alternatives>
</beans>


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

## Chapter 14. Java EE component environment resources

Java EE 5 already introduced some limited support for dependency injection, in the form of component environment injection. A component environment resource is a Java EE component, for example a JDBC datasource, JMS queue or topic, JPA persistence context, remote EJB or web service.

Naturally, there is now a slight mismatch with the new style of dependency injection in CDI. Most notably, component environment injection relies on string-based names to qualify ambiguous types, and there is no real consistency as to the nature of the names (sometimes a JNDI name, sometimes a persistence unit name, sometimes an EJB link, sometimes a nonportable "mapped name"). Producer fields turned out to be an elegant adaptor to reduce all this complexity to a common model and get component environment resources to participate in the CDI system just like any other kind of bean.

Fields have a duality in that they can both be the target of Java EE component environment injection and be declared as a CDI producer field. Therefore, they can define a mapping from a string-based name in the component environment, to a combination of type and qualifiers used in the world of typesafe injection. We call a producer field that represents a reference to an object in the Java EE component environment a resource.

## 14.1. Defining a resource

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.

@Produces @WebServiceRef(lookup="java:app/service/Catalog")
Catalog catalog;
@Produces @Resource(lookup="java:global/env/jdbc/CustomerDatasource")
@CustomerDatabase Datasource customerDatabase;
@Produces @PersistenceContext(unitName="CustomerDatabase")
@CustomerDatabase EntityManager customerDatabasePersistenceContext;
@Produces @PersistenceUnit(unitName="CustomerDatabase")
@CustomerDatabase EntityManagerFactory customerDatabasePersistenceUnit;
@Produces @EJB(ejbLink="../their.jar#PaymentService")
PaymentService paymentService;

The field may be static (but not final).

A resource declaration really contains two pieces of information:

## 14.2. Typesafe resource injection

These resources can now be injected in the usual way.

@Inject Catalog catalog;
@Inject @CustomerDatabase Datasource customerDatabase;
@Inject @CustomerDatabase EntityManager customerDatabaseEntityManager;
@Inject @CustomerDatabase EntityManagerFactory customerDatabaseEntityManagerFactory;
@Inject PaymentService paymentService;

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

@Inject @CustomerDatabase EntityManager

@PersistenceContext(unitName="CustomerDatabase") EntityManager

all over the place?

# Part IV. CDI and the Java EE ecosystem

## Chapter 15. Java EE integration

CDI is fully integrated into the Java EE environment. Beans have access to Java EE resources and JPA persistence contexts. They may be used in Unified EL expressions in JSF and JSP pages. They may even be injected into other platform components, such as servlets and message-driven Beans, which are not beans themselves.

## 15.1. Built-in beans

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

## Note

The CDI specification does not require the servlet context objects, HttpServletRequest, HttpSession and ServletContext to be exposed as injectable beans. If you really want to be able to inject these objects, it's easy to create a portable extension to expose them as beans. However, we recommend that direct access to these objects be limited to servlets, servlet filters and servlet event listeners, where they may be obtained in the usual way as defined by the Java Servlets spec. The FacesContext is also not injectable. You can get at it by calling FacesContext.getCurrentInstance().

## Note

Oh, you really want to inject the FacesContext? Alright then, try this producer method:

class FacesContextProducer {
@Produces @RequestScoped FacesContext getFacesContext() {
return FacesContext.getCurrentInstance();
}
}

## 15.2. Injecting Java EE resources into a bean

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

@Transactional @Interceptor
public class TransactionInterceptor {
@Resource UserTransaction transaction;

@AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}
@SessionScoped
public class Login implements Serializable {
@Inject Credentials credentials;
@PersistenceContext EntityManager userDatabase;
...
}

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.

## 15.3. Calling a bean from a servlet

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

public class Login extends HttpServlet {
@Inject Credentials credentials;

@Override
public void service(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
response.sendRedirect("/home.jsp");
}
else {
}
}

}

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.

## 15.5. JMS endpoints

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:

public class OrderResources {
@Resource(name="jms/ConnectionFactory")
private ConnectionFactory connectionFactory;

@Resource(name="jms/OrderQueue")
private Queue orderQueue;

@Produces @OrderConnection
public Connection createOrderConnection() throws JMSException {
return connectionFactory.createConnection();
}

public void closeOrderConnection(@Disposes @OrderConnection Connection connection)
throws JMSException {
connection.close();
}

@Produces @OrderSession
public Session createOrderSession(@OrderConnection Connection connection)
throws JMSException {
return connection.createSession(true, Session.AUTO_ACKNOWLEDGE);
}

public void closeOrderSession(@Disposes @OrderSession Session session)
throws JMSException {
session.close();
}

@Produces @OrderMessageProducer
public MessageProducer createOrderMessageProducer(@OrderSession Session session)
throws JMSException {
return session.createProducer(orderQueue);
}

public void closeOrderMessageProducer(@Disposes @OrderMessageProducer MessageProducer producer)
throws JMSException {
producer.close();
}
}

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

@Inject Order order;
@Inject @OrderMessageProducer MessageProducer producer;
@Inject @OrderSession QueueSession orderSession;

public void sendMessage() {
MapMessage msg = orderSession.createMapMessage();
msg.setLong("orderId", order.getId());
...
producer.send(msg);
}

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

## Chapter 16. Portable extensions

CDI is intended to be a foundation for frameworks, extensions and integration with other technologies. Therefore, CDI exposes a set of SPIs for the use of developers of portable extensions to CDI. For example, the following kinds of extensions were envisaged by the designers of CDI:

• integration with Business Process Management engines,

• integration with third-party frameworks such as Spring, Seam, GWT or Wicket, and

• new technology based upon the CDI programming model.

More formally, according to the spec:

A portable extension may integrate with the container by:

• Providing its own beans, interceptors and decorators to the container

• Injecting dependencies into its own objects using the dependency injection service

• Providing a context implementation for a custom scope

• Augmenting or overriding the annotation-based metadata with metadata from some other source

## 16.2. Container lifecycle events

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

Extensions may observe these events:

class MyExtension implements Extension {

void beforeBeanDiscovery(@Observes BeforeBeanDiscovery bbd) {
Logger.global.debug("beginning the scanning process");
}

<T> void processAnnotatedType(@Observes ProcessAnnotatedType<T> pat) {
Logger.global.debug("scanning type: " + pat.getAnnotatedType().getJavaClass().getName());
}

void afterBeanDiscovery(@Observes AfterBeanDiscovery abd) {
Logger.global.debug("finished the scanning process");
}

}

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:

class MyExtension implements Extension {

<T> void processAnnotatedType(@Observes ProcessAnnotatedType<T> pat) {
//tell the container to ignore the type if it is annotated @Ignore
if ( pat.getAnnotatedType().isAnnotionPresent(Ignore.class) ) pat.veto();
}

}

The observer method may inject a BeanManager

<T> void processAnnotatedType(@Observes ProcessAnnotatedType<T> pat, BeanManager beanManager) { ... }

## 16.3. The BeanManager object

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

public interface BeanManager {
public Object getReference(Bean<?> bean, Type beanType, CreationalContext<?> ctx);
public Object getInjectableReference(InjectionPoint ij, CreationalContext<?> ctx);
public <T> CreationalContext<T> createCreationalContext(Contextual<T> contextual);
public Set<Bean<?>> getBeans(Type beanType, Annotation... qualifiers);
public Set<Bean<?>> getBeans(String name);
public Bean<?> getPassivationCapableBean(String id);
public <X> Bean<? extends X> resolve(Set<Bean<? extends X>> beans);
public void validate(InjectionPoint injectionPoint);
public void fireEvent(Object event, Annotation... qualifiers);
public <T> Set<ObserverMethod<? super T>> resolveObserverMethods(T event, Annotation... qualifiers);
public List<Decorator<?>> resolveDecorators(Set<Type> types, Annotation... qualifiers);
public List<Interceptor<?>> resolveInterceptors(InterceptionType type, Annotation... interceptorBindings);
public boolean isScope(Class<? extends Annotation> annotationType);
public boolean isNormalScope(Class<? extends Annotation> annotationType);
public boolean isPassivatingScope(Class<? extends Annotation> annotationType);
public boolean isQualifier(Class<? extends Annotation> annotationType);
public boolean isInterceptorBinding(Class<? extends Annotation> annotationType);
public boolean isStereotype(Class<? extends Annotation> annotationType);
public Set<Annotation> getInterceptorBindingDefinition(Class<? extends Annotation> bindingType);
public Set<Annotation> getStereotypeDefinition(Class<? extends Annotation> stereotype);
public Context getContext(Class<? extends Annotation> scopeType);
public ELResolver getELResolver();
public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
public <T> AnnotatedType<T> createAnnotatedType(Class<T> type);
public <T> InjectionTarget<T> createInjectionTarget(AnnotatedType<T> type);
}

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

@Inject BeanManager beanManager;

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.

## 16.4. The InjectionTarget interface

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.

//get the BeanManager from JNDI
BeanManager beanManager = (BeanManager) new InitialContext().lookup("java:comp/BeanManager");

//CDI uses an AnnotatedType object to read the annotations of a class
AnnotatedType<SomeFrameworkComponent> type = beanManager.createAnnotatedType(SomeFrameworkComponent.class);

//The extension uses an InjectionTarget to delegate instantiation, dependency injection
//and lifecycle callbacks to the CDI container
InjectionTarget<SomeFrameworkComponent> it = beanManager.createInjectionTarget(type);

//each instance needs its own CDI CreationalContext
CreationalContext ctx = beanManager.createCreationalContext(null);

//instantiate the framework component and inject its dependencies
SomeFrameworkComponent instance = it.produce(ctx);  //call the constructor
it.inject(instance, ctx);  //call initializer methods and perform field injection
it.postConstruct(instance);  //call the @PostConstruct method

...

//destroy the framework component instance and clean up dependent objects
it.preDestroy(instance);  //call the @PreDestroy method
it.dispose(instance);  //it is now safe to discard the instance
ctx.release();  //clean up dependent objects


## 16.5. The Bean interface

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.

public interface Bean<T> extends Contextual<T> {
public Set<Type> getTypes();
public Set<Annotation> getQualifiers();
public Class<? extends Annotation> getScope();
public String getName();
public Set<Class<? extends Annotation>> getStereotypes();
public Class<?> getBeanClass();
public boolean isAlternative();
public boolean isNullable();
public Set<InjectionPoint> getInjectionPoints();
}

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

Set<Bean<?>> allBeans = beanManager.getBeans(Obect.class, new AnnotationLiteral<Any>() {});

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.

## 16.6. Registering a Bean

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.

public class SecurityManagerExtension implements Extension {

void afterBeanDiscovery(@Observes AfterBeanDiscovery abd, BeanManager bm) {

//use this to read annotations of the class
AnnotatedType<SecurityManager> at = bm.createAnnotatedType(SecurityManager.class);

//use this to instantiate the class and inject dependencies
final InjectionTarget<SecurityManager> it = bm.createInjectionTarget(at);

@Override
public Class<?> getBeanClass() {
return SecurityManager.class;
}

@Override
public Set<InjectionPoint> getInjectionPoints() {
return it.getInjectionPoints();
}

@Override
public String getName() {
return "securityManager";
}

@Override
public Set<Annotation> getQualifiers() {
Set<Annotation> qualifiers = new HashSet<Annotation>();
return qualifiers;
}

@Override
public Class<? extends Annotation> getScope() {
return SessionScoped.class;
}

@Override
public Set<Class<? extends Annotation>> getStereotypes() {
return Collections.emptySet();
}

@Override
public Set<Type> getTypes() {
Set<Type> types = new HashSet<Type>();
return types;
}

@Override
public boolean isAlternative() {
return false;
}

@Override
public boolean isNullable() {
return false;
}

@Override
public SecurityManager create(CreationalContext<SecurityManager> ctx) {
SecurityManager instance = it.produce(ctx);
it.inject(instance, ctx);
it.postConstruct(instance);
return instance;
}

@Override
public void destroy(SecurityManager instance,
CreationalContext<SecurityManager> ctx) {
it.preDestroy(instance);
it.dispose(instance);
ctx.release();
}

} );
}

}

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

## 16.7. Wrapping an AnnotatedType

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.

public class QualifiedNameExtension implements Extension {

<X> void processAnnotatedType(@Observes ProcessAnnotatedType<X> pat) {

//wrap this to override the annotations of the class
final AnnotatedType<X> at = pat.getAnnotatedType();

AnnotatedType<X> wrapped = new AnnotatedType<X>() {

@Override
public Set<AnnotatedConstructor<X>> getConstructors() {
return at.getConstructors();
}

@Override
public Set<AnnotatedField<? super X>> getFields() {
return at.getFields();
}

@Override
public Class<X> getJavaClass() {
return at.getJavaClass();
}

@Override
public Set<AnnotatedMethod<? super X>> getMethods() {
return at.getMethods();
}

@Override
public <T extends Annotation> T getAnnotation(final Class<T> annType) {
if ( Named.class.equals(annType) ) {
class NamedLiteral
extends AnnotationLiteral<Named>
implements Named {
@Override
public String value() {
Package pkg = at.getClass().getPackage();
String unqualifiedName = at.getAnnotation(Named.class).value();
final String qualifiedName;
if ( pkg.isAnnotationPresent(Named.class) ) {
qualifiedName = pkg.getAnnotation(Named.class).value()
+ '.' + unqualifiedName;
}
else {
qualifiedName = unqualifiedName;
}
return qualifiedName;
}
}
return (T) new NamedLiteral();
}
else {
return at.getAnnotation(annType);
}
}

@Override
public Set<Annotation> getAnnotations() {
return at.getAnnotations();
}

@Override
public Type getBaseType() {
return at.getBaseType();
}

@Override
public Set<Type> getTypeClosure() {
return at.getTypeClosure();
}

@Override
public boolean isAnnotationPresent(Class<? extends Annotation> annType) {
return at.isAnnotationPresent(annType);
}

};

pat.setAnnotatedType(wrapped);
}

}

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

class ServiceAlternativeExtension implements Extension {

<T> void processAnnotatedType(@Observes ProcessAnnotatedType<T> pat) {

final AnnotatedType<T> type = pat.getAnnotatedType();

if ( Service.class.isAssignableFrom( type.getJavaClass() ) ) {

//if the class implements Service, make it an @Alternative
AnnotatedType<T> wrapped = new AnnotatedType<T>() {

@Override
public boolean isAnnotationPresent(Class<? extends Annotation> annotationType) {
return annotationType.equals(Alternative.class) ?
true : type.isAnnotationPresent(annotationType);
}

//remaining methods of AnnotatedType
...
}

pat.setAnnotatedType(wrapped);
}
}

}

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

## 16.8. Wrapping an InjectionTarget

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:

firstName=Gavin
lastName=King

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

public class ConfigExtension implements Extension {

<X> void processInjectionTarget(@Observes ProcessInjectionTarget<X> pit) {

//wrap this to intercept the component lifecycle
final InjectionTarget<X> it = pit.getInjectionTarget();

final Map<Field, Object> configuredValues = new HashMap<Field, Object>();

//use this to read annotations of the class and its members
AnnotatedType<X> at = pit.getAnnotatedType();

String propsFileName = at.getClass().getSimpleName() + ".properties";
InputStream stream = at.getJavaClass().getResourceAsStream(propsFileName);
if (stream!=null) {

try {
Properties props = new Properties();
for (Map.Entry<Object, Object> property : props.entrySet()) {
String fieldName = property.getKey().toString();
Object value = property.getValue();
try {
Field field = at.getJavaClass().getField(fieldName);
field.setAccessible(true);
if ( field.getType().isAssignableFrom( value.getClass() ) ) {
configuredValues.put(field, value);
}
else {
//TODO: do type conversion automatically
"field is not of type String: " + field ) );
}
}
catch (NoSuchFieldException nsfe) {
}
finally {
stream.close();
}
}
}
catch (IOException ioe) {
}
}

InjectionTarget<X> wrapped = new InjectionTarget<X>() {

@Override
public void inject(X instance, CreationalContext<X> ctx) {
it.inject(instance, ctx);

//set the values onto the new instance of the component
for (Map.Entry<Field, Object> configuredValue: configuredValues.entrySet()) {
try {
configuredValue.getKey().set(instance, configuredValue.getValue());
}
catch (Exception e) {
throw new InjectionException(e);
}
}
}

@Override
public void postConstruct(X instance) {
it.postConstruct(instance);
}

@Override
public void preDestroy(X instance) {
it.dispose(instance);
}

@Override
public void dispose(X instance) {
it.dispose(instance);
}

@Override
public Set<InjectionPoint> getInjectionPoints() {
return it.getInjectionPoints();
}

@Override
public X produce(CreationalContext<X> ctx) {
return it.produce(ctx);
}

};

pit.setInjectionTarget(wrapped);

}

}

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.

## 16.9. The Context interface

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

public interface Context {
public Class<? extends Annotation> getScope();
public <T> T get(Contextual<T> contextual, CreationalContext<T> creationalContext);
public <T> T get(Contextual<T> contextual);
boolean isActive();
}

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.

## Chapter 17. Next steps

The CDI reference implementation, Weld, is being developed at the Seam project. The RI development team and the CDI spec lead blog at in.relation.to. This guide was originally based on a series of blog entries published there while the specification was being developed. It's probably the best source of information about the future of CDI, Weld and Seam.

We encourage you to follow the weld-dev mailing list and to get involved in development. If you are reading this guide, you likely have something to offer.

# Part V. Weld Reference Guide

## 18.3. Servlet containers (such as Tomcat or Jetty)

While JSR-299 does not require support for servlet environments, Weld can be used in a servlet container, such as Tomcat 6.0 or Jetty 6.1.

Weld can be used as a library in an web application that is deployed to a Servlet container. You should place weld-servlet.jar within the WEB-INF/lib directory relative to the web root. weld-servlet.jar is an "uber-jar", meaning it bundles all the bits of Weld and CDI required for running in a Servlet container, for your convenience. Alternatively, you can use its component jars. A list of transitive dependencies can be found in the META-INF/DEPENDENCIES.txt file inside the weld-servlet.jar artifact.

You also need to explicitly specify the servlet listener (used to boot Weld, and control its interaction with requests) in WEB-INF/web.xml in the web root:


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


### 18.3.1. Tomcat

Tomcat has a read-only JNDI, so Weld can't automatically bind the BeanManager extension SPI. To bind the BeanManager into JNDI, you should populate META-INF/context.xml in the web root with the following contents:


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


and make it available to your deployment by adding this to the bottom of web.xml:


<resource-env-ref>
<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>


Tomcat only allows you to bind entries to java:comp/env, so the BeanManager will be available at java:comp/env/BeanManager

Weld also supports Servlet injection in Tomcat 6.

### 18.3.2. Jetty

Like Tomcat, Jetty has a read-only JNDI, so Weld can't automatically bind the BeanManager. To bind the BeanManager to JNDI in Jetty 6, you should populate WEB-INF/jetty-env.xml with the following contents:


<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN"
"http://jetty.mortbay.org/configure.dtd">
<Configure id="webAppCtx" class="org.mortbay.jetty.webapp.WebAppContext">
<New id="BeanManager" class="org.mortbay.jetty.plus.naming.Resource">
<Arg><Ref id="webAppCtx"/></Arg>
<Arg>BeanManager</Arg>
<Arg>
<New class="javax.naming.Reference">
<Arg>javax.enterprise.inject.spi.BeanManager</Arg>
<Arg>org.jboss.weld.resources.ManagerObjectFactory</Arg>
<Arg/>
</New>
</Arg>
</New>
</Configure>


Jetty 7 has moved to the Eclipse Foundation; if you are using Jetty 7 put the following in your WEB-INF/jetty-env.xml:


<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN"
"http://www.eclipse.org/jetty/configure.dtd">

<Configure id="webAppCtx" class="org.eclipse.jetty.webapp.WebAppContext">
<New id="BeanManager" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg> <Ref id="webAppCtx"/> </Arg>
<Arg>BeanManager</Arg>
<Arg>
<New class="javax.naming.Reference">
<Arg>javax.enterprise.inject.spi.BeanManager</Arg>
<Arg>org.jboss.weld.resources.ManagerObjectFactory</Arg>
<Arg/>
</New>
</Arg>
</New>
</Configure>


Just like in Tomcat, you need to make it available to your deployment by adding this to the bottom of web.xml:


<resource-env-ref>
<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>


Notice that Jetty doesn't not have built-in support for an javax.naming.spi.ObjectFactory like Tomcat, so it's necessary to manually create the javax.naming.Reference to wrap around it.

Jetty only allows you to bind entries to java:comp/env, so the BeanManager will be available at java:comp/env/BeanManager

Weld also supports Servlet injection in Jetty 6. To enable this, add the file META-INF/jetty-web.xml with the following content to your war:


<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN"
"http://jetty.mortbay.org/configure.dtd">
<Configure id="webAppCtx" class="org.mortbay.jetty.webapp.WebAppContext">
<Call class="org.jboss.weld.environment.jetty.WeldServletHandler" name="process">
<Arg><Ref id="webAppCtx"/></Arg>
</Call>
</Configure>


## 18.4. Java SE

In addition to improved integration of the Enterprise Java stack, the "Contexts and Dependency Injection for the Java EE platform" specification also defines a state of the art typesafe, stateful dependency injection framework, which can prove useful in a wide range of application types. To help developers take advantage of this, Weld provides a simple means for being executed in the Java Standard Edition (SE) environment independently of any Java EE APIs.

When executing in the SE environment the following features of Weld are available:

EJB beans are not supported.

### 18.4.1. CDI SE Module

Weld provides an extension which will boot a CDI bean manager in Java SE, automatically registering all simple beans found on the classpath. The command line parameters can be injected using either of the following:

@Inject @Parameters List<String> params;
@Inject @Parameters String[] paramsArray;

The second form is useful for compatibility with existing classes.

Here's an example of a simple CDI SE application:

@Singleton
public class HelloWorld
{
public void printHello(@Observes ContainerInitialized event, @Parameters List<String> parameters) {
System.out.println("Hello " + parameters.get(0));
}
}

### 18.4.2. Bootstrapping CDI SE

CDI SE applications can be bootstrapped in the following ways.

#### 18.4.2.2. Programatic Bootstrap API

For added flexibility, CDI SE also comes with a bootstrap API which can be called from within your application in order to initialize CDI and obtain references to your application's beans and events. The API consists of two classes: Weld and WeldContainer.

public class Weld
{

/** Boots Weld and creates and returns a WeldContainer instance, through which
* beans and events can be accesed. */
public WeldContainer initialize() {...}

/** Convenience method for shutting down the container. */
public void shutdown() {...}

}
public class WeldContainer
{

/** Provides access to all beans within the application. */
public Instance<Object> instance() {...}

/** Provides access to all events within the application. */
public Event<Object> event() {...}

/** Provides direct access to the BeanManager. */
public BeanManager getBeanManager() {...}

}

Here's an example application main method which uses this API to initialize a bean of type MyApplicationBean.

public static void main(String[] args) {
WeldContainer weld = new Weld().initialize();
weld.instance().select(MyApplicationBean.class).get();
weld.shutdown();
}

Alternatively the application could be started by firing a custom event which would then be observed by another simple bean. The following example fires MyEvent on startup.

public static void main(String[] args) {
WeldContainer weld = new Weld().initialize();
weld.event().select(MyEvent.class).fire( new MyEvent() );
weld.shutdown();
}

## 20.1. Excluding classes from scanning and deployment

Weld allows you to exclude classes in your archive from scanning, having container lifecycle events fired, and being deployed as beans.


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:weld="http://jboss.org/schema/weld/beans"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee http://docs.jboss.org/cdi/beans_1_0.xsd
http://jboss.org/schema/weld/beans http://jboss.org/schema/weld/beans_1_1.xsd">

<weld:scan>

<!-- Don't deploy the classes for the swing app! -->
<weld:exclude name="com.acme.swing.**" />

<!-- Don't include GWT support if GWT is not installed -->
<weld:exclude name="com.acme.gwt.**">
</weld:exclude>

<!--
Exclude classes which end in Blether if the system property verbosity is set to low
i.e.
java ... -Dverbosity=low
-->
<weld:exclude pattern="^(.*)Blether\$">
<weld:if-system-property name="verbosity" value="low"/>
</weld:exclude>

<!--
Don't include JSF support if Wicket classes are present, and the viewlayer system
property is not set
-->
<weld:exclude name="com.acme.jsf.**">
<weld:if-class-available name="org.apahce.wicket.Wicket"/>
<weld:if-system-property name="!viewlayer"/>
</weld:exclude>
</weld:scan>

</beans>


In this example we show the most common use cases for exercising fine control over which classes Weld scans. The first filter excludes all classes in the package com.acme.swing, and in most cases this will be sufficient for your needs.

However, sometimes it's useful to be able to activate the filter depending on the environment used. In this case, Weld allows you to activate (or deactivate) a filter based on either system properties or whether a class is available. The second filter shows the use case of disabling scanning of certain classes depending on the capabilities of the environment you deploy to - in this case we are excluding GWT support if GWT is not installed.

## Note

Notice how we use a ! character on the name attribute to invert the activation condition. You can invert any activation condition in this way.

The third filter uses a regular expression to select the classes to match (normally we use simple name-based patterns, as they don't require us to escape the period which delimits the package hierarchy).

## Note

If you specify just a system property name, Weld will activate the filter if that system property has been set (with any value). If you also specify the system property value, then Weld will only activate the filter if the system property's value matches exactly.

The fourth filter shows more a advanced configurations, where we use multiple activation conditions to decide whether to activate the filter.

You can combine as many activation conditions as you like (all must be true for the filter to be activated). If you want to a filter that is active if any of the activation conditions are true, then you need multiple identical filters, each with different activation conditions.

## Tip

In general, the semantics defined by Ant's pattern sets (http://ant.apache.org/manual/dirtasks.html#patternset) are followed.

## Appendix A. Integrating Weld into other environments

If you want to use Weld in another environment, you will need to provide certain information to Weld via the integration SPI. In this Appendix we will briefly discuss the steps needed.

All SPIs and APIs described have extensive JavaDoc, which spell out the detailed contract between the container and Weld.

## A.2. The contract with the container

There are a number of requirements that Weld places on the container for correct functioning that fall outside implementation of APIs.

If you are integrating Weld into an environment that supports deployment of multiple applications, you must enable, automatically, or through user configuation, classloader isolation for each CDI application.

Servlet

If you are integrating Weld into a Servlet environment you must register org.jboss.weld.servlet.WeldListener as a Servlet listener, either automatically, or through user configuration, for each CDI application which uses Servlet.

You must ensure that that WeldListener.contextInitialized() is called after beans are deployed is complete (Bootstrap.deployBeans() has been called).

JSF

If you are integrating Weld into a JSF environment you must register org.jboss.weld.jsf.WeldPhaseListener as a phase listener.

If you are integrating Weld into a JSF environment you must register org.jboss.weld.el.WeldELContextListener as an EL Context listener.

If you are integrating Weld into a JSF environment you must register org.jboss.weld.jsf.ConversationAwareViewHandler as a delegating view handler.

If you are integrating Weld into a JSF environment you must obtain the bean manager for the module and then call BeanManager.wrapExpressionFactory(), passing Application.getExpressionFactory() as the argument. The wrapped expression factory must be used in all EL expression evaluations performed by JSF in this web application.

If you are integrating Weld into a JSF environment you must obtain the bean manager for the module and then call BeanManager.getELResolver(), The returned EL resolver should be registered with JSF for this web application.

If you are integrating Weld into a JSF environment you must register org.jboss.weld.servlet.ConversationPropagationFilter as a Servlet listener, either automatically, or through user configuration, for each CDI application which uses JSF. This filter can be registered for all Servlet deployment safely.

## Note

Weld only supports JSF 1.2 and above.

JSP

If you are integrating Weld into a JSP environment you must register org.jboss.weld.el.WeldELContextListener as an EL Context listener.

If you are integrating Weld into a JSP environment you must obtain the bean manager for the module and then call BeanManager.wrapExpressionFactory(), passing Application.getExpressionFactory() as the argument. The wrapped expression factory must be used in all EL expression evaluations performed by JSP.

If you are integrating Weld into a JSP environment you must obtain the bean manager for the module and then call BeanManager.getELResolver(), The returned EL resolver should be registered with JSP for this web application.

Session Bean Interceptor

If you are integrating Weld into an EJB environment you must register the aroundInvoke method of org.jboss.weld.ejb.SessionBeanInterceptor as a EJB around-invoke interceptor for all EJBs in the application, either automatically, or through user configuration, for each CDI application which uses enterprise beans. If you are running in a EJB 3.1 environment, you should register this as an around-timeout interceptor as well.

The weld-core.jar

Weld can reside on an isolated classloader, or on a shared classloader. If you choose to use an isolated classloader, the default SingletonProvider, IsolatedStaticSingletonProvider, can be used. If you choose to use a shared classloader, then you will need to choose another strategy.

You can provide your own implementation of Singleton and SingletonProvider and register it for use using SingletonProvider.initialize(SingletonProvider provider).

Weld also provides an implementation of Thread Context Classloader per application strategy, via the TCCLSingletonProvider.

Binding the manager in JNDI

You should bind the bean manager for the bean deployment archive into JNDI at java:comp/BeanManager. The type should be javax.enterprise.inject.spi.BeanManager. To obtain the correct bean manager for the bean deployment archive, you may call bootstrap.getBeanManager(beanDeploymentArchive)

Performing CDI injection on Java EE component classes

The CDI specification requires the container to provide injection into non-contextual resources for all Java EE component classes. Weld delegates this responsibility to the container. This can be achieved using the CDI defined InjectionTarget SPI. Furthermore, you must perform this operation on the correct bean manager for the bean deployment archive containing the EE component class.

The CDI specification also requires that a ProcessInjectionTarget event is fired for every Java EE component class. Furthermore, if an observer calls ProcessInjectionTarget.setInjectionTarget() the container must use the specified injection target to perform injection.

To help the integrator, Weld provides WeldManager.fireProcessInjectionTarget() which returns the InjectionTarget to use.

// Fire ProcessInjectionTarget, returning the InjectionTarget
// to use
InjectionTarget it = weldBeanManager.fireProcessInjectionTarget(clazz);

// Per instance required, create the creational context
CreationalContext<?> cc = beanManager.createCreationalContext(null);

// Produce the instance, performing any constructor injection required
Object instance = it.produce();

// Perform injection and call initializers
it.inject(instance, cc);

// Call the post-construct callback
it.postConstruct(instance);

// Call the pre-destroy callback
it.preDestroy(instance);

// Clean up the instance
it.dispose();
cc.release();

The container may intersperse other operations between these calls. Further, the integrator may choose to implement any of these calls in another manner, assuming the contract is fulfilled.

When performing injections on EJBs you must use the Weld-defined SPI, WeldManager. Furthermore, you must perform this operation on the correct bean manager for the bean deployment archive containing the EJB.

// Obtain the EjbDescriptor for the EJB
// You may choose to use this utility method to get the descriptor
EjbDescriptor<?> ejbDescriptor = beanManager.getEjbDescriptor(ejbName);

// Get an the Bean object
Bean<?> bean = beanManager.getBean(ejbDescriptor);

// Create the injection target
InjectionTarget it = deploymentBeanManager.createInjectionTarget(ejbDescriptor);

// Per instance required, create the creational context
CreationalContext<?> cc = deploymentBeanManager.createCreationalContext(bean);

// Perform injection and call initializers
it.inject(instance, cc);

// You may choose to have CDI call the post construct and pre destroy
// lifecycle callbacks

// Call the post-construct callback
it.postConstruct(instance);

// Call the pre-destroy callback
it.preDestroy(instance);

// Clean up the instance
it.dispose();
cc.release();