Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

11.2. Use CDI

11.2.1. First Steps

11.2.1.1. Enable CDI

Summary

Contexts and Dependency Injection (CDI) is one of the core technologies in JBoss EAP 6, and is enabled by default. If for some reason it is disabled and you need to enable it, follow this procedure.

Procedure 11.1. Enable CDI in JBoss EAP 6

  1. Check to see if the CDI subsystem details are commented out of the configuration file.

    A subsystem can be disabled by commenting out the relevant section of the domain.xml or standalone.xml configuration files, or by removing the relevant section altogether.
    To find the CDI subsystem in EAP_HOME/domain/configuration/domain.xml or EAP_HOME/standalone/configuration/standalone.xml, search them for the following string. If it exists, it is located inside the <extensions> section.
    <extension module="org.jboss.as.weld"/>
    The following line must also be present in the profile you are using. Profiles are in individual <profile> elements within the <profiles> section.
    <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
  2. Before editing any files, stop JBoss EAP 6.

    JBoss EAP 6 modifies the configuration files during the time it is running, so you must stop the server before you edit the configuration files directly.
  3. Edit the configuration file to restore the CDI subsystem.

    If the CDI subsystem was commented out, remove the comments.
    If it was removed entirely, restore it by adding this line to the file in a new line directly above the </extensions> tag:
    <extension module="org.jboss.as.weld"/>
  4. You also need to add the following line to the relevant profile in the <profiles> section.
    <subsystem xmlns="urn:jboss:domain:weld:1.0"/>
  5. Restart JBoss EAP 6.

    Start JBoss EAP 6 with your updated configuration.
Result

JBoss EAP 6 starts with the CDI subsystem enabled.

11.2.2. Use CDI to Develop an Application

11.2.2.2. Use CDI with Existing Code

Almost every concrete Java class that has a constructor with no parameters, or a constructor designated with the annotation @Inject, is a bean. The only thing you need to do before you can start injecting beans is create a file called beans.xml in the META-INF/ or WEB-INF/ directory of your archive. The file can be empty.

Procedure 11.2. Use legacy beans in CDI applications

  1. Package your beans into an archive.

    Package your beans into a JAR or WAR archive.
  2. Include a beans.xml file in your archive.

    Place a beans.xml file into your JAR archive's META-INF/ or your WAR archive's WEB-INF/ directory. The file can be empty.
Result:

You can use these beans with CDI. The container can create and destroy instances of your beans and associate them with a designated context, inject them into other beans, use them in EL expressions, specialize them with qualifier annotations, and add interceptors and decorators to them, without any modifications to your existing code. In some circumstances, you may need to add some annotations.

11.2.2.3. Exclude Beans From the Scanning Process

Summary

One of the features of Weld, the JBoss EAP 6 implementation of CDI, is the ability to exclude classes in your archive from scanning, having container lifecycle events fired, and being deployed as beans. This is not part of the JSR-299 specification.

Example 11.1. Exclude packages from your bean

The following example has several <weld:exclude> tags.
  1. The first one excludes all Swing classes.
  2. The second excludes Google Web Toolkit classes if Google Web Toolkit is not installed.
  3. The third excludes classes which end in the string Blether (using a regular expression), if the system property verbosity is set to low.
  4. The fourth excludes Java Server Faces (JSF) classes if Wicket classes are present and the viewlayer system property is not set.
<?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:if-class-available name="!com.google.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.apache.wicket.Wicket"/>
            <weld:if-system-property name="!viewlayer"/>
        </weld:exclude>
    </weld:scan>
</beans>
The formal specification of Weld-specific configuration options can be found at http://jboss.org/schema/weld/beans_1_1.xsd.

11.2.2.4. Use an Injection to Extend an Implementation

Summary

You can use an injection to add or change a feature of your existing code. This example shows you how to add a translation ability to an existing class. The translation is a hypothetical feature and the way it is implemented in the example is pseudo-code, and only provided for illustration.

