## CDI 2, JAX-RS and dependent libraries support

### Table of Contents

- Introduction
- CDI 2 support
- JAX-RS support
- Eclipse Microprofile support

### Introduction

CDI and JAX-RS are dependencies for many other APIs and libraries. This guide explains how to add support for them in Tomcat using two optional modules that are provided in the Tomcat sources.

### CDI 2 support

CDI 2 support is provided by the `modules/owb` optional module. It packages the Apache OpenWebBeans project and allows adding CDI 2 support to the Tomcat container. The build process of the module uses Apache Maven, and is not available as a binary bundle as it is built using a number of publicly available JARs.

The process to build CDI support is the following.

    cd $TOMCAT_SRC/modules/owb
    mvn clean && mvn package

The resulting JAR at `target/tomcat-owb-x.y.z.jar` (where x.y.z depends on the Apache OpenWebBeans version used during the build) should be processed by the Tomcat migration tool for Jakarta EE, and then be placed into the `lib` folder of the Tomcat installation.
CDI support can then be enabled for all webapps in the container by adding the following listener in `server.xml` nested inside the `Server` element:

    <Listener className="org.apache.webbeans.web.tomcat.OpenWebBeansListener" optional="true" startWithoutBeansXml="false" />

The listener will produce a non fatal error if the CDI container loading fails.
CDI support can also be enabled at the individual webapp level by adding the following listener to the webapp `context.xml` file nested inside the `Server` element:

    <Listener className="org.apache.webbeans.web.tomcat.OpenWebBeansContextLifecycleListener" />

### JAX-RS support

JAX-RS support is provided by the `modules/cxf` optional module. It packages the Apache CXF project and allows adding JAX-RS support to individual webapps. The build process of the module uses Apache Maven, and is not available as a binary bundle as it is built using a number of publicly available JARs. The support depends on CDI 2 support, which should have previously been installed at either the container or webapp level.

The process to build JAX-RS support is the following.

    cd $TOMCAT_SRC/modules/cxf
    mvn clean && mvn package

The resulting JAR at `target/tomcat-cxf-x.y.z.jar` (where x.y.z depends on the Apache CXF version used during the build) should then be placed into the `/WEB-INF/lib` folder of the desired web application.

If the CDI 2 support is available at the container level, the JAR can also be placed in the Tomcat `lib` folder, but in that case the CXF Servlet declaration must be individually added in each webapp as needed (it is normally loaded by the web fragment that is present in the JAR). The CXF Servlet class that should be used is `org.apache.cxf.cdi.CXFCdiServlet` and should be mapped to the desired root path where JAX-RS resources will be available.

The webapp as a whole should be processed by the Tomcat migration tool for Jakarta EE.

### Eclipse Microprofile support

ASF artifacts are available that implement Eclipse Microprofile specifications using CDI 2 extensions. Once the CDI 2 and JAX-RS support is installed, they will be usable by individual webapps.

The following implementations are available (reference: `org.apache.tomee.microprofile.TomEEMicroProfileListener`) as Maven artifacts which must be added to the webapp `/WEB-INF/lib` folders:

- Configuration: Maven artifact: `org.apache.geronimo.config:geronimo-config` CDI extension class: `org.apache.geronimo.config.cdi.ConfigExtension`
- Fault Tolerance: Maven artifact: `org.apache.geronimo.safeguard:safeguard-parent` CDI extension class: `org.apache.safeguard.impl.cdi.SafeguardExtension`
- Health: Maven artifact: `org.apache.geronimo:geronimo-health` CDI extension class: `org.apache.geronimo.microprofile.impl.health.cdi.GeronimoHealthExtension`
- Metrics: Maven artifact: `org.apache.geronimo:geronimo-metrics` CDI extension class: `org.apache.geronimo.microprofile.metrics.cdi.MetricsExtension`
- OpenTracing: Maven artifact: `org.apache.geronimo:geronimo-opentracing` CDI extension class: `org.apache.geronimo.microprofile.opentracing.microprofile.cdi.OpenTracingExtension`
- OpenAPI: Maven artifact: `org.apache.geronimo:geronimo-openapi` CDI extension class: `org.apache.geronimo.microprofile.openapi.cdi.GeronimoOpenAPIExtension`
- Rest client: Maven artifact: `org.apache.cxf:cxf-rt-rs-mp-client` CDI extension class: `org.apache.cxf.microprofile.client.cdi.RestClientExtension`
- JSON Web Tokens: Note: Fore reference only, unusable outside Apache TomEE; Maven artifact: `org.apache.tomee:mp-jwt` CDI extension class: `org.apache.tomee.microprofile.jwt.cdi.MPJWTCDIExtension`