Decorators

Weld 6.0.0.CR2 - CDI Reference Implementation

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.

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:

has the type of the delegate injection point as a bean type, and
has all qualifiers that are declared at the delegate injection point.

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

Enabling decorators

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

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

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

it enables us to specify an ordering for decorators in our system, ensuring deterministic behavior, and
it lets us enable or disable decorator classes at deployment time.

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

Note	A decorator enabled by `@Priority` and in the same time listed in beans.xml is only invoked once in the `@Priority` part of the invocation chain. E.g. the enablement via `beans.xml` will be ignored.