The example assumes you already have a Welcome class, which has a method buildPhrase. The buildPhrase method takes as an argument the name of a city, and outputs a phrase like "Welcome to Boston." Your goal is to create a version of the Welcome class which can translate the greeting into a different language.

Example 11.2. Inject a Translator Bean Into the Welcome Class

The following pseudo-code injects a hypothetical Translator object into the Welcome class. The Translator object may be an EJB stateless bean or another type of bean, which can translate sentences from one language to another. In this instance, the Translator is used to translate the entire greeting, without actually modifying the original Welcome class at all. The Translator is injected before the buildPhrase method is implemented.
The code sample below is an example Translating Welcome class.
public class TranslatingWelcome extends Welcome {

    @Inject Translator translator;

    public String buildPhrase(String city) {
        return translator.translate("Welcome to " + city + "!");
    }
    ...
}

11.2.3. Ambiguous or Unsatisfied Dependencies

11.2.3.1. About Ambiguous or Unsatisfied Dependencies

Ambiguous dependencies exist when the container is unable to resolve an injection to exactly one bean.
Unsatisfied dependencies exist when the container is unable to resolve an injection to any bean at all.
The container takes the following steps to try to resolve dependencies:
  1. It resolves the qualifier annotations on all beans that implement the bean type of an injection point.
  2. It filters out disabled beans. Disabled beans are @Alternative beans which are not explicitly enabled.
In the event of an ambiguous or unsatisfied dependency, the container aborts deployment and throws an exception.

11.2.3.2. About Qualifiers

A qualifier is an annotation which ties a bean to a bean type. It allows you to specify exactly which bean you mean to inject. Qualifiers have a retention and a target, which are defined as in the example below.

Example 11.3. Define the @Synchronous and @Asynchronous Qualifiers

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

Example 11.4. Use the @Synchronous and @Asynchronous Qualifiers

@Synchronous
public class SynchronousPaymentProcessor implements PaymentProcessor {

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

}
@Asynchronous
public class AsynchronousPaymentProcessor implements PaymentProcessor {

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

11.2.3.3. Use a Qualifier to Resolve an Ambiguous Injection

Summary

This task shows an ambiguous injection and removes the ambiguity with a qualifier. Read more about ambiguous injections at Section 11.2.3.1, “About Ambiguous or Unsatisfied Dependencies”.

Example 11.5. Ambiguous injection

You have two implementations of Welcome, one which translates and one which does not. In that situation, the injection below is ambiguous and needs to be specified to use the translating Welcome.
public class Greeter {
  private Welcome welcome;

  @Inject
  void init(Welcome welcome) {
    this.welcome = welcome;
  }
  ...
}

Procedure 11.3. Resolve an Ambiguous Injection with a Qualifier

  1. Create a qualifier annotation called @Translating.

    @Qualifier
    @Retention(RUNTIME)
    @Target({TYPE,METHOD,FIELD,PARAMETERS})
    public @interface Translating{}
    
  2. Annotate your translating Welcome with the @Translating annotation.

    @Translating
    public class TranslatingWelcome extends Welcome {
        @Inject Translator translator;
        public String buildPhrase(String city) {
            return translator.translate("Welcome to " + city + "!");
        }
        ...
    }
    
  3. Request the translating Welcome in your injection.

