<chapter id="RESTEasy_Spring_Integration">
    <title>Spring Integration</title>

    <section id="Integration_Overview">
    <title>Overview</title>
        <para>
            There are three RESTEasy GitHub projects that provide components for RESTEasy's
            Spring Framework support.
        </para>
        <itemizedlist>
            <listitem>
                <ulink url="https://github.com/resteasy/resteasy.git">RESTEasy</ulink>:
                provides core components for Spring Framework integration.
            </listitem>
            <listitem><para>
                <ulink url="https://github.com/resteasy/resteasy-spring.git">resteasy-spring</ulink>:
                This project has been created to separate RESTEasy's Spring
                integration extensions from RESTEasy's core code.  It contains RESTEasy's
                modules <code>resteasy-spring-web, resteasy-spring, resteasy-undertow-spring</code>
                and related tests.  These modules were moved out of the RESTEasy project
                as of version 5.0.0.  In maven the GAV groupId is now
                <code>org.jboss.resteasy.spring</code>.  The artifactIds remain the same.
                <programlisting><![CDATA[
<dependency>
    <groupId>org.jboss.resteasy.spring</groupId>
    <artifactId>resteasy-spring</artifactId>
    <version>${version.org.jboss.resteasy.spring}</version>
</dependency>
            ]]></programlisting>
            </para>
            </listitem>
            <listitem><para>
                <ulink url="https://github.com/resteasy/resteasy-spring-boot.git">resteasy-spring-boot</ulink>:
                provides two Spring Boot starters.
                <programlisting><![CDATA[
<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-spring-boot-starter</artifactId>
    <version>${latest_version_of_restesy_spring_boot}</version>
</dependency>
                ]]></programlisting>
            </para>
            </listitem>
        </itemizedlist>

        <para>RESTEasy currently supports Spring version &SPRING-VERSION;</para>

        <para>
            RESTEasy provides integrated support for Spring Framework.
            It supplies a default <code>org.springframework.web.context.ContextLoaderListener</code>
            and <code>org.springframework.beans.factory.config.BeanPostProcessor</code>
            implementation that is used to run Spring applications.  Alternatively
            RESTEasy provides support for registering a custom
            <code>org.springframework.beans.factory.config.BeanFactoryPostProcessor</code>
            thus enabling the user to create their own bean factories.
        </para>

        <para>
            Spring MVC Framework support is provided in RESTEasy.
            A default implementation of Spring's <code>org.springframework.web.servlet.DispatcherServlet</code>
            is supplied.
        </para>

        <para>
            RESTEasy furnishes an Undertow based embedded Spring
            container in which Spring applications can run.  It supplies
            class <code>org.jboss.resteasy.plugins.server.undertow.spring.UndertowJaxrsSpringServer</code>
            which accepts a Spring context configuration file and preforms the appropriate wiring
            of Spring to RESTEasy.
        </para>

        <para>
            Two types of Spring Boot starters are provided by resteasy-spring-boot.
            These can be used by any
            regular Spring Boot application that wants to have REST endpoints
            and prefers RESTEasy as the JAX-RS implementation.  The starters
            integrate with Spring, thus Spring beans will be automatically
            auto-scanned, integrated, and available.  Two types of starters
            are available, one Servlet based for Tomcat and one for Reactor Netty.
        </para>

        <para>
            RESTEasy supports Spring's singleton and prototype scopes and
            Spring Web REST annotations.
        </para>

        <para>
            The following subsections discuss ways of configuring these features for
            use in RESTEasy.  Code examples can be found in project
            <ulink url="https://github.com/resteasy/resteasy-examples.git">resteasy-examples</ulink>
        </para>

    </section>


    <section id="BasicIntegration">
        <title>Basic Integration</title>
        <para>
            Basic integration makes use of RESTEasy's default implementations of interface
            <code>jakarta.servlet.ServletContextListener</code>, and classes
            <code>org.springframework.web.context.ContextLoaderListener</code>
            <code>org.springframework.beans.factory.config.BeanPostProcessor</code>
            <code>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</code>,
            <code>org.jboss.resteasy.plugins.spring.SpringContextLoaderListener</code> and
            <code>org.jboss.resteasy.plugins.spring.ResteasyBeanPostProcessor</code>.
        </para>
        <para>
            To use this feature the user must add the maven resteasy-spring dependency to their project.
        </para>
        <programlisting><![CDATA[
<dependency>
    <groupId>org.jboss.resteasy.spring</groupId>
    <artifactId>resteasy-spring</artifactId>
    <version>${version.org.jboss.resteasy.spring}</version>
</dependency>]]>
        </programlisting>


        <para>
            RESTEasy's <code>SpringContextLoaderListener</code> registers its
            <code>ResteasyBeanPostProcessor</code>.  It processes Jakarta RESTful
            Web Services annotations when a bean is created by a <code>BeanFactory</code>.
            It automatically scans for @Provider and Jakarta RESTful
            Web Services resource annotations on bean classes and registers them as
            Jakarta RESTful Web Services resources.
        </para>
        <para>
            A user's application must be configured via a <code>web.xml</code> and optionally a
            <code>bean.xml</code> file to use these classes.  The configuration files discussed
            below can be found in example,
            <ulink url="https://github.com/resteasy/resteasy-examples/tree/master/resteasy-spring-basic">Basic Example</ulink>
        </para>

        <para>
            Optionally Spring Framework can be configured to scan for the Jakarta RESTful
            Web Services resources and beans with a Spring configuration file.
            Here is an example bean.xml that declares component scanning.  In the example code
            this file is named, <code>resteasy-spring-basic.xml</code>.
        </para>
        <programlisting><![CDATA[
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:p="http://www.springframework.org/schema/p"
    xmlns:context="http://www.springframework.org/schema/context"
    xsi:schemaLocation="http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd

    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

    <context:component-scan base-package="org.jboss.resteasy.examples.springbasic">
        <context:include-filter type="annotation" expression="jakarta.ws.rs.Path"/>
    </context:component-scan>
    <context:annotation-config/>
</beans>]]>
        </programlisting>

        <para>
            Two or three elements will need to be added to the application's <code>web.xml</code>.
            Two listener classes must be declared.  The RESTEasy servlet must be identified.
            If the user provided an optional bean.xml file, that needs to be referenced also.
        </para>
        <para>Here is the content that should add into the <code>web.xml</code> file:
        </para>

        <programlisting><![CDATA[
...

    <listener>
(1)     <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
    </listener>

    <listener>
(1)     <listener-class>org.jboss.resteasy.plugins.spring.SpringContextLoaderListener</listener-class>
    </listener>

    <servlet>
        <servlet-name>resteasy-dispatcher</servlet-name>
(2)     <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>

    <context-param>
        <param-name>contextConfigLocation</param-name>
(3)     <param-value>classpath:resteasy-spring-basic.xml</param-value>
    </context-param>]]>
        </programlisting>

        <itemizedlist>
            <listitem>(1) Two listener classes must be declared,
                <code>ResteasyBootstrap</code> and <code>SpringContextLoaderListener</code>.
                The declaration order is critical.  ResteasyBootstrap must be declared first because
                <code>SpringContextLoaderListener</code> relies on <code>ServletContext</code>
                attributes initialized by it.
            </listitem>
            <listitem>(2) The RESTEasy servlet is declared.
            </listitem>
            <listitem>(3) A reference to the bean.xml file must be added if the application provides one.
            </listitem>
        </itemizedlist>

        <para>An alternative for using <code>HttpServletDispatcher</code> for deployment, a
            <code>FilterDispatcher</code> can be declared instead:
        </para>
        <programlisting><![CDATA[
<filter>
    <filter-name>resteasy-filter</filter-name>
    <filter-class>
        org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
    </filter-class>
</filter>]]>
        </programlisting>

    </section>

    <section id="CustomizedConfiguration">
        <title>Customized Configuration</title>
        <para>
            The user is not limited to using RESTEasy's <code>ContextLoaderListener</code>
            implementation.  The user may provide their own implementation, however such a
            customization will require the creation of two additional custom classes, to
            facilitate the wiring of needed RESTEasy classes into the Spring configuration.
            An implementation of <code>org.springframework.web.WebApplicationInitializer</code>
            and a class that provides an instance of
            <code>org.jboss.resteasy.plugins.spring.SpringBeanProcessorServletAware</code>
            will be needed.
            <ulink url="https://github.com/resteasy/resteasy-examples/tree/master/resteasy-spring-customized">Spring and
                Resteasy Customized Example
            </ulink> provides an example of the wiring that is required.
        </para>

        <para>
            There are four RESTEasy classes that must be registered with Spring in the
            implementation of <code>WebApplicationInitializer</code>, <code>ResteasyBootstrap</code>,
            <code>HttpServletDispatcher</code>, <code>ResteasyDeployment</code>, and
            <code>SpringBeanProcessorServletAware</code>.
        </para>
        <programlisting><![CDATA[
@Override
public void onStartup(ServletContext servletContext) throws ServletException {
(1)     servletContext.addListener(ResteasyBootstrap.class);
        AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
(2)     context.register(MyConfig.class);
(3)     servletContext.addListener(new MyContextLoaderListener(context));
(4)     ServletRegistration.Dynamic dispatcher = servletContext.addServlet("resteasy-dispatcher", new HttpServletDispatcher());
        dispatcher.setLoadOnStartup(1);
        dispatcher.addMapping("/rest/*");
}]]>
        </programlisting>
        <itemizedlist>
            <listitem>
                (1) <code>ResteasyBootstrap</code> needs to be registered in the
                <code>servletContext</code> so that the RESTEasy container can gain access to it.
            </listitem>
            <listitem>
                (2) The user's <code>MyConfig</code> class provides RESTEasy's implementation of
                <code>BeanProcessorServletAware</code> as a @Bean to the Spring container.
            </listitem>
            <listitem>
                (3) The user's implementation of <code>ContextLoaderListener</code> is registered in
                <code>servletContext</code> so that the RESTEasy container can gain access to it.
            </listitem>
            <listitem>
                (4) RESTEasy's servlet, <code>HttpServletDispatcher</code> is registered in
                <code>servletContext</code> so that the RESTEasy container can gain access to it.
            </listitem>
        </itemizedlist>

        <para>
            The user's implementation of <code>ContextLoaderListener</code> performs two
            important actions.
        </para>
        <programlisting><![CDATA[
@Override
protected void customizeContext(ServletContext servletContext, ConfigurableWebApplicationContext configurableWebApplicationContext) {
        super.customizeContext(servletContext, configurableWebApplicationContext);

(1)     ResteasyDeployment deployment = (ResteasyDeployment) servletContext.getAttribute(ResteasyDeployment.class.getName());
        if (deployment == null) {
            throw new RuntimeException(Messages.MESSAGES.deploymentIsNull());
        }
(2)     SpringBeanProcessor processor = new SpringBeanProcessor(deployment);
        configurableWebApplicationContext.addBeanFactoryPostProcessor(processor);
        configurableWebApplicationContext.addApplicationListener(processor);
    }]]>
        </programlisting>
        <itemizedlist>
            <listitem>(1) an instance of RESTEasy's <code>ResteasyDeployment</code> must be
                retrieved from the <code>servletContext</code>.
            </listitem>
            <listitem>(2) and register with Spring
            </listitem>
        </itemizedlist>

        <para>
            RESTEasy's Spring integration supports both singleton and prototype scope. It handles
            injecting <code>@Context</code> references. Constructor injection is not supported.
            With the prototype scope RESTEasy will inject any <code>@*Param</code> annotated fields
            or setters before the request is dispatched.
        </para>
        <para>
            <emphasis role="bold">Note:</emphasis> Only auto-proxied beans can be used with RESTEasy's
            Spring integration.  There will be undesirable affects if you use handcoded proxying
            with Spring, i.e., with <code>ProxyFactoryBean</code>.
        </para>

    </section>

    <section id="SpringMVC">
        <title>Spring MVC Integration</title>

        <para>
            RESTEasy can be integrated with the Spring MVC Framework. Generally speaking, &REST-API;
            can be combined with a Spring <code>org.springframework.web.servlet.DispatcherServlet</code>
            and used in the same web application.
            An application combined in this way allows the application to dispatch to either
            the Spring controller or the &REST-API; resource using the same base URL.
            In addition Spring <code>ModelAndView</code> objects can be returned as
            arguments from <code>@GET</code> resource methods.
        </para>
        <para>
            The
            <ulink url="https://github.com/resteasy/resteasy-examples/tree/master/resteasy-spring-mvc">Spring MVC
                Integration Example
            </ulink>
            demonstrates how to configure an application using Spring MVC.
        </para>
        <para>
            <code>resteasy-spring</code> provides bean xml file, <code>springmvc-resteasy.xml</code>.
            It resides in the <code>org.jboss.resteasy.spring:resteasy-spring</code> archive.
            The file defines the beans for the Spring MVC/RESTEasy integration.  The file is required
            to be imported into the user's MVC application.
            This bean file can be used as a template to define more advanced functionality,
            such as configuring multiple RESTEasy factories, dispatchers and registries.
        </para>
        <para>
            In the example, the reference to <code>springmvc-resteasy.xml</code> is declared in an
            application provided bean xml named, <code>resteasy-spring-mvc-servlet.xml</code>.
            This file imports <code>springmvc-resteasy.xml</code>.
        </para>
        <programlisting><![CDATA[
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    ">
(1)    <context:component-scan base-package="org.jboss.resteasy.examples.springmvc"/>
       <context:annotation-config/>
(2)    <import resource="classpath:springmvc-resteasy.xml"/>
....
</beans>]]>
        </programlisting>
        <itemizedlist>
            <listitem>(1) The application must tell Spring the package to scan for its &REST-API;
                resource classes
            </listitem>
            <listitem>(2) A reference to resteasy-spring project's <code>springmvc-resteasy.xml</code>
            </listitem>
        </itemizedlist>
        <para>
            The setup requires the application to provide a <code>web.xml</code> file in which a
            Spring <code>DispatcherServlet</code> implementation is declared.
            Project resteasy-spring provides a default Spring <code>DispatcherServlet</code>
            implementation, <code>org.jboss.resteasy.springmvc.ResteasySpringDispatcherServlet</code>.
            This is the <code>DispatcherServlet</code> used in the example code.
        </para>
        <para>
            The <code>DispatcherServlet</code> takes as an input parameter a reference to the application's
            bean file.  This reference is declared as an <code>init-param</code> to the <code>servlet</code>.
        </para>
        <para>The application's web.xml should define the servlet as follows:
        </para>
        <programlisting><![CDATA[
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
         http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
    <display-name>resteasy-spring-mvc</display-name>

    <servlet>
        <servlet-name>resteasy-spring-mvc</servlet-name>
 (1)    <servlet-class>org.jboss.resteasy.springmvc.ResteasySpringDispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
 (2)        <param-value>classpath:resteasy-spring-mvc-servlet.xml</param-value>
        </init-param>
    </servlet>
    ....
</web-app>]]>
        </programlisting>

        <itemizedlist>
            <listitem>(1) An implementation of Spring's <code>DispatcherServlet</code>
            </listitem>
            <listitem>(2) The application's bean xml file that imports
                <code>org.jboss.resteasy.spring:resteasy-spring</code> archive's
                <code>springmvc-resteasy.xml</code> file.
            </listitem>
        </itemizedlist>

        <para>
            A <code>jakarta.ws.rs.core.Application</code> subclass can be combined with a Spring
            <code>DispatcherServlet</code> and used in the same web application.
            In this scenario a servlet declaration is required for the Spring
            <code>DispatcherServlet</code> and the <code>jakarta.ws.rs.core.Application</code> subclass.
            A RESTEasy Configuration Switch, <code>resteasy.scan.resources</code> must be declared
            as a context-param in the <code>web.xml</code>.  Here is an example of the minimum
            configuration information needed in the <code>web.xml</code>.
        </para>
        <programlisting><![CDATA[
<web-app>
    <servlet>
        <servlet-name>mySpring</servlet-name>
 (1)    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>mySpring</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>myAppSubclass</servlet-name>
 (2)    <servlet-class>org.my.app.EntryApplicationSubclass</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>myAppSubclass</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

    <!-- required RESTEasy Configuration Switch directs auto scanning
         of the archive for Jakarta RESTful Web Services resource files
    -->
    <context-param>
 (3)    <param-name>resteasy.scan.resources</param-name>
        <param-value>true</param-value>
    </context-param>
</web-app>]]>
        </programlisting>
        <itemizedlist>
            <listitem>(1) <code>DispatcherServlet</code> declaration</listitem>
            <listitem>(2) <code>Application</code> declaration</listitem>
            <listitem>(3) scanning configuration switch</listitem>
        </itemizedlist>

        <para><emphasis role="bold">Note:</emphasis> RESTEasy parameters like
            <code>resteasy.scan.resources</code> may be set in a variety of ways. See
            <xref linkend="microprofile_config"/>
            for more information about application configuration.
        </para>
        <para>
            If the web application contains &REST-API; provider classes the RESTEasy Configuration
            Switch, <code>resteasy.scan.providers</code>, will also be needed. If the url-pattern for the
            &REST-API; <code>Application</code> subclass is other than <code>/*</code> a declaration
            of RESTEasy Configuration Switch, <code>resteasy.servlet.mapping.prefix</code> will be
            required. This switch can be declared either as a <code>context-param</code> or as a servlet
            <code>init-param</code>.
            It's value must be the text that precedes the <code>/*</code>. Here is an example of such
            a <code>web.xml</code>:

            <programlisting><![CDATA[
<web-app>
    .....

    <servlet>
        <servlet-name>myAppSubclass</servlet-name>
        <servlet-class>org.my.app.EntryApplicationSubclass</servlet-class>

        <init-param>
 (1)        <param-name>resteasy.servlet.mapping.prefix</param-name>
            <param-value>/resources</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>myAppSubclass</servlet-name>
 (2)    <url-pattern>/resources/*</url-pattern>
    </servlet-mapping>

    <context-param>
 (3)    <param-name>resteasy.scan.resources</param-name>
        <param-value>true</param-value>
    </context-param>
    <context-param>
 (3)    <param-name>resteasy.scan.providers</param-name>
        <param-value>true</param-value>
    </context-param>
</web-app>]]>
            </programlisting>
        </para>
        <itemizedlist>
            <listitem>(1) Configuration switch, resteasy.servlet.mapping.prefix, specified in an init-param
            </listitem>
            <listitem>(2) The url-pattern /* is preceeded by /resources.
            </listitem>
            <listitem>(3) Configuration switches specified as context-params
            </listitem>
        </itemizedlist>

    </section>

    <section id="SpringUndertow">
        <title>Undertow Embedded Spring Container</title>

        <para>
            Project <code>resteasy-spring</code> provides an Undertow based embedded Spring container
            module, <code>resteasy-undertow-spring</code>.  It provides class,
            <code>org.jboss.resteasy.plugins.server.undertow.spring.UndertowJaxrsSpringServer</code>.
            This class has a single method, <code>undertowDeployment</code>
            which requires an input parameter that references a Spring context configuration
            file.  The Spring context configuration data is used to wire Spring into Undertow.
        </para>
        <para>
            An example of setting up the Undertow embedded Spring container can be found
            in example,
            <ulink
                    url="https://github.com/resteasy/resteasy-examples/tree/master/resteasy-spring-undertow">
                resteasy-spring-undertow
            </ulink>
        </para>
        <para>
            To use this container the user must add the following two archives to their
            maven project.
        </para>
        <programlisting><![CDATA[
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-undertow</artifactId>
  <version>${SOME_VERSION}</version>
</dependency>
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-undertow-spring</artifactId>
  <version>${SOME_VERSION}</version>
</dependency>]]>
        </programlisting>

        <para>
            The user's application must provide a bean xml file that imports a reference
            to the <code>org.jboss.resteasy.spring:resteasy-spring</code> archive's bean
            file, <code>springmvc-resteasy.xml</code>.
            In the example code the user's provided file is named, <code>spring-servlet.xml</code>
            Here is the information needed in this file.
        </para>
        <programlisting><![CDATA[
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        ">
    <context:component-scan base-package="org.jboss.resteasy.springmvc.test"/>
    <context:annotation-config/>
    <import resource="classpath:springmvc-resteasy.xml"/>
</beans>]]>
        </programlisting>

        <para>
            Below is a code snippet that shows the creation and configuration of the
            Undertow embedded Spring container.
        </para>
        <programlisting><![CDATA[
(1) UndertowJaxrsSpringServer server = new UndertowJaxrsSpringServer();
    server.start();

(2) DeploymentInfo deployment = server.undertowDeployment("classpath:spring-servlet.xml", null);
    deployment.setDeploymentName(BasicSpringTest.class.getName());
    deployment.setContextPath("/");
    deployment.setClassLoader(BasicSpringTest.class.getClassLoader());
    server.deploy(deployment);]]>
        </programlisting>

        <itemizedlist>
            <listitem>(1) Create an instance of the Undertow Spring server</listitem>
            <listitem>(2) Provide the server a reference to the user's application bean.xml</listitem>
        </itemizedlist>

    </section>

    <section id="SpringWebAnnotation">
        <title>Processing Spring Web REST annotations in RESTEasy</title>

        <para>
            RESTEasy also provides the ability to process Spring Web REST annotations (i.e. Spring classes annotated
            with <code>@RestController</code>)
            and handle related REST requests without delegating to Spring MVC. This functionality is currently
            experimental.
        </para>
        <para>
            In order for RESTEasy to be able to process Spring <code>@RestController</code>,
            the user must include the following maven dependency.
        </para>
        <para>
            <programlisting><![CDATA[
<dependency>
    <groupId>org.jboss.resteasy.spring</groupId>
    <artifactId>resteasy-spring-web</artifactId>
    <version>${version.org.jboss.resteasy.spring}</version>
</dependency>]]>
            </programlisting>
        </para>
        <para>
            RESTEasy does not auto-scan for <code>@RestController</code> annotated classes, so
            all <code>@RestController</code> annotated classes need to be declared in the application's
            <code>web.xml</code> file as shown below.
        </para>
        <programlisting><![CDATA[
 <web-app>
   <display-name>RESTEasy application using Spring REST annotations</display-name>

    <context-param>
        <param-name>resteasy.scanned.resource.classes.with.builder</param-name>
        <param-value>org.jboss.resteasy.spi.metadata.SpringResourceBuilder:org.example.Controller1,org.example.Controller2</param-value>
    </context-param>
   ...
</web-app>]]>
        </programlisting>
        <para>
            In the example above, <code>Controller1</code> and <code>Controller2</code> are registered and expected
            to be annotated with <code>@RestController</code>.
        </para>
        <para>
            Currently supported annotations:
        </para>
        <table frame="topbot">
            <tgroup cols="2" rowsep="1" colsep="1">
                <thead>
                    <row>
                        <entry>Annotation</entry>
                        <entry>Comment</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>@RestController</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@RequestMapping</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@GetMapping</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@PostMapping</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@PutMapping</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@DeleteMapping</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@PatchMapping</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@RequestParam</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@RequestHeader</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@MatrixVariable</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@PathVariable</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@CookieValue</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@RequestBody</entry>
                        <entry/>
                    </row>
                    <row>
                        <entry>@ResponseStatus</entry>
                        <entry>Only supported as a method annotation</entry>
                    </row>
                    <row>
                        <entry>@RequestParam</entry>
                        <entry/>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para>
            The use of <code>org.springframework.http.ResponseEntity</code>,
            <code>jakarta.servlet.http.HttpServletRequest</code> and
            <code>jakarta.servlet.http.HttpServletResponse</code> are supported as return values
            of method parameters.
        </para>
        <para>A usage example can be found in sample project <ulink
                url="https://github.com/resteasy/resteasy-examples/tree/master/resteasy-spring-rest">resteasy-spring-rest
        </ulink>
        </para>
    </section>

    <section id="SpringBootStarter">
        <title>Spring Boot starter</title>

        <para>
            RESTEasy supports Spring Boot integration. The code was developed by PayPal
            and donated to the RESTEasy community. The project is maintained in the
            <ulink url="https://github.com/resteasy/resteasy-spring-boot">RESTEasy Spring Boot Starter Project</ulink>.
        </para>
        <para>
            Here is the usage in brief:
        </para>
        <para>Add this maven dependency to the Spring Boot application:
            <programlisting><![CDATA[
<dependency>
   <groupId>org.jboss.resteasy</groupId>
   <artifactId>resteasy-spring-boot-starter</artifactId>
   <version>${latest_version_of_restesy_spring_boot}</version>
   <scope>runtime</scope>
</dependency>]]>
            </programlisting>
        </para>
        <para>
            Use Spring annotation <code>@Component</code> to register a &REST-API;
            <code>Application</code> class:
            <programlisting><![CDATA[
package com.sample.app;

import org.springframework.stereotype.Component;
import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@Component
@ApplicationPath("/sample-app/")
public class JaxrsApplication extends Application {
}]]>
            </programlisting>
        </para>
        <para>
            To register &REST-API; resources and providers, define them as Spring beans.  They will be
            automatically registered. Notice that &REST-API; resources can be singleton or request scoped, while &REST-API;
            providers must be singletons.
        </para>
        <para>To see an example, please check the <ulink
                url="https://github.com/resteasy/resteasy-spring-boot/tree/master/sample-app">sample-app
        </ulink>.
        </para>
    </section>

    <section id="SpringUpgradeInWildfly">
        <title>Upgrading in Wildfly</title>
        <para>
            As noted in <xref linkend="upgrading-wildfly"/>, Galleon is used in updating
            RESTEasy distributions in Wildfly.  RESTEasy Spring also uses Galleon for the
            same task.  Follow the directions in that section to install Galleon, then
            run command:
        </para>
        <programlisting>
galleon.sh install org.jboss.resteasy.spring:galleon-feature-pack:{CURRENT-VERSION} --dir=${WILDFLY-HOME}
        </programlisting>
        <para>
            Note Installing resteasy-spring feature pack, also installs the corresponding RESTEasy
            archives do to transitive dependencies.
        </para>
    </section>
</chapter>
