<chapter id="CDI">
    <title>CDI Integration</title>
    <para>This module provides integration with <ulink url="https://jakarta.ee/specifications/cdi/3.0/jakarta-cdi-spec-3.0.html">(Contexts and Dependency Injection for the Jakarta EE platform)</ulink>
    </para>
    <section>
        <title>Using CDI beans as &REST-API; components</title>
        <para>
            Both the &REST-API; 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
            <code>@Path</code> or <code>@Provider</code>
            is required for it to become a &REST-API; component.  Without the
            integration code, annotating a class suitable for being a CDI bean with
            &REST-API; annotations leads into a faulty result (&REST-API; component
            not managed by CDI).  The resteasy-cdi module is a bridge that allows
            RESTEasy to work with class instances obtained from the CDI container.
        </para>
        <para>
            During a web service invocation, resteasy-cdi asks the CDI container for the
            managed instance of a &REST-API; 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.
        </para>
        <para>
            As a result, CDI services like injection, lifecycle management,
            events, decoration and interceptor bindings can be used in &REST-API;
            components.
        </para>
    </section>
    <section>
        <title>Default scopes</title>
        <para>
            A CDI bean that does not explicitly define a scope is
            <code>@Dependent</code> 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 &REST-API; components as they
            designate component's lifecycle boundaries explicitly. Therefore, the
            resteasy-cdi module alters the default scoping in the following way:
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    If a &REST-API; root resource does not define a scope
                    explicitly, it is bound to the Request scope.
                </para>
            </listitem>
            <listitem>
                <para>
                    If a &REST-API; Provider or <code>jakarta.ws.rs.Application</code>
                    subclass does not define a scope explicitly, it is bound to the
                    Application scope.
                </para>
            </listitem>
        </itemizedlist>
        <warning>
            <para>
                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.
            </para>
        </warning>
    </section>
    <section>
        <title>Configuration within WildFly</title>
        <para>
            CDI integration is provided with no additional configuration with WildFly.
        </para>
    </section>
    <section>
        <title>Configuration with different distributions</title>
        <para>
            Provided there is an existing RESTEasy application, all that needs to
            be done is to add the resteasy-cdi jar into the project's
            <code>WEB-INF/lib</code> directory.  When using maven, this can be achieved by defining the
            following dependency.
            <programlisting><![CDATA[<dependency>
	<groupId>org.jboss.resteasy</groupId>
	<artifactId>resteasy-cdi</artifactId>
	<version>${project.version}</version>
</dependency>]]></programlisting>
        </para>
        <para>
            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)
        </para>
        <programlisting language="xml"><![CDATA[<context-param>
	<param-name>resteasy.injector.factory</param-name>
	<param-value>org.jboss.resteasy.cdi.CdiInjectorFactory</param-value>
</context-param>]]></programlisting>
        <para>
            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.
            <ulink
                    url="http://docs.jboss.org/weld/reference/latest/en-US/html/environments.html">Weld-servlet module
            </ulink>
            can be used for this purpose.
        </para>
    </section>
</chapter>