    You must request a qualified implementation explicitly, similar to the factory method pattern. The ambiguity is resolved at the injection point.
    public class Greeter {
      private Welcome welcome;
      @Inject
      void init(@Translating Welcome welcome) {
        this.welcome = welcome;
      } 
      public void welcomeVisitors() {
        System.out.println(welcome.buildPhrase("San Francisco"));
      }
    }
    
Result

The TranslatingWelcome is used, and there is no ambiguity.

11.2.4. Managed Beans

11.2.4.1. About Managed Beans

Prior to Java EE 6, there was no clear definition of the term bean in the Java EE platform. There were several concepts referred to as beans in the Java EE specifications, including EJB beans and JSF managed beans. Third-party frameworks such as Spring and Seam introduced their own ideas of what defined a bean.
Java EE 6 established a common definition in the Managed Beans specification. Managed Beans are defined as container-managed objects with minimal programming restrictions, otherwise known by the acronym POJO (Plain Old Java Object). They support a small set of basic services, such as resource injection, lifecycle callbacks and interceptors. Companion specifications, such as EJB and CDI, build on this basic model.
With very few exceptions, almost every concrete Java class that has a constructor with no parameters (or a constructor designated with the annotation @Inject) is a bean. This includes every JavaBean and every EJB session bean. The only requirement to enable the mentioned services in beans is that they reside in an archive (a JAR, or a Java EE module such as a WAR or EJB JAR) that contains a special marker file: META-INF/beans.xml.

11.2.4.2. Types of Classes That are Beans

A managed bean is a Java class. The basic lifecycle and semantics of a managed bean are defined by the Managed Beans specification. You can explicitly declare a managed bean by annotating the bean class @ManagedBean, but in CDI you do not need to. According to the specification, the CDI container treats any class that satisfies the following conditions as a managed bean:
  • It is not a non-static inner class.
  • It is a concrete class, or is annotated @Decorator.
  • It is not annotated with an EJB component-defining annotation or declared as an EJB bean class in ejb-jar.xml.
  • It does not implement interface javax.enterprise.inject.spi.Extension.
  • It has either a constructor with no parameters, or a constructor annotated with @Inject.
The unrestricted set of bean types for a managed bean contains the bean class, every superclass and all interfaces it implements directly or indirectly.
If a managed bean has a public field, it must have the default scope @Dependent.

11.2.4.3. Use CDI to Inject an Object Into a Bean

When your deployment archive includes a META-INF/beans.xml or WEB-INF/beans.xml file, each object in your deployment can be injected using CDI.
This procedure introduces the main ways to inject objects into other objects.
  1. Inject an object into any part of a bean with the @Inject annotation.

    To obtain an instance of a class, within your bean, annotate the field with @Inject.

    Example 11.6. Injecting a TextTranslator instance into a TranslateController

    public class TranslateController {
    
       @Inject TextTranslator textTranslator;
       ...
    
  2. Use your injected object's methods

    You can use your injected object's methods directly. Assume that TextTranslator has a method translate.

    Example 11.7. Use your injected object's methods

    // in TranslateController class
    
    public void translate() {
    
       translation = textTranslator.translate(inputText); 
    
    }
    
  3. Use injection in the constructor of a bean

    You can inject objects into the constructor of a bean, as an alternative to using a factory or service locator to create them.

    Example 11.8. Using injection in the constructor of a bean

    public class TextTranslator {
    
       private SentenceParser sentenceParser;
    
       private Translator sentenceTranslator;
    
        
    
       @Inject
    
       TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator) {
    
          this.sentenceParser = sentenceParser;
    
          this.sentenceTranslator = sentenceTranslator;
    
       }
    
       // Methods of the TextTranslator class
       ...
    }
    
  4. Use the Instance(<T>) interface to get instances programmatically.

    The Instance interface can return an instance of TextTranslator when parameterized with the bean type.

    Example 11.9. Obtaining an instance programmatically

    @Inject Instance<TextTranslator> textTranslatorInstance;
    
    ...
    
