Portable extensions
CDI is intended to be a foundation for frameworks, extensions and integration with other technologies. Therefore,
CDI exposes a set of SPIs for the use of developers of portable extensions to CDI. For example, the following
kinds of extensions were envisaged by the designers of CDI:
integration with Business Process Management engines,
integration with third-party frameworks such as Spring, Seam, GWT or Wicket, and
new technology based upon the CDI programming model.
More formally, according to the spec:
A portable extension may integrate with the container by:
Providing its own beans, interceptors and decorators to the container
Injecting dependencies into its own objects using the dependency injection service
Providing a context implementation for a custom scope
Augmenting or overriding the annotation-based metadata with metadata from some other source
Creating an <literal>Extension</literal>
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.
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.
Container lifecycle events
During the initialization process, the container fires a series of events, including:
BeforeBeanDiscovery
ProcessAnnotatedType
ProcessInjectionTarget and ProcessProducer
ProcessBean and ProcessObserverMethod
AfterBeanDiscovery
AfterDeploymentValidation
Extensions may observe these events:
void processAnnotatedType(@Observes ProcessAnnotatedType 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:
void processAnnotatedType(@Observes ProcessAnnotatedType pat) {
//tell the container to ignore the type if it is annotated @Ignore
if ( pat.getAnnotatedType().isAnnotionPresent(Ignore.class) ) pat.veto();
}
}]]>
The observer method may inject a BeanManager
void processAnnotatedType(@Observes ProcessAnnotatedType pat, BeanManager beanManager) { ... }]]>
The <literal>BeanManager</literal> object
The nerve center for extending CDI is the BeanManager object. The
BeanManager interface lets us obtain beans, interceptors, decorators,
observers and contexts programmatically.
bean, Type beanType, CreationalContext ctx);
public Object getInjectableReference(InjectionPoint ij, CreationalContext ctx);
public CreationalContext createCreationalContext(Contextual contextual);
public Set> getBeans(Type beanType, Annotation... qualifiers);
public Set> getBeans(String name);
public Bean getPassivationCapableBean(String id);
public Bean resolve(Set> beans);
public void validate(InjectionPoint injectionPoint);
public void fireEvent(Object event, Annotation... qualifiers);
public Set> resolveObserverMethods(T event, Annotation... qualifiers);
public List> resolveDecorators(Set types, Annotation... qualifiers);
public List> resolveInterceptors(InterceptionType type, Annotation... interceptorBindings);
public boolean isScope(Class annotationType);
public boolean isNormalScope(Class annotationType);
public boolean isPassivatingScope(Class annotationType);
public boolean isQualifier(Class annotationType);
public boolean isInterceptorBinding(Class annotationType);
public boolean isStereotype(Class annotationType);
public Set getInterceptorBindingDefinition(Class bindingType);
public Set getStereotypeDefinition(Class stereotype);
public Context getContext(Class scopeType);
public ELResolver getELResolver();
public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
public AnnotatedType createAnnotatedType(Class type);
public InjectionTarget createInjectionTarget(AnnotatedType type);
}]]>
Any bean or other Java EE component which supports injection can obtain an instance of BeanManager
via injection:
@Inject BeanManager beanManager;
Java EE components may obtain an instance of BeanManager from JNDI by looking up the name
java:comp/BeanManager. Any operation of BeanManager may be called at any
time during the execution of the application.
Let's study some of the interfaces exposed by the BeanManager.
The <literal>InjectionTarget</literal> interface
The first thing that a framework developer is going to look for in the portable extension SPI is a way to
inject CDI beans into objects which are not under the control of CDI. The InjectionTarget
interface makes this very easy.
We recommend that frameworks let CDI take over the job of actually instantiating the framework-controlled
objects. That way, the framework-controlled objects can take advantage of constructor injection. However,
if the framework requires use of a constructor with a special signature, the framework will need to
instatiate the object itself, and so only method and field injection will be supported.
type = beanManager.createAnnotatedType(SomeFrameworkComponent.class);
//The extension uses an InjectionTarget to delegate instantiation, dependency injection
//and lifecycle callbacks to the CDI container
InjectionTarget 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
]]>
The <literal>Bean</literal> interface
Instances of the interface Bean represent beans. There is an instance of
Bean registered with the BeanManager object for every bean in the
application. There are even Bean objects representing interceptors, decorators and
producer methods.
The Bean interface exposes all the interesting things we dicussed in
.
extends Contextual {
public Set getTypes();
public Set getQualifiers();
public Class getScope();
public String getName();
public Set> getStereotypes();
public Class getBeanClass();
public boolean isAlternative();
public boolean isNullable();
public Set getInjectionPoints();
}]]>
There's an easy way to find out what beans exist in the application:
> allBeans = beanManager.getBeans(Obect.class, new AnnotationLiteral() {});]]>
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.
Registering a <literal>Bean</literal>
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.
at = bm.createAnnotatedType(SecurityManager.class);
//use this to instantiate the class and inject dependencies
final InjectionTarget it = bm.createInjectionTarget(at);
abd.addBean( new Bean() {
@Override
public Class getBeanClass() {
return SecurityManager.class;
}
@Override
public Set getInjectionPoints() {
return it.getInjectionPoints();
}
@Override
public String getName() {
return "securityManager";
}
@Override
public Set getQualifiers() {
Set qualifiers = new HashSet();
qualifiers.add( new AnnotationLiteral() {} );
qualifiers.add( new AnnotationLiteral() {} );
return qualifiers;
}
@Override
public Class getScope() {
return SessionScoped.class;
}
@Override
public Set> getStereotypes() {
return Collections.emptySet();
}
@Override
public Set getTypes() {
Set types = new HashSet();
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 ctx) {
SecurityManager instance = it.produce(ctx);
it.inject(instance, ctx);
it.postConstruct(instance);
return instance;
}
@Override
public void destroy(SecurityManager instance,
CreationalContext 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.
Wrapping an <literal>AnnotatedType</literal>
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.
void processAnnotatedType(@Observes ProcessAnnotatedType pat) {
//wrap this to override the annotations of the class
final AnnotatedType at = pat.getAnnotatedType();
AnnotatedType wrapped = new AnnotatedType() {
@Override
public Set> getConstructors() {
return at.getConstructors();
}
@Override
public Set> getFields() {
return at.getFields();
}
@Override
public Class getJavaClass() {
return at.getJavaClass();
}
@Override
public Set> getMethods() {
return at.getMethods();
}
@Override
public T getAnnotation(final Class annType) {
if ( Named.class.equals(annType) ) {
class NamedLiteral
extends AnnotationLiteral
implements Named {
@Override
public String value() {
Package pkg = at.getClass().getPackage();
String unqualifiedName = at.getAnnotation(Named.class).value();
final String qualifiedName;
if ( pkg.isAnnotationPresent(Named.class) ) {
qualifiedName = pkg.getAnnotation(Named.class).value()
+ '.' + unqualifiedName;
}
else {
qualifiedName = unqualifiedName;
}
return qualifiedName;
}
}
return (T) new NamedLiteral();
}
else {
return at.getAnnotation(annType);
}
}
@Override
public Set getAnnotations() {
return at.getAnnotations();
}
@Override
public Type getBaseType() {
return at.getBaseType();
}
@Override
public Set getTypeClosure() {
return at.getTypeClosure();
}
@Override
public boolean isAnnotationPresent(Class annType) {
return at.isAnnotationPresent(annType);
}
};
pat.setAnnotatedType(wrapped);
}
}]]>
Here's a second example, which adds the @Alternative annotation to any
class which implements a certain Service interface.
void processAnnotatedType(@Observes ProcessAnnotatedType pat) {
final AnnotatedType type = pat.getAnnotatedType();
if ( Service.class.isAssignableFrom( type.getJavaClass() ) ) {
//if the class implements Service, make it an @Alternative
AnnotatedType wrapped = new AnnotatedType() {
@Override
public boolean isAnnotationPresent(Class 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 <literal>InjectionTarget</literal>
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.
void processInjectionTarget(@Observes ProcessInjectionTarget pit) {
//wrap this to intercept the component lifecycle
final InjectionTarget it = pit.getInjectionTarget();
final Map configuredValues = new HashMap();
//use this to read annotations of the class and its members
AnnotatedType at = pit.getAnnotatedType();
//read the properties file
String propsFileName = at.getClass().getSimpleName() + ".properties";
InputStream stream = at.getJavaClass().getResourceAsStream(propsFileName);
if (stream!=null) {
try {
Properties props = new Properties();
props.load(stream);
for (Map.Entry property : props.entrySet()) {
String fieldName = property.getKey().toString();
Object value = property.getValue();
try {
Field field = at.getJavaClass().getField(fieldName);
field.setAccessible(true);
if ( field.getType().isAssignableFrom( value.getClass() ) ) {
configuredValues.put(field, value);
}
else {
//TODO: do type conversion automatically
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 wrapped = new InjectionTarget() {
@Override
public void inject(X instance, CreationalContext ctx) {
it.inject(instance, ctx);
//set the values onto the new instance of the component
for (Map.Entry 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 getInjectionPoints() {
return it.getInjectionPoints();
}
@Override
public X produce(CreationalContext ctx) {
return it.produce(ctx);
}
};
pit.setInjectionTarget(wrapped);
}
}]]>
There's a lot more to the portable extension SPI than what we've discussed here. Check out the CDI spec or
Javadoc for more information. For now, we'll just mention one more extension point.
The <literal>Context</literal> interface
The Context interface supports addition of new scopes to CDI, or extension of the built-in
scopes to new environments.
getScope();
public T get(Contextual contextual, CreationalContext creationalContext);
public T get(Contextual 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.