Weld Extensions provides a number enhancements to the CDI programming model which are under trial and may be included in later releases of Contexts and Dependency Injection.

@Veto

class Utilities {

   ...

}

@Requires(EntityManager.class)

class EntityManagerProducer {

   

   @Produces

   EntityManager getEntityManager() {

      ...

   }

   

}

interface PaymentService { 

   ...

}

class ChequePaymentService implements PaymentService { 

   ...

}

class CardPaymentService implements PaymentService { 

   ...

}

class PaymentProcessor { 

   

   @Inject @Exact(CardPaymentService.class)

   PaymentService paymentService;

   

   ...

   

}

@Named

package com.acme

Weld extensions provides a complete set of AnnotationLiterals for every annotation type defined by the CDI (JSR-299) and Injection (JSR-330) specification. These are located in the org.jboss.weld.extensions.literal package. Annotations without listitems provide a static INSTANCE listitem that should be used rather than creating a new instance every time.

Literals are provided for the following annotations from Context and Dependency Injection:

Literals are provided for the following annotations from Weld Extensions:

Weld extensions provides a method to evaluate EL that is not dependent on JSF or JSP, a facility sadly missing in Java EE. To use it inject Expressions into your bean. You can evaluate value expressions, or method expressions. The Weld Extensions API provides type inference for you. For example:

class FruitBowl {

   

   @Inject Expressions expressions;

  

   public void run() {

      String fruitName = expressions.evaluateValueExpression("#{fruitBowl.fruitName}");

      Apple fruit = expressions.evaluateMethodExpression("#{fruitBown.getFruit}");

   }

}

Weld Extensions provides an extensible, injectable resource loader. The resource loader can provide URLs or managed input streams. By default the resource loader will look at the classpath, and the servlet context if available.

If the resource name is known at development time, the resource can be injected, either as a URL or an InputStream:

   @Inject

   @Resource("WEB-INF/beans.xml")

   URL beansXml;


   @Inject

   @Resource("WEB-INF/web.xml")

   InputStream webXml;

If the resource name is not known, the ResourceProvider can be injected, and the resource looked up dynamically:

   @Inject

   void readXml(ResourceProvider provider, String fileName) {

      InputStream is = provider.loadResourceStream(fileName);

   }

If you need access to all resources under a given name known to the resource loader (as opposed to first resource loaded), you can inject a collection of resources:

   @Inject

   @Resource("WEB-INF/beans.xml")

   Collection<URL> beansXmls;


   @Inject

   @Resource("WEB-INF/web.xml")

   Collection<InputStream> webXmls;

If the resource is a Properties bundle, you can also inject it as a set of Properties:

   @Inject

   @Resource("META-INF/aws.properties")

   Properties awsProperties;

class MyResourceLoader implements ResourceLoader {

   ...

}

Weld Extensions integrates JBoss Logging 3 as it's logging framework of choice. JBoss Logging 3 is a modern logging framework offering:

To use a typed logger, first create the logger definition:

@MessageLogger

interface TrainSpotterLog {


   // Define log call with message, using printf-style interpolation of parameters

   @LogMessage @Message("Spotted %s diesel trains") 

   void dieselTrainsSpotted(int number);


}

You can then inject the typed logger with no further configuration:

   // Use the train spotter log, with the log category "trains"

   @Inject @Category("trains") TrainSpotterLog log;

and use it:

log.dieselTrainsSpotted(7);

JBoss Logging will use the default locale unless overridden:

   // Use the train spotter log, with the log category "trains", and select the UK locale

   @Inject @Category("trains") @Locale("en_GB") TrainSpotterLog log;

You can also log exceptions:

@MessageLogger

interface TrainSpotterLog {


   // Define log call with message, using printf-style interpolation of parameters

   // The exception parameter will be logged as an exception

   @LogMessage @Message("Failed to spot train %s") 

   void missedTrain(String trainNumber,@Cause Exception exception);


}