    public void translate() {
    
       textTranslatorInstance.get().translate(inputText);
    
    }
    
Result:

When you inject an object into a bean all of the object's methods and properties are available to your bean. If you inject into your bean's constructor, instances of the injected objects are created when your bean's constructor is called, unless the injection refers to an instance which already exists. For instance, a new instance would not be created if you inject a session-scoped bean during the lifetime of the session.

11.2.5. Contexts, Scopes, and Dependencies

11.2.5.1. Contexts and Scopes

A context, in terms of CDI, is a storage area which holds instances of beans associated with a specific scope.
A scope is the link between a bean and a context. A scope/context combination may have a specific lifecycle. Several pre-defined scopes exist, and you can create your own scopes. Examples of pre-defined scopes are @RequestScoped, @SessionScoped, and @ConversationScope.

11.2.5.2. Available Contexts

Table 11.1. Available contexts

Context Description
@Dependent The bean is bound to the lifecycle of the bean holding the reference.
@ApplicationScoped Bound to the lifecycle of the application.
@RequestScoped Bound to the lifecycle of the request.
@SessionScoped Bound to the lifecycle of the session.
@ConversationScoped Bound to the lifecycle of the conversation. The conversation scope is between the lengths of the request and the session, and is controlled by the application.
Custom scopes If the above contexts do not meet your needs, you can define custom scopes.

11.2.6. Bean Lifecycle

11.2.6.1. Manage the Lifecycle of a Bean

Summary

This task shows you how to save a bean for the life of a request. Several other scopes exist, and you can define your own scopes.

The default scope for an injected bean is @Dependent. This means that the bean's lifecycle is dependent upon the lifecycle of the bean which holds the reference. For more information, see Section 11.2.5.1, “Contexts and Scopes”.

Procedure 11.4. Manage Bean Lifecycles

  1. Annotate the bean with the scope corresponding to your desired scope.

    @RequestScoped
    @Named("greeter")
    public class GreeterBean {
      private Welcome welcome;
      private String city; // getter & setter not shown
      @Inject   void init(Welcome welcome) {
        this.welcome = welcome;
      }
      public void welcomeVisitors() {
        System.out.println(welcome.buildPhrase(city));
      }
    }
    
  2. When your bean is used in the JSF view, it holds state.

    <h:form>
      <h:inputText value="#{greeter.city}"/>
      <h:commandButton value="Welcome visitors" action="#{greeter.welcomeVisitors}"/>
    </h:form>
Result:

Your bean is saved in the context relating to the scope that you specify, and lasts as long as the scope applies.

11.2.6.2. Use a Producer Method

Summary

This task shows how to use producer methods to produce a variety of different objects which are not beans for injection.

Example 11.10. Use a producer method instead of an alternative, to allow polymorphism after deployment

The @Preferred annotation in the example is a qualifier annotation. For more information about qualifiers, refer to: Section 11.2.3.2, “About Qualifiers”.
@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();
           default: return null;
       } 
   }
}
The following 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 is called by the container to obtain an instance to service this injection point.
@Inject @Preferred PaymentStrategy paymentStrategy;

Example 11.11. Assign a scope to a producer method

The default scope of a producer method is @Dependent. If you assign a scope to a bean, it is bound to the appropriate context. The producer method in this example is only called once per session.
@Produces @Preferred @SessionScoped
public PaymentStrategy getPaymentStrategy() {
   ...
}

Example 11.12. Use an injection inside a producer method

Objects instantiated directly by an application cannot take advantage of dependency injection and do not have interceptors. However, you can use dependency injection into the producer method to obtain bean instances.
@Produces @Preferred @SessionScoped
public PaymentStrategy getPaymentStrategy(CreditCardPaymentStrategy ccps,
                                          CheckPaymentStrategy cps ) {
   switch (paymentStrategy) {
      case CREDIT_CARD: return ccps;
      case CHEQUE: return cps;
      default: return null;
   } 
}

If you inject a request-scoped bean into a session-scoped producer, the producer method promotes the current request-scoped instance into session scope. This is almost certainly not the desired behavior, so use caution when you use a producer method in this way.

Note

The scope of the producer method is not inherited from the bean that declares the producer method.
Result

Producer methods allow you to inject non-bean objects and change your code dynamically.

11.2.7. Named Beans and Alternative Beans

11.2.7.1. About Named Beans

