14.2. Enabling Pax CDI

Overview

Pax CDI is not enabled by default in the Karaf container in JBoss Fuse, so you must enable it explicitly. There are two aspects of enabling Pax CDI in the Karaf container: first, installing the requisite Karaf features in the container; second, enabling CDI for a particular bundle, by adding the Require-Capability header to the bundle's manifest (turning the bundle into a bean bundle).

Pax CDI features

To make Pax CDI functionality available in the Karaf container, install the requisite Karaf features into your container. JBoss Fuse provides the following Karaf features for Pax CDI:
pax-cdi
Deploys the core components of Pax CDI. This feature must be combined with the pax-cdi-weld CDI implementation.
pax-cdi-weld
Deploys the JBoss Weld CDI implementation (which is the only CDI implementation supported on JBoss Fuse)
pax-cdi-web
Adds support for deploying a CDI application as a Web application (that is, deploying the CDI application into the Pax Web Jetty container). This enables support for the CDI features associated with servlet deployment, such as session-scoped beans, request-scoped beans, injection into servlets, and so on. This feature must be combined with the pax-cdi-web-weld feature (CDI implementation).
pax-cdi-web-weld
Deploys the JBoss Weld CDI implementation for Web applications.

Requirements and capabilities

CDI requires you to organize your Java code in a very specific way, so it cannot be enabled arbitrarily for any bundle. It only makes sense to enable CDI for each bundle that needs it, not for the entire container. Hence, it is necessary to use an OSGi extension mechanism that switches on the CDI capability on a bundle-by-bundle basis. The relevant OSGi mechanism is known as the requirements and capabilities mechanism.
The CDI capability is provided by the relevant Pax CDI packages (installed as Karaf features); and the CDI requirement is specified for each bundle by adding a Require-Capability bundle header to the bundle's manifest file. For example, to enable the base Pax CDI functionality, you would add the following Require-Capability header to the bundle's manifest file:
Require-Capability : osgi.extender; filter:="(osgi.extender=pax.cdi)"
A bundle that includes the preceding Require-Capability bundle header effectively becomes a bean bundle (a CDI enabled bundle).

How to enable Pax CDI in Apache Karaf

To enable Pax CDI in Apache Karaf, perform the following steps:
  1. Add the required pax-cdi and pax-cdi-weld features to the Karaf container, as follows:
    JBossFuse:karaf@root> features:install pax-cdi pax-cdi-weld
  2. When the Pax CDI features are installed in the Karaf container, this is not sufficient to enable CDI. You must also explicitly enable Pax CDI in each bundle that uses CDI (so that it becomes a bean bundle). To enable Pax CDI in a bundle, open the pom.xml file in your bundle's Maven project and add the following Require-Capability element to the configuration of the Maven bundle plug-in:
    <project ...>
      ...
      <build>
        <plugins>
          ...
          <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-bundle-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
              <instructions>
                <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName>
                <Import-Package>*</Import-Package>
                <Require-Capability>
                  osgi.extender; filter:="(osgi.extender=pax.cdi)"
                </Require-Capability>
              </instructions>
            </configuration>
          </plugin>
          ...
        </plugins>
      </build>
      ...
    </project>
  3. To access the CDI annotations in Java, you must add a dependency on the CDI API package. Edit your bundle's POM file, pom.xml, to add the CDI API package as a Maven dependency:
    <project ...>
      ...
      <dependencies>
        ...
        <!-- CDI API -->
        <dependency>
          <groupId>javax.enterprise</groupId>
          <artifactId>cdi-api</artifactId>
          <version>${cdi-api-1.2-version}</version>
          <scope>provided</scope>
        </dependency>
        ...
      </dependencies>
      ...
    </project>
  4. Rebuild your bundle in the usual way for your Maven project. For example, using the command:
    mvn clean install
  5. Deploy the bundle to the Karaf container in the usual way (for example, using the osgi:install console command).