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 Extension
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 jakarta.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/jakarta.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.
Note
|
Weld SE allows to define so called synthetic container lifecycle event observers. Such observers do not belong to a particular extension. See also org.jboss.weld.environment.se.ContainerLifecycleObserver and Weld.addContainerLifecycleObserver() .
|
Container lifecycle events
During the initialization process, the container fires a series of events, including:
-
BeforeBeanDiscovery
-
ProcessAnnotatedType
andProcessSyntheticAnnotatedType
-
AfterTypeDiscovery
-
ProcessInjectionTarget
andProcessProducer
-
ProcessInjectionPoint
-
ProcessBeanAttributes
-
ProcessBean
,ProcessManagedBean
,ProcessSessionBean
,ProcessProducerMethod
,ProcessProducerField
andProcessSyntheticBean
-
ProcessObserverMethod
andProcessSyntheticObserverMethod
-
AfterBeanDiscovery
-
AfterDeploymentValidation
Extensions may observe these events:
import jakarta.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 jakarta.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();
}
}
Note
|
The @WithAnnotations annotation causes the container to deliver the
ProcessAnnotatedType events only for the types which contain the
specified annotation.
|
Container lifecycle event observer methods 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.
Configurators
CDI 2.0 introduced the Configurators API - a new way to easily configure some parts of the SPI during container lifecycle event notification.
E.g. to add a qualifier to a bean, an extension can observe ProcessBeanAttributes
, then obtain a configurator instance through ProcessBeanAttributes.configureBeanAttributes()
and finally use BeanAttributesConfigurator.addQualifier(Annotation)
.
No need to wrap/delegate to the original BeanAttributes
.
See also chapter Configurators interfaces of the CDI specification.
Weld-enriched container lifecycle events
Apart from CDI-defined lifecycle events, Weld also offers enriched observable container lifecycle event - WeldAfterBeanDiscovery
.
Compared to jakarta.enterprise.inject.spi.AfterBeanDiscovery
, it adds one extra method - addInterceptor()
.
This method works in the same way as the aforementioned Configurators; you get back an InterceptorConfigurator
instance, where you can set all the desired data.
The interceptor is created automatically, once the methods exits and the configurator instance is not reusable.
But if you need to create several interceptors, you can simply request several configurator instances.
Here is a code snippet to demonstrate the idea:
public void afterBeanDiscovery(@Observes WeldAfterBeanDiscovery event) {
// type level interceptor
event.addInterceptor().intercept(InterceptionType.AROUND_INVOKE, (invocationContext) -> {
try {
getAnswerToLifeTheUniverseAndEverything();
return invocationContext.proceed();
} catch (Exception e) {
e.printStackTrace();
}
return null;
}).priority(2500).addBinding(MyTypeBinding.MyTypeBindingLiteral.INSTANCE);
}
The sample presents a simple interception use case where you supply java.util.function.Function
as the interceptor body method.
For more complex cases, you may also choose to use interceptWithMetadata
method which accepts java.util.function.BiFunction
instead.
The second parameter of the BiFunction
emulates @Inject @Intercepted Bean<?>
allowing access to metadata.
The BeanManager
object
The nerve center for extending CDI is the BeanManager
object.
The BeanManager
interface provides operations useful for portable extensions, e.g. lets us obtain beans, interceptors, decorators, observers and contexts programmatically.
Note that some of the methods may not be called before the AfterBeanDiscovery
event is fired, e.g. BeanManager.getBeans()
.
Furthermore, the BeanManager.getReference()
and BeanManager.getInjectableReference()
methods may not be called before the AfterDeploymentValidation
event is fired.
See also the javadoc for more details.
As already stated in Container lifecycle events, any container lifecycle event observer method can obtain an injected BeanManager
reference:
void afterBeanDiscovery(@Observes AfterBeanDiscovery event, BeanManager beanManager) { ... }
Furthermore, 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
.
The CDI
class
Application components which cannot obtain a BeanManager
reference via
injection nor JNDI lookup can get the reference from the
jakarta.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
Obtaining a contextual instance by programmatic lookup
.
CDI.select(Foo.class).get()
The InjectionTarget
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.
Note
|
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 instantiate the object itself, and so only method and field injection will be supported. |
import jakarta.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
The Bean
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 BeanAttributes
interface exposes all the interesting things we
discussed in
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(Object.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.
Registering a Bean
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 jakarta.enterprise.inject.spi.Extension;
import jakarta.enterprise.event.Observes;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import jakarta.enterprise.inject.spi.InjectionPoint;
...
public class SecurityManagerExtension implements Extension {
void afterBeanDiscovery(@Observes AfterBeanDiscovery event, BeanManager bm) {
event.addBean()
/* read annotations of the class and create an InjectionTarget used to instantiate the class and inject dependencies */
.read(bm.createAnnotatedType(SecurityManager.class))
.beanClass(SecurityManager.class)
.scope(ApplicationScoped.class)
.name("securityManager");
}
}
But a portable extension can also mess with beans that are discovered automatically by the container.
Configuring an AnnotatedType
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 configure the
AnnotatedType
object and override the value()
of the @Named
annotation.
import java.lang.reflect.Type;
import jakarta.enterprise.inject.spi.Extension;
import java.lang.annotation.Annotation;
...
public class QualifiedNameExtension implements Extension {
<X> void processAnnotatedType(@Observes ProcessAnnotatedType<X> event) {
/* wrap this to override the annotations of the class */
final AnnotatedType<X> at = event.getAnnotatedType();
/* Only wrap AnnotatedTypes for classes with @Named packages */
Package pkg = at.getJavaClass().getPackage();
if (pkg == null || !pkg.isAnnotationPresent(Named.class) ) {
return;
}
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 = pkg.getAnnotation(Named.class).value()
+ '_' + unqualifiedName;
event.configureAnnotatedType().remove((a) -> a.annotationType().equals(Named.class)).add(NamedLiteral.of(qualifiedName));
}
}
Here’s a second example, which adds the @Alternative
annotation to any
class which implements a certain Service
interface.
import jakarta.enterprise.inject.spi.Extension;
import jakarta.enterprise.inject.Alternative;
...
class ServiceAlternativeExtension implements Extension {
<T extends Service> void processAnnotatedType(@Observes ProcessAnnotatedType<T> event) {
event.configureAnnotatedType().add(Alternative.Literal.INSTANCE);
}
}
The AnnotatedType
is not the only thing that can be configured/wrapped by an
extension.
Overriding attributes of a bean
Configuring 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 BeanAttributesConfigurator<T> configureBeanAttributes();
public void setBeanAttributes(BeanAttributes<T> beanAttributes);
public void addDefinitionError(Throwable t);
public void veto();
}
The BeanManager
also provides two utility methods for creating the
BeanAttributes
object from scratch:
public <T> BeanAttributes<T> createBeanAttributes(AnnotatedType<T> type);
public BeanAttributes<?> createBeanAttributes(AnnotatedMember<?> type);
Wrapping an InjectionTarget
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 jakarta.enterprise.event.Observes;
import jakarta.enterprise.inject.spi.Extension;
import jakarta.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);
}
}
Overriding InjectionPoint
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
jakarta.enterprise.inject.spi.ProcessInjectionPoint
public interface ProcessInjectionPoint<T, X> {
public InjectionPoint getInjectionPoint();
public InjectionPointConfigurator configureInjectionPoint();
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.
Manipulating interceptors, decorators and alternatives enabled for an application
An event of type jakarta.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
interfaces
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 jakarta.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 or the Command context example.
Build Compatible extensions
Since CDI 4, users can leverage Build Compatible extensions as an alternative to Portable extensions. Both extension models are targeting the same set of use cases and can users can choose either model or even combine both.
As name suggests, Build Compatible extensions are tailored to run in more constrained environments and as such have to sacrifice some functionality and user-friendliness in order to retain portability across very different environments.
For example, Build Compatible extension cannot be injected as a bean at runtime and therefore cannot be used to carry information gathered during CDI bootstrap into later stages of your application.
Another notable difference is that unlike Portable extensions and their reflection-heavy model (for instance AnnotatedType
), Build Compatible extensions use an entirely different language model, that has a reflection-free API.
Weld supports Build Compatible extensions and their language model but does so through usage of reflection and executes these extensions by binding their lifecycle calls to a specialized Portable extension. Since Weld is a CDI Full implementation, it is recommended to keep using Portable extensions over Build Compatible extensions.
The support works out of the box for Weld SE and Weld Servlet but for any other environments and custom integrations, it is up to integrators to make sure the support is included.
Take a look at org.jboss.weld.lite.extension.translator.LiteExtensionTranslator
and org.jboss.weld.lite.extension.translator.BuildCompatibleExtensionLoader
in case you want to learn more about this topic.
Users can also choose to provide the same functionality in both variants - a Portable extension and a Build Compatible extension.
It is then possible to annotate the Build Compatible variant with @jakarta.enterprise.inject.build.compatible.spi.SkipIfPortableExtensionPresent
which will automatically disable the Build Compatible variant in favor of Portable extension variant in CDI Full environments.
Build Compatible extension have an extensive Javadoc describing how to use them; a good starting point is the jakarta.enterprise.inject.build.compatible.spi.BuildCompatibleExtension
interface.
Further documentation is available in dedicated CDI specification chapter.