A bean is named by using the @Named annotation. Naming a bean allows you to use it directly in Java Server Faces (JSF).
The @Named annotation takes an optional parameter, which is the bean name. If this parameter is omitted, the lower-cased bean name is used as the name.

11.2.7.2. Use Named Beans

  1. Use the @Named annotation to assign a name to a bean.

    @Named("greeter")
    public class GreeterBean {
      private Welcome welcome;
    
      @Inject
      void init (Welcome welcome) {
        this.welcome = welcome;
      }
    
      public void welcomeVisitors() {
        System.out.println(welcome.buildPhrase("San Francisco"));
      }
    }
    
    The bean name itself is optional. If it is omitted, the bean is named after the class name, with the first letter decapitalized. In the example above, the default name would be greeterBean.
  2. Use the named bean in a JSF view.

    <h:form>
      <h:commandButton value="Welcome visitors" action="#{greeter.welcomeVisitors}"/>
    </h:form>
Result:

Your named bean is assigned as an action to the control in your JSF view, with a minimum of coding.

11.2.7.3. About Alternative Beans

Alternatives are beans whose implementation is specific to a particular client module or deployment scenario.

Example 11.13. Defining Alternatives

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. They are enabled for a specific bean archive by editing its beans.xml file.

11.2.7.4. Override an Injection with an Alternative

Summary

Alternative beans let you override existing beans. They can be thought of as a way to plug in a class which fills the same role, but functions differently. They are disabled by default. This task shows you how to specify and enable an alternative.

Procedure 11.5. Override an Injection

This task assumes that you already have a TranslatingWelcome class in your project, but you want to override it with a "mock" TranslatingWelcome class. This would be the case for a test deployment, where the true Translator bean cannot be used.
  1. Define the alternative.

    @Alternative
    @Translating 
    public class MockTranslatingWelcome extends Welcome {
      public String buildPhrase(string city) {
        return "Bienvenue à " + city + "!");
      }
    }
    
  2. Substitute the alternative.

    To activate the substitute implementation, add the fully-qualified class name to your META-INF/beans.xml or WEB-INF/beans.xml file.
    <beans>
      <alternatives>
        <class>com.acme.MockTranslatingWelcome</class>
      </alternatives>
    </beans>
Result

The alternative implementation is now used instead of the original one.

11.2.8. Stereotypes

11.2.8.1. About Stereotypes

In many systems, use of architectural patterns produces a set of recurring bean roles. A stereotype allows you 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:
  • default scope
  • a set of interceptor bindings
A stereotype may also specify either of these two scenarios:
  • all beans with the stereotype have defaulted bean EL names
  • 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.
A class that inherits a scope from a stereotype may override that stereotype and specify a scope directly on the bean.
In addition, if a stereotype has a @Named annotation, any bean it is placed on has a default bean name. The bean may override this name if the @Named annotation is specified directly on the bean. For more information about named beans, see Section 11.2.7.1, “About Named Beans”.

11.2.8.2. Use Stereotypes

Summary

Without stereotypes, annotations can become cluttered. This task shows you how to use stereotypes to reduce the clutter and streamline your code. For more information about what stereotypes are, see Section 11.2.8.1, “About Stereotypes”.

Example 11.14. Annotation clutter

@Secure
@Transactional
@RequestScoped
@Named
public class AccountManager {
  public boolean transfer(Account a, Account b) {
    ...
  }
}

Procedure 11.6. Define and Use Stereotypes

  1. Define the stereotype,

    @Secure
    @Transactional
    @RequestScoped
    @Named
    @Stereotype
    @Retention(RUNTIME)
    @Target(TYPE)
    public @interface BusinessComponent {
     ...
    }
    
  2. Use the stereotype.

    @BusinessComponent
    public class AccountManager {
      public boolean transfer(Account a, Account b) {
        ...
      }
    }
    
Result:

Stereotypes streamline and simplify your code.

11.2.9. Observer Methods

11.2.9.1. About Observer Methods

