[[_cdi]]
== CDI Integration

This module provides integration with https://jakarta.ee/specifications/cdi/4.1/jakarta-cdi-spec-4.1[(Contexts and Dependency Injection for the Jakarta EE platform)]

=== Using CDI beans as {spec-name} components

Both the {spec-name} and CDI specifications introduce their own component model.
On the one hand, every class placed in a CDI archive that fulfills a set of basic constraints is implicitly a CDI bean.
On the other hand, explicit decoration of a Java class with `@Path` or `@Provider` is required for it to become a {spec-name} component.
Without the integration code, annotating a class suitable for being a CDI bean with annotations leads into a faulty result ({spec-name} component not managed by CDI). {spec-name} The resteasy-cdi module is a bridge that allows RESTEasy to work with class instances obtained from the CDI container.

During a web service invocation, resteasy-cdi asks the CDI container for the managed instance of a {spec-name} component.
Then, this instance is passed to RESTEasy.
If a managed instance is not available for some reason (the class is placed in a jar which is not a bean deployment archive), RESTEasy falls back to instantiating the class itself. 

As a result, CDI services like injection, lifecycle management, events, decoration and interceptor bindings can be used in {spec-name} components.

=== Default scopes

A CDI bean that does not explicitly define a scope is `@Dependent` scoped by default.
This pseudo scope means that the bean adapts to the lifecycle of the bean it is injected into.
Normal scopes (request, session, application) are more suitable for {spec-name} components as they designate component's lifecycle boundaries explicitly.
Therefore, the resteasy-cdi module alters the default scoping in the following way: 

* If a {spec-name} root resource does not define a scope explicitly, it is bound to the Request scope.
* If a {spec-name} Provider or `jakarta.ws.rs.Application` subclass does not define a scope explicitly, it is bound to the Application scope.


[WARNING]
====
Since the scope of all beans that do not declare a scope is modified by resteasy-cdi, this affects session beans as well.
As a result, a conflict occurs if the scope of a stateless session bean or singleton is changed automatically as the spec prohibits these components to be @RequestScoped.
Therefore, you need to explicitly define a scope when using stateless session beans or singletons.
This requirement is likely to be removed in future releases. 
====

=== Configuration within WildFly

CDI integration is provided with no additional configuration with WildFly. 

=== Configuration with different distributions

Provided there is an existing RESTEasy application, all that needs to be done is to add the resteasy-cdi jar into the project's `WEB-INF/lib` directory.
When using maven, this can be achieved by defining the following dependency. 
[source,xml]
----
<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-cdi</artifactId>
    <version>${project.version}</version>
</dependency>
----

Furthermore, when running a pre-Servlet 3 container, the following context parameter needs to be specified in web.xml.
(This is done automatically via web-fragment in a Servlet 3 environment) 

[source,xml]
----
<context-param>
    <param-name>resteasy.injector.factory</param-name>
    <param-value>org.jboss.resteasy.cdi.CdiInjectorFactory</param-value>
</context-param>
----

When deploying an application to a Servlet container that does not support CDI out of the box (Tomcat, Jetty, Google App Engine), a CDI implementation needs to be added first. http://docs.jboss.org/weld/reference/latest/en-US/html/environments.html[Weld-servlet module
            ] can be used for this purpose. 