You can then log a message with an exception:

log.missedTrain("RH1", cause);

You can also inject a "plain old" Logger:

   @Inject Logger log;

Typed loggers also provide internationalization support, simply add the @MessageBundle annotation to the logger interface (not currently supported).

Sometimes you need to access the message directly (for example to localize an exception message). Weld Extensions let's you inject a typed message bundle. First, declare the message bundle:

@MessageBundle

interface TrainMessages {


   // Define a message using printf-style interpolation of parameters

   @Message("No trains spotted due to %s") 

   String noTrainsSpotted(String cause);


}

Inject it:

@Inject @MessageBundle TrainMessages messages;

And use it:

   throw new BadDayException(messages.noTrainsSpotted("leaves on the line"));

Weld Extensions provides a number of utilility classes to make working with Annotations and AnnotatedTypes easier. This chapter will walk you each utility, and give you an idea of how to use it. For more detail, take a look at the javaodoc on each class.

AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder()

      .readFromType(baseType,true) /* readFromType can read from an AnnotatedType or a class */

      .addToClass(ModelLiteral.INSTANCE) /* add the @Model annotation */

      .create();

AnnotatedTypeBuilder builder = new AnnotatedTypeBuilder()

      .readFromType(baseType,true)

      .redefine(Unique.class, new AnnotationRedefiner<Unique>() {

      

         public void redefine(RedefinitionContext<A> ctx) {

            ctx.getAnnotationBuilder().remove(Unique.class);

         }

            

      }

      .create();

@Retention(RetentionPolicy.RUNTIME)

public @interface MultipleMembers {

   int intMember();


   long longMember();


   short shortMember();


   float floatMember();


   double doubleMember();


   byte byteMember();


   char charMember();


   boolean booleanMember();


   int[] intArrayMember();

}

/* Create a new provider */

   AnnotationInstanceProvider provider = new AnnotationInstanceProvider();


    /* Set the value for each of attributes */

    Map<String, Object> values = new HashMap<String, Object>();

    values.put("intMember", 1);

    values.put("longMember", 1);

    values.put("shortMember", 1);

    values.put("floatMember", 0);

    values.put("doubleMember", 0);

    values.put("byteMember", ((byte) 1));

    values.put("charMember", 'c');

    values.put("booleanMember", true);

    values.put("intArrayMember", new int[] { 0, 1 });

    

    /* Generate the instance */

    MultipleMembers an = provider.get(MultipleMembers.class, values);

   /* Discover all annotations on type which are meta-annotated @Constraint */

   Set<Annotation> constraints = AnnotationInspector.getAnnotations(type, Constraint.class);

   

   /* Load the annotation instance for @FacesValidator the annotation may declared on the type, */

   /* or, if the type has any stereotypes, on the stereotypes */

   FacesValidator validator = AnnotationInspector.getAnnotation(

                                                                type,

                                                                FacesValidator.class,

                                                                true,

                                                                beanManager);

   /* Create a provider, giving it a unique namespace */

   Synthetic.Provider provider = new Synthetic.Provider("com.acme");

   

   /* Get the a synthetic qualifier for the original annotation instance */

   Synthetic synthetic = provider.get(originalAnnotation);

   

   /* Later calls with the same original annotation instance will return the same instance */

   /* Alternatively, we can "get and forget" */

   

   Synthetic synthetic2 = provider.get();

When developing a framework that builds on CDI, you may need to obtain the BeanManager for the application, can't simply inject it as you are not working in an object managed by the container. The CDI specification allows lookup of java:comp/BeanManager in JNDI, however some environments don't support binding to this location (e.g. servlet containers such as Tomcat and Jetty) and some environments don't support JNDI (e.g. the Weld SE container). For this reason, most framework developers will prefer to avoid a direct JNDI lookup.

Often it is possible to pass the correct BeanManager to the object in which you require it, for example via a context object. For example, you might be able to place the BeanManager in the ServletContext, and retrieve it at a later date.

On some occasions however there is no suitable context to use, and in this case, you can take advantage of the abstraction over BeanManager lookup provided by Weld Extensions. To lookup up a BeanManager, you can extend the BeanManagerAware class, and call getBeanManager:

class WicketIntegration extends BeanManagerAware {


   public WicketManager getWicketManager() {

      Bean<?> bean = getBeanManager.getBean(Instance.class);

      ...   

   }

   

   ...


}

Occasionally you will be working in an existing class hierarchy, in which case you can use the static accessors on BeanManagerAccessor. For example:

class ResourceServlet extends HttpServlet {


   protected void doGet(HttpServletRequest req, HttpServletResponse resp) 

         throws ServletException, IOException {

      BeanManager beanManager = BeanManagerAccessor.getBeanManager();

      ...

   }

}

Weld Extensions provides a number of base classes which can be extended to create custom beans. Weld Extensions also provides bean builders which can be used to dynamically create beans using a fluent API.

The use of these classes is in general trivially understood with an understanding of basic programming patterns and the CDI specification, so no in depth explanation is provided here. The JavaDoc for each class and method provides more detail.

Properties are a convenient way of locating and working with JavaBean properties. They can be used with properties exposed via a getter/setter method, or directly via the field of a bean, providing a uniform interface that allows you all properties in the same way.

Property queries allow you to interrogate a class for properties which match certain criteria.

class Person {

   

   PersonName personName;

   

   Address address;

   

   void setPostcode(String postcode) {

      address.setPostcode(postcode);

   }

   

   String getPostcode() {

      return address.getPostcode();

   }

   

}

   Property<PersonName> personNameProperty = Properties.createProperty(Person.class.getField("personName");

   Property<String> postcodeProperty = Properties.createProperty(Person.class.getMethod("getPostcode"));

   PropertyQuery<?> query = PropertyQueries.createQuery(Foo.class);

   PropertyQuery<String> query = PropertyQueries.<String>createQuery(identityClass);

   public class Foo {  
      private String accountNumber;
      private @Scrambled String accountPassword;    
      private String accountName;    
   }

   PropertyQuery<String> query = PropertyQueries.<String>createQuery(Foo.class)
      .addCriteria(new AnnotatedPropertyCriteria(Scrambled.class));

public class Foo {
   public String getBar() {
      return "foobar";
   }
}

   PropertyQuery<String> query = PropertyQueries.<String>createQuery(Foo.class)
      .addCriteria(new NamedPropertyCriteria("bar"));

public class Foo {
   private Bar bar;
}

PropertyQuery<Bar> query = PropertyQueries.<Bar>createQuery(Foo.class)
      .addCriteria(new TypedPropertyCriteria(Bar.class));

public class WholeNumberPropertyCriteria implements PropertyCriteria {
   public boolean fieldMatches(Field f) {
      return f.getType() == Integer.class || f.getType() == Integer.TYPE.class ||
             f.getType() == Long.class || f.getType() == Long.TYPE.class ||
             f.getType() == BigInteger.class;
   }   

   boolean methodMatches(Method m) {
      return m.getReturnType() == Integer.class || m.getReturnType() == Integer.TYPE.class ||
             m.getReturnType() == Long.class || m.getReturnType() == Long.TYPE.class ||
             m.getReturnType() == BigInteger.class;
   }
}

   List<Property<String>> results = PropertyQueries.<String>createQuery(Foo.class)
     .addCriteria(TypedPropertyCriteria(String.class))
     .getResultList();

   Property<String> result = PropertyQueries.<String>createQuery(Foo.class)
      .addCriteria(NamedPropertyCriteria("bar"))
      .getFirstResult();

Unwrapping producer methods allow you to create injectable objects that have "self-managed"" lifecycles, and are particularly useful if you have need a bean whose lifecycle does not exactly match one of the lifecycle of one of the existing scopes. The lifecycle of the bean is are managed by the bean that defines the producer method, and changes to the unwrapped object are immediately visible to all clients.

You can declare a method to be an unwrapping producer method by annotating it @Unwraps. The return type of the managed producer must be proxyable (see Section 5.4.1 of the CDI specification, "Unproxyable bean types"). Every time a method is called on unwrapped object the invocation is forwarded to the result of calling the unwrapping producer method.

For example consider a permission manager (that manages the current permission), and a security manager (that checks the current permission level). Any changes to permission in the permission manager are immediately visible to the security manager.

@SessionScoped

class PermissionManager {

   

   Permission permission;

  

   void setPermission(Permission permission) {

      this.permission=permission;

   }

  

   @Unwraps @Current

   Permission getPermission() {

      return this.permission;

   }

}

class SecurityManager {

   

   @Inject @Current

   Permission permission;

  

   boolean checkAdminPermission() {

      return permission.getName().equals("admin");

   }


}

When permission.getName() is called, the unwrapped Permission forwards the invocation of getName() to the result of calling PermissionManager.getPermission().

For example you could raise the permission level before performing a sensitive operation, and then lower it again afterwards:

public class SomeSensitiveOperation {

   

   @Inject

   PermissionManager permissionManager;

  

   public void perform() {

      try {

         permissionManager.setPermission(Permissions.ADMIN);

         // Do some sensitive operation

      } finally {

         permissionManager.setPermission(Permissions.USER);

      }

   }


}

Unwrapping producer methods can have parameters injected, including InjectionPoint (which repreents) the calling method.

Suppose you have a situation where you want to provide a default implementation of a particular service and allow the user to override it as needed. Although this may sound like a job for an alternative, they have some restrictions that may make them undesirable in this situation. If you were to use an alternative it would require an entry in every beans.xml file in an application.

Developers consuming the extension will have to open up the any jar file which references the default bean, and edit the beans.xml file within, in order to override the service. This is where default beans come in.

Default beans allow you to create a default bean with a specified type and set of qualifiers. If no other bean is installed that has the same type and qualifiers, then the default bean will be installed.

Let's take a real world example - a module that allows you to evaluate EL (something that Weld Extensions provides!). If JSF is available we want to use the FunctionMapper provided by the JSF implementation to resolve functions, otherwise we just want to use a a default FunctionMapper implementation that does nothing. We can achieve this as follows:

@DefaultBean(type = FunctionMapper.class)

@Mapper

class FunctionMapperImpl extends FunctionMapper {


   @Override

   Method resolveFunction(String prefix, String localName) {

      return null;

   }


}

And in the JSF module:

class FunctionMapperProvider {

   

   @Produces

   @Mapper

   FunctionMapper produceFunctionMapper() {

      return FacesContext.getCurrentInstance().getELContext().getFunctionMapper();

   }

}

If FunctionMapperProvider is present then it will be used by default, otherwise the default FunctionMapperImpl is used.

A producer method or producer field may be defined to be a default producer by placing the @DefaultBean annotation on the producer. For example:

class CacheManager {
   
   @DefaultBean(Cache.class)
   Cache getCache() {
      ...
   }
     
}

Any producer methods or producer fields declared on a default managed bean are automatically registered as default producers, with Method.getGenericReturnType() or Field.getGenericType() determining the type of the default producer. The default producer type can be overridden by specifying @DefaultBean on the producer method or field.

Many common services and API's require the use of more than just one class. When exposing these services via CDI, it would be time consuming and error prone to force the end developer to provide producers for all the different classes required. Generic beans provides a solution, allowing a framework author to provide a set of related beans, one for each single configuration point defined by the end developer. The configuration points specifies the qualifiers which are inherited by all beans in the set.

To illustrate the use of generic beans, we'll use the following example. Imagine we are writing an extension to integrate our custom messaging solution "ACME Messaging" with CDI. The ACME Messaging API for sending messages consists of several interfaces:

We want to be able to create as many MessageQueue configurations's as they need, however we do not want to have to declare each producers and the associated plumbing for every queue. Generic beans are an ideal solution to this problem.

class MyMessageQueues {

   

   @Produces

   @ACMEQueue("defaultQueue")

   MessageSystemConfiguration defaultQueue = new MessageSystemConfiguration();

   

   @Produces @Durable @ConversationScoped

   @ACMEQueue("durableQueue")

   MessageSystemConfiguration producerDefaultQueue() {

      MessageSystemConfiguration config = new MessageSystemConfiguration();

      config.setDurable(true);

      return config;

   }

}

class MessageLogger {

  

   @Inject

   MessageDispatcher dispatcher;

  

   void logMessage(Payload payload) {

      /* Add metaddata to the message */

      Collection<Header> headers = new ArrayList<Header>();

      ... 

      Message message = new Message(headers, payload);

      dispatcher.send(message);

   }

  

}

class DurableMessageLogger {

  

   @Inject @Durable

   MessageDispatcher dispatcher;

   

   @Inject @Durable

   DispatcherPolicy policy;

   

         

   /* Tweak the dispatch policy to enable duplicate removal */

   @Inject

   void tweakPolicy(@Durable DispatcherPolicy policy) {

      policy.removeDuplicates();

   }

  

   void logMessage(Payload payload) {

      ...

   }

}

@Retention(RUNTIME)

@GenericType(MessageSystemConfiguration.class)

@interface ACMEQueue {


   String name();

   

}

@GenericConfiguration(ACMEQueue.class) @ApplyScope

class QueueManager {


   @Inject @Generic

   MessageSystemConfiguration systemConfig;

   

   @Inject

   ACMEQueue config;

   

   MessageQueueFactory factory;

   

   @PostConstruct

   void init() {

      factory = systemConfig.createMessageQueueFactory();

   }

   

   @Produces @ApplyScope

   public MessageQueue messageQueueProducer() {

      return factory.createMessageQueue(config.name());

   }

}

@Generic(ACMEQueue.class)

class MessageManager {


   @Inject @Generic

   MessageQueue queue;

   

   @Produces @ApplyScope

   MessageDispatcher messageDispatcherProducer() {

      return queue.createMessageDispatcher();

   }

   

   @Produces

   DispatcherPolicy getPolicy() {

      return queue.getDispatcherPolicy();

   }   

   

}

The service handler facility allow you to declare interfaces and abstract classes as automatically implemented beans. Any call to an abstract method on the interface or abstract class will be forwarded to the invocation handler for processing.

If you wish to convert some non-type-safe lookup to a type-safe lookup, then service handlers may be useful for you, as they allow the end user to map a lookup to a method using domain specific annotations.

We will work through using this facility, taking the example of a service which can execute JPA queries upon abstract method calls. First we define the annotation used to mark interfaces as automatically implemented beans. We meta-annotate it, defining the invocation handler to use:

@ServiceHandler(QueryHandler.class)

@Retention(RUNTIME)

@Target({TYPE})

@interface QueryService {}

We now define an annotation which provides the query to execute:

@Retention(RUNTIME)

@Target({METHOD})

@interface Query {


   String value();

   

}

And finally, the invocation handler, which simply takes the query, and executes it using JPA, returning the result:

class QueryHandler {

   

   @Inject EntityManager em;

  

   @AroundInvoke

   Object handle(InvocationContext ctx) {

      return em.createQuery(ctx.getMethod().getAnnotation(Query.class).value()).getResultList();

   }

}

Finally, we can define (any number of) interfaces which define our queries:

@QueryService

interface UserQuery {

   

   @Query("select u from User u");

   public List<User> getAllUsers();

}

Finally, we can inject the query interface, and call methods, automatically executing the JPA query.

class UserListManager {

   @Inject 

   UserQuery userQuery;

  

   List<User> users;

   

   @PostConstruct

   void create() {

      users=userQuery.getAllUsers();

   }


}