Observer methods receive notifications when events occur.
CDI also provides transactional observer methods, which receive event notifications during the before completion or after completion phase of the transaction in which the event was fired.

11.2.9.2. Transactional Observers

Transactional observers receive the event notifications before or after the completion phase of the transaction in which the event was raised. For example, the following observer method refreshes a query result set cached in the application context, but only when transactions that update the Category tree are successful:
public void refreshCategoryTree(@Observes(during = AFTER_SUCCESS) CategoryUpdateEvent event) { ... }
There are five kinds of transactional observers:
  • IN_PROGRESS: By default, observers are invoked immediately.
  • AFTER_SUCCESS: Observers are invoked after the completion phase of the transaction, but only if the transaction completes successfully.
  • AFTER_FAILURE: Observers are invoked after the completion phase of the transaction only if the transaction fails to complete successfully.
  • AFTER_COMPLETION: Observers are invoked after the completion phase of the transaction.
  • BEFORE_COMPLETION: Observers are invoked before the completion phase of the transaction.
Transactional observers are important in a stateful object model because state is often held for longer than a single atomic transaction.
Assume we have cached a JPA query result set in the application scope:
	
import javax.ejb.Singleton;
import javax.enterprise.inject.Produces;

@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;
   }
}
Occasionally a Product is created or deleted. When this occurs, we need to refresh the Product catalog. But we have to wait for the transaction to complete successfully before performing this refresh.
The bean that creates and deletes Products triggers events, for example:
	
import javax.enterprise.event.Event;

@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);
   }
   ...
}
The Catalog can now observe the events after successful completion of the transaction:
	
import javax.ejb.Singleton;

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

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

}

11.2.9.3. Fire and Observe Events

Example 11.15. Fire an event

This code shows an event being injected and used in a method.
public class AccountManager {
  @Inject Event<Withdrawal> event;
  
  public boolean transfer(Account a, Account b) {
    ...
    event.fire(new Withdrawal(a));
  }
}

Example 11.16. Fire an event with a qualifier

You can annotate your event injection with a qualifier, to make it more specific. For more information about qualifiers, see Section 11.2.3.2, “About Qualifiers”.
public class AccountManager {
  @Inject @Suspicious Event <Withdrawal> event;
  
  public boolean transfer(Account a, Account b) {
    ...
    event.fire(new Withdrawal(a));
  }
}

Example 11.17. Observe an event

To observe an event, use the @Observes annotation.
public class AccountObserver {
  void checkTran(@Observes Withdrawal w) {
    ...
  }
}

Example 11.18. Observe a qualified event

You can use qualifiers to observe only specific types of events. For more information about qualifiers, see Section 11.2.3.2, “About Qualifiers”.
public class AccountObserver {
  void checkTran(@Observes @Suspicious Withdrawal w) {
    ...
  }
}

11.2.10. Interceptors

11.2.10.1. About Interceptors

Interceptors are defined as part of the Enterprise JavaBeans specification, which can be found at http://jcp.org/aboutJava/communityprocess/final/jsr318/. Interceptors allow you to add functionality to the business methods of a bean without modifying the bean's method directly. The interceptor is executed before any of the business methods of the bean.
CDI enhances this functionality by allowing you to use annotations to bind interceptors to beans.

Interception points

business method interception
A business method interceptor applies to invocations of methods of the bean by clients of the bean.
lifecycle callback interception
A lifecycle callback interceptor applies to invocations of lifecycle callbacks by the container.
timeout method interception
A timeout method interceptor applies to invocations of the EJB timeout methods by the container.

11.2.10.2. Use Interceptors with CDI

Example 11.19. Interceptors without CDI

Without CDI, interceptors have two problems.
  • The bean must specify the interceptor implementation directly.
  • Every bean in the application must specify the full set of interceptors in the correct order. This makes adding or removing interceptors on an application-wide basis time-consuming and error-prone.
