<chapter id="CDI">
    <title>CDI Integration</title>
    <para>This module provides integration with JSR-299 (Contexts and
        Dependency Injection for the Jakarta EE platform)
    </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 your 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>javax.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 you have an
            existing RESTEasy application, all that needs to
            be done is to
            add the
            resteasy-cdi jar into your project's
            <code>WEB-INF/lib</code>
            directory.
            When using
            maven, this can be achieve 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>
