The first step in creating a portable extension is to write a class that implements Extension. This marker interface does not define any methods, but it's needed to satisfy the requirements of Java SE's service provider architecture.

 import javax.enterprise.inject.spi.Extension;


class MyExtension implements Extension { ... }

Next, we need to register our extension as a service provider by creating a file named META-INF/services/javax.enterprise.inject.spi.Extension, which contains the name of our extension class:

org.mydomain.extension.MyExtension

An extension is not a bean, exactly, since it is instantiated by the container during the initialization process, before any beans or contexts exist. However, it can be injected into other beans once the initialization process is complete.

@Inject 

MyBean(MyExtension myExtension) {

   myExtension.doSomething();

}

And, like beans, extensions can have observer methods. Usually, the observer methods observe container lifecycle events.

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

Extensions may observe these events:

import javax.enterprise.inject.spi.Extension;


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:

import javax.enterprise.inject.spi.Extension;


class MyExtension implements Extension {

      

   <T> void processAnnotatedType(@Observes @WithAnnotations({Ignore.class}) ProcessAnnotatedType<T> pat) {

      /* tell the container to ignore the type if it is annotated @Ignore */

      if ( pat.getAnnotatedType().isAnnotationPresent(Ignore.class) ) pat.veto();   

   } 

   

}

The observer method may inject a BeanManager

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

An extension observer method is not allowed to inject any other 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 boolean areQualifiersEquivalent(Annotation qualifier1, Annotation qualifier2);

   public boolean areInterceptorBindingsEquivalent(Annotation interceptorBinding1, Annotation interceptorBinding2);

   public int getQualifierHashCode(Annotation qualifier);

   public int getInterceptorBindingHashCode(Annotation interceptorBinding);

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

   public <T> InjectionTargetFactory<T> getInjectionTargetFactory(AnnotatedType<T> annotatedType);

   public <X> ProducerFactory<X> getProducerFactory(AnnotatedField<? super X> field, Bean<X> declaringBean);

   public <X> ProducerFactory<X> getProducerFactory(AnnotatedMethod<? super X> method, Bean<X> declaringBean);

   public <T> BeanAttributes<T> createBeanAttributes(AnnotatedType<T> type);

   public BeanAttributes<?> createBeanAttributes(AnnotatedMember<?> type);

   public <T> Bean<T> createBean(BeanAttributes<T> attributes, Class<T> beanClass,

   public <T, X> Bean<T> createBean(BeanAttributes<T> attributes, Class<X> beanClass, ProducerFactory<X> producerFactory);

   public InjectionPoint createInjectionPoint(AnnotatedField<?> field);

   public InjectionPoint createInjectionPoint(AnnotatedParameter<?> parameter);

   public <T extends Extension> T getExtension(Class<T> extensionClass);

}

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

@Inject BeanManager beanManager;

Alternatively, a BeanManager reference may be obtained from CDI via a static method call.

CDI.current().getBeanManager()

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.

Application components which cannot obtain a BeanManager reference via injection nor JNDI lookup can get the reference from the javax.enterprise.inject.spi.CDI class via a static method call:

BeanManager manager = CDI.current().getBeanManager();

The CDI class can be used directly to programmatically lookup CDI beans as described in Section 4.10, “Obtaining a contextual instance by programmatic lookup”

CDI.select(Foo.class).get()

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.

import javax.enterprise.inject.spi.CDI;


...


//get the BeanManager

BeanManager beanManager = CDI.current().getBeanManager();


//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

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.

The BeanAttributes interface exposes all the interesting things we discussed in Section 2.1, “The anatomy of a bean”.

public interface BeanAttributes<T> {

   public Set<Type> getTypes();

   public Set<Annotation> getQualifiers();

   public Class<? extends Annotation> getScope();

   public String getName();

   public Set<Class<? extends Annotation>> getStereotypes();

   public boolean isAlternative();

}

The Bean interface extends the BeanAttributes interface and defines everything the container needs to manage instances of a certain bean.

public interface Bean<T> extends Contextual<T>, BeanAttributes<T> {

   public Class<?> getBeanClass();

   public Set<InjectionPoint> getInjectionPoints();

   public boolean isNullable();

}

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.

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.

import javax.enterprise.inject.spi.Extension;

import javax.enterprise.event.Observes;

import java.lang.annotation.Annotation;

import java.lang.reflect.Type;

import javax.enterprise.inject.spi.InjectionPoint;

...


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


        abd.addBean( new Bean<SecurityManager>() {


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

                qualifiers.add( new AnnotationLiteral<Default>() {} );

                qualifiers.add( new AnnotationLiteral<Any>() {} );

                return qualifiers;

            }


            @Override

            public Class<? extends Annotation> getScope() {

                return ApplicationScoped.class;

            }


            @Override

            public Set<Class<? extends Annotation>> getStereotypes() {

                return Collections.emptySet();

            }


            @Override

            public Set<Type> getTypes() {

                Set<Type> types = new HashSet<Type>();

                types.add(SecurityManager.class);

                types.add(Object.class);

                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.

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.

import java.lang.reflect.Type;

import javax.enterprise.inject.spi.Extension;

import java.lang.annotation.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();


        /* Only wrap AnnotatedTypes for classes with @Named packages */

        Package pkg = at.getJavaClass().getPackage();

        if ( !pkg.isAnnotationPresent(Named.class) ) {

            return;

        }


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

            

            class NamedLiteral extends AnnotationLiteral<Named>

            implements Named {

                @Override

                public String value() {

                    Package pkg = at.getJavaClass().getPackage();


                    String unqualifiedName = "";

                    if (at.isAnnotationPresent(Named.class)) {

                        unqualifiedName = at.getAnnotation(Named.class).value();

                    }


                    if (unqualifiedName.isEmpty()) {

                        unqualifiedName = Introspector.decapitalize(at.getJavaClass().getSimpleName());

                    }


                    final String qualifiedName;

                    if ( pkg.isAnnotationPresent(Named.class) ) {

                        qualifiedName = pkg.getAnnotation(Named.class).value()

                            + '.' + unqualifiedName;

                    }

                    else {

                        qualifiedName = unqualifiedName;

                    }


                    return qualifiedName;

                }

            }

            

            private final NamedLiteral namedLiteral = new NamedLiteral();


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

                    return (T) namedLiteral;

                }

                else {

                    return at.getAnnotation(annType);

                }

            }


            @Override

            public Set<Annotation> getAnnotations() {

                Set<Annotation> original = at.getAnnotations();

                Set<Annotation> annotations = new HashSet<Annotation>();


                boolean hasNamed = false;


                for (Annotation annotation : original) {

                    if (annotation.annotationType().equals(Named.class)) {

                        annotations.add(getAnnotation(Named.class));

                        hasNamed = true;

                    }

                    else {

                        annotations.add(annotation);

                    }

                }


                if (!hasNamed) {

                    Package pkg = at.getJavaClass().getPackage();

                    if (pkg.isAnnotationPresent(Named.class)) {

                        annotations.add(getAnnotation(Named.class));

                    }

                }


                return annotations;

            }


            @Override

            public Type getBaseType() {

                return at.getBaseType();

            }


            @Override

            public Set<Type> getTypeClosure() {

                return at.getTypeClosure();

            }


            @Override

            public boolean isAnnotationPresent(Class<? extends Annotation> annType) {

                if (Named.class.equals(annType)) {

                    return true;

                }

                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.

import javax.enterprise.inject.spi.Extension;

import java.lang.annotation.Annotation;

...


class ServiceAlternativeExtension implements Extension {

      

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

   

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


      /* if the class implements Service, make it an @Alternative */

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


         class AlternativeLiteral extends AnnotationLiteral<Alternative> implements Alternative {}

         

         private final AlternativeLiteral alternativeLiteral = new AlternativeLiteral();


         @Override

         public <X extends Annotation> X getAnnotation(final Class<X> annType) {

            return (X) (annType.equals(Alternative.class) ?  alternativeLiteral : type.getAnnotation(annType));

         }


         @Override

         public Set<Annotation> getAnnotations() {

            Set<Annotation> annotations = new HashSet<Annotation>(type.getAnnotations());

            annotations.add(alternativeLiteral);

            return annotations;

         }

         

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

Wrapping an AnnotatedType is a low-level approach to overriding CDI metadata by adding, removing or replacing annotations. Since version 1.1, CDI provides a higher-level facility for overriding attributes of beans discovered by the CDI container.

public interface BeanAttributes<T> {


   public Set<Type> getTypes();


   public Set<Annotation> getQualifiers();


   public Class<? extends Annotation> getScope();


   public String getName();


   public Set<Class<? extends Annotation>> getStereotypes();


   public boolean isAlternative();


}

The BeanAttributes interface exposes attributes of a bean. The container fires a ProcessBeanAttributes event for each enabled bean, interceptor and decorator before this object is registered. Similarly to the ProcessAnnotatedType, this event allows an extension to modify attributes of a bean or to veto the bean entirely.

public interface ProcessBeanAttributes<T> {


    public Annotated getAnnotated();


    public BeanAttributes<T> getBeanAttributes();


    public void setBeanAttributes(BeanAttributes<T> beanAttributes);


    public void addDefinitionError(Throwable t);


    public void veto();


}

The BeanManager provides two utility methods for creating the BeanAttributes object from scratch:

public <T> BeanAttributes<T> createBeanAttributes(AnnotatedType<T> type);


public BeanAttributes<?> createBeanAttributes(AnnotatedMember<?> type);

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.

import javax.enterprise.event.Observes;

import javax.enterprise.inject.spi.Extension;

import javax.enterprise.inject.spi.InjectionPoint;


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

        

        /* read the properties file */

        String propsFileName = at.getJavaClass().getSimpleName() + ".properties";

        InputStream stream = at.getJavaClass().getResourceAsStream(propsFileName);

        if (stream!=null) {

            

            try {

                Properties props = new Properties();

                props.load(stream);

                for (Map.Entry<Object, Object> property : props.entrySet()) {

                    String fieldName = property.getKey().toString();

                    Object value = property.getValue();

                    try {

                        Field field = at.getJavaClass().getDeclaredField(fieldName);

                        field.setAccessible(true);

                        if ( field.getType().isAssignableFrom( value.getClass() ) ) {

                            configuredValues.put(field, value);

                        }

                        else {

                            /* TODO: do type conversion automatically */

                            pit.addDefinitionError( new InjectionException(

                                   "field is not of type String: " + field ) );

                        }

                    }

                    catch (NoSuchFieldException nsfe) {

                        pit.addDefinitionError(nsfe);

                    }

                    finally {

                        stream.close();

                    }

                }

            }

            catch (IOException ioe) {

                pit.addDefinitionError(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);

        

    }

    

}

CDI provides a way to override the metadata of an InjectionPoint. This works similarly to how metadata of a bean may be overridden using BeanAttributes.

For every injection point of each component supporting injection Weld fires an event of type javax.enterprise.inject.spi.ProcessInjectionPoint

public interface ProcessInjectionPoint<T, X> {

    public InjectionPoint getInjectionPoint();

    public void setInjectionPoint(InjectionPoint injectionPoint);

    public void addDefinitionError(Throwable t);

}

An extension may either completely override the injection point metadata or alter it by wrapping the InjectionPoint object obtained from ProcessInjectionPoint.getInjectionPoint()

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.

An event of type javax.enterprise.inject.spi.AfterTypeDiscovery is fired when the container has fully completed the type discovery process and before it begins the bean discovery process.

public interface AfterTypeDiscovery {

    public List<Class<?>> getAlternatives();

    public List<Class<?>> getInterceptors();

    public List<Class<?>> getDecorators();

    public void addAnnotatedType(AnnotatedType<?> type, String id);

}

This event exposes a list of enabled alternatives, interceptors and decorators. Extensions may manipulate these collections directly to add, remove or change the order of the enabled records.

In addition, an AnnotatedType can be added to the types which will be scanned during bean discovery, with an identifier, which allows multiple annotated types, based on the same underlying type, to be defined.

The Context and AlterableContext interface support 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.

import javax.enterprise.context.spi.Context;


public interface AlterableContext extends Context {

    public void destroy(Contextual<?> contextual);

}

AlterableContext was introduced in CDI 1.1. The destroy method allows an application to remove instances of contextual objects from a context.

For more information on implementing a custom context see this blog post.