@Interceptors({
  SecurityInterceptor.class,
  TransactionInterceptor.class,
  LoggingInterceptor.class
})
@Stateful public class BusinessComponent {
  ...
}

Procedure 11.7. Use interceptors with CDI

  1. Define the interceptor binding type.

    @InterceptorBinding
    @Retention(RUNTIME)
    @Target({TYPE, METHOD})
    public @interface Secure {}
    
  2. Mark the interceptor implementation.

    @Secure
    @Interceptor
    public class SecurityInterceptor {
      @AroundInvoke
      public Object aroundInvoke(InvocationContext ctx) throws Exception {
        // enforce security ...
        return ctx.proceed();
        }
    }
    
  3. Use the interceptor in your business code.

    @Secure
    public class AccountManager {
      public boolean transfer(Account a, Account b) {
        ...
      }
    }
    
  4. Enable the interceptor in your deployment, by adding it to META-INF/beans.xml or WEB-INF/beans.xml.

    <beans>
      <interceptors>
        <class>com.acme.SecurityInterceptor</class>
        <class>com.acme.TransactionInterceptor</class>
      </interceptors>
    </beans>
    The interceptors are applied in the order listed.
Result:

CDI simplifies your interceptor code and makes it easier to apply to your business code.

11.2.11. About Decorators

A decorator intercepts invocations from a specific Java interface, and is aware of all the semantics attached to that interface. Decorators are useful for modeling some kinds of business concerns, but do not have the generality of interceptors. They are a bean, or even an abstract class, that implements the type it decorates, and are annotated with @Decorator. To invoke a decorator in a CDI application, it must be specified in the beans.xml file.

Example 11.20. Example Decorator

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

      ...

   }

}
A decorator must have exactly one @Delegate injection point to obtain a reference to the decorated object.

11.2.12. About 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. Extensions can provide the following types of functionality:
  • integration with Business Process Management engines
  • integration with third-party frameworks such as Spring, Seam, GWT or Wicket
  • new technology based upon the CDI programming model
According to the JSR-299 specification, a portable extension may integrate with the container in the following ways:
  • 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

11.2.13. Bean Proxies

11.2.13.1. About Bean Proxies

Clients of an injected bean do not usually hold a direct reference to a bean instance. Unless the bean is a dependent object (scope @Dependent), the container must redirect all injected references to the bean using a proxy object.
This bean proxy referred to as client proxy is responsible for ensuring the bean instance that receives a method invocation is the instance associated with the current context. The client proxy also allows beans bound to contexts such as the session context to be serialized to disk without recursively serializing other injected beans.
Due to Java limitations, some Java types cannot be proxied by the container. If an injection point declared with one of these types resolves to a bean with any scope other than @Dependent, the container aborts the deployment.

Java types that cannot be proxied by the container

  • Classes which do not have a non-private constructor with no parameters
  • Classes which are declared final or have a final method
  • Arrays and primitive types

11.2.13.2. Use a Proxy in an Injection

Overview

A proxy is used for injection when the lifecycles of the beans are different from each other. The proxy is a subclass of the bean that is created at run-time, and overrides all the non-private methods of the bean class. The proxy forwards the invocation onto the actual bean instance.

In this example, the PaymentProcessor instance is not injected directly into Shop. Instead, a proxy is injected, and when the processPayment() method is called, the proxy looks up the current PaymentProcessor bean instance and calls the processPayment() method on it.

Example 11.21. Proxy Injection

@ConversationScoped
class PaymentProcessor
{
  public void processPayment(int amount)
  {
    System.out.println("I'm taking $" + amount);
  }
}
 
@ApplicationScoped
public class Shop
{
 
  @Inject
  PaymentProcessor paymentProcessor; 
 
  public void buyStuff()
  {
    paymentProcessor.processPayment(100);
  }
}
Fore more information about proxies, including which types of classes can be proxied, refer to Section 11.2.13.1, “About Bean Proxies”.