This is an implementation of OSGi CDI Integration Specification (hereafter referred to simply as OSGi CDI).
The build uses maven so it should look pretty familiar to most developers.
mvn clean install
The main artifact is the CDI Component Runtime (CCR) implementation. a.k.a. the extender bundle:
<dependency> <groupId>org.apache.aries.cdi</groupId> <artifactId>org.apache.aries.cdi.extender</artifactId> <version>${aries-cdi.version}</version> <scope>runtime</scope> </dependency>
However all the required dependencies are available using the Aries CDI BOM:
<dependency> <groupId>org.apache.aries.cdi</groupId> <artifactId>org.apache.aries.cdi.bom</artifactId> <version>${aries-cdi.version}</version> <type>pom</type> <scope>import</scope> </dependency>
In order to make the best use of OSGi CDI you should use tooling that supports it. Bnd provides OOTB support for OSGi CDI annotations and enables a painless configuration model.
OSGi CDI support in bnd comes with any tool that uses bnd versions 4.1.0+
:
Note there are several improvements for CDI handling in later versions of bnd, so please use the latest version for best experience.
Bean discovery in bnd is handled by the -cdiannotations
instruction. The default value for this is *
(which is functionally equivalent to *;discover=annotated_by_bean
described below.)
Discovery is controlled by applying the attribute discover
to glob pattern used for matching classes in the bundle by their fully qualified names (the default glob *
matches all classes.)
Available discover
options are:
none
- disable bean discoveryannotated
- uses the CDI definition of annotated discovery modeall
- discover all classes which could be beansannotated_by_bean
- defined by bnd, this is the effective default which means to look for classes annotated with org.osgi.service.cdi.annotations.Bean
or packages annotated with org.osgi.service.cdi.annotations.Beans
)In combination the glob and modes give the developer very concise control over discovery.
If you want to emulate the CDI default use:
-cdiannotations: *;discover=annotated
In bnd 4.3.0+
you can rely purely on the discovery mode calculated from existing beans.xml
files in your project. This grants even less configuration friction for existing projects migrating to OSGi CDI.
This repository provides an example for how to assemble an executable jar providing a complete runtime for you to just drop in your CDI bundles. It comes complete with logging, Gogo shell, Config Admin, Http Whiteboard support, and OSGi Promises.
Once you've completed a successfull build, you should be able to execute the command:
java -jar cdi-executable/target/executable.jar
and be presented with a gogo shell prompt ready for you to install a CDI bundle.
The goal of OSGi CDI was to remain as true to both technologies as possible. This proved possible due to the extensive feature set provided by each technology.
The main actors in the OSGi CDI architecture are:
CDI bundle - bundles which contain CDI beans and opted-in to OSGi CDI (best achieved with supporting build tooling.)
CDI container - an instance of the CDI machinery hosting all beans inside a bundle and managing their instantiation.
CDI Component Runtime (CCR) - is what Aries CDI implements using the extender pattern. It awaits CDI bundles creating a private CDI container for each one.
OSGi CDI Components (hereafter referred to simple as components) - A set of closely related CDI beans having a common OSGi lifecycle. A CDI bundle has 1 to N components. Again, all beans within the same component have a common OSGi lifecycle within the CDI bundle. The collective dependencies declared by all bean making up a component are treated as a single set. As such any single unsatisfied dependency of the component will prevent the entire component from activating, or upon removal, will cause the component to deactivate.
OSGi CDI Portable Extension (hereafter referred to simply as portable extensions) - bundles which contain portable extensions and opted-in to providing those extensions in a OSGi CDI compatible way.
Service Registry - The OSGi service registry is the central actor by which all inter bundle service activity is managed. As such, CDI bundles interact with other bundles via the service registry as well.
The nice thing is you can mix and match through the lingua franca of services. A bundle that is internally implemented with DS can talk to a bundle that is internally implemented with CDI (or Blueprint, etc...) Neil Bartlett - Twitter
Configuration Admin - OSGi CDI is well integrated with Configuration Admin the way that Declarative Services (DS) is. As such, all components in CDI bundles are configurable via configuration admin.
When a CDI bundle is identified by CCR several steps are taken before any bean is instantiated:
javax.enterprise.inject.spi.Extension
services must be located. The bundle's CDI container will remain inactive until all portable extension services are located. Conversely, for a bundle with an active CDI container, if an identified extension goes away the CDI container is torn down.ApplicationScoped
, Dependent
, RequestScoped
, SessionScoped
, ConversationScoped
, any custom scopes, etc.; all of these make up the container component.org.osgi.service.cdi.annotations.ComponentScoped
are part of the container component.@SingleComponent
are roots of a single component.@ComponentScoped
are also part of this single component.@FactoryComponent
are roots of a factory component.@ComponentScoped
are also part of this factory component.javax.enterprise.inject.spi.BeanManager
of the CDI container is published as a service with the service property osgi.cdi.container.id
. (always, even if the container component is empty.)ServiceFactory
like DS component services)ServiceFactory
). Service instances are created whenever the getService
method of the factory is called, and destroyed when the ungetService
is called. Note: The service registry is the one tracking if a bundle has already gotten factory service instances.PrototypeServiceFactory
). Service instances are created whenever the getService
method of the factory is called, and destroyed when the ungetService
is called.@Initialized(ComponentScoped.class)
@BeforeDestroy(ComponentScoped.class)
@Destroyed(ComponentScoped.class)
ServiceFactory
like DS component services)ServiceFactory
). Service instances are created whenever the getService
method of the factory is called, and destroyed when the ungetService
is called. Note: The service registry is the one tracking if a bundle has already gotten factory service instances.PrototypeServiceFactory
). Service instances are created whenever the getService
method of the factory is called, and destroyed when the ungetService
is called.@Initialized(ComponentScoped.class)
@BeforeDestroy(ComponentScoped.class)
@Destroyed(ComponentScoped.class)
Time to move onto the examples.