JBoss.orgCommunity Documentation
RESTEasy integrates with Springframework in various forms. In this chapter we introduce different methods to integrate Springframework with RESTEasy.
For Maven users, you must use the resteasy-spring
artifact. And here is the dependency you
should use:
<dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-spring</artifactId> <version>3.15.1.Final</version> </dependency>
RESTEasy comes with its own ContextLoaderListener
that registers a RESTEasy specific
BeanPostProcessor
that processes JAX-RS annotations when a bean is created by a BeanFactory
. And it will
automatically scan for @Provider
and JAX-RS resource annotations on your
bean class and
register them as JAX-RS resources.
Here is the content that you should add into your web.xml
file:
<listener> <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class> </listener> <listener> <listener-class>org.jboss.resteasy.plugins.spring.SpringContextLoaderListener</listener-class> </listener>
Please note that the SpringContextLoaderListener
must be declared after
ResteasyBootstrap
as it
uses
ServletContext
attributes initialized by it.
And you can configure the Springframework to scan for the JAX-RS resources and beans in a Spring configuration file. The content of the file is shown as follow:
<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="javax.ws.rs.Path"/> </context:component-scan> <context:annotation-config/> </beans>
Let's say the above file is named resteasy-spring-basic.xml
, then in your web.xml
the
can be configured like this:
<context-param> <param-name>contextConfigLocation</param-name> <param-value>classpath:resteasy-spring-basic.xml</param-value> </context-param>
In addition, you need to configure your RESTEasy servlet in web.xml
. Here is the example:
<servlet> <servlet-name>Resteasy</servlet-name> <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class> </servlet> <servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/rest/*</url-pattern> </servlet-mapping>
Instead of using HttpServletDispatcher
for deployment, you can also use the
FilterDispatcher
in web.xml
:
<filter> <filter-name>resteasy-filter</filter-name> <filter-class> org.jboss.resteasy.plugins.server.servlet.FilterDispatcher </filter-class> </filter>
To see a complete example of the above basic usage, please check the Basic Example we provided.
If you do not want to use the SpringContextLoaderListener
provided by RESTEasy, and want to
create your bean factories, then you can manually
register the RESTEasy BeanFactoryPostProcessor
by creating an instance of the RESTEasy
SpringBeanProcessor
.
And you must configure the RestasyBootstrap
into the scope to create the
ResteasyDeployment
so the relative
classes can be fetched from ServletContext
.
There is also a
SpringBeanProcessorServletAware
class that implements the ServletContextAware
interface provided by Springframework.
The SpringBeanProcessorServletAware
can be used to fetch the
Registry
and ResteasyProviderFactory
from the ServletContext
.
To demonstrate the above process, we have also provide an example. Please check the Spring and Resteasy Customized Example we provided.
Our Spring integration supports both singletons and the "prototype" scope. RESTEasy handles injecting
@Context
references. Constructor injection is not supported though. Also, with the "prototype" scope,
RESTEasy will inject any @*Param
annotated fields or setters before the request is dispatched.
NOTE: You can only use auto-proxied beans with our base Spring integration. You will have undesirable
affects if you are doing handcoded proxying with Spring, i.e., with ProxyFactoryBean
. If you
are using
auto-proxied beans, you will be ok.
RESTEasy can also integrate with the Spring DispatcherServlet
. The advantages of using this are
that you
have a simpler web.xml
file, you can dispatch to either Spring controllers or RESTEasy from
under the same
base URL, and finally, the most important, you can use Spring ModelAndView
objects as return
arguments from
@GET
resource methods. Setup requires you using the Spring DispatcherServlet
in your web.xml
file, as well
as importing the springmvc-resteasy.xml
file into your base Spring beans xml file. Here's an
example
web.xml
file:
<web-app> <display-name>Archetype Created Web Application</display-name> <servlet> <servlet-name>Spring</servlet-name> <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>Spring</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app>
Then within your main Spring beans xml, import the springmvc-resteasy.xml
file
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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 "> <!-- Import basic SpringMVC RESTEasy integration --> <import resource="classpath:springmvc-resteasy.xml"/> ....
You can specify resteasy configuration options by overriding the resteasy.deployment
bean which
is an
instance
of ResteasyDeployment
. Here's an example of adding media type suffix mappings as well
as enabling the RESTEasy asynchronous job service.
<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 "> <!-- Import basic SpringMVC RESTEasy integration --> <import resource="classpath:springmvc-resteasy.xml" /> <!-- override the bean definition for deployment --> <bean id="resteasy.deployment" class="org.jboss.resteasy.spi.ResteasyDeployment" init-method="start" destroy-method="stop"> <property name="asyncJobServiceEnabled" value="true"/> <property name="mediaTypeMappings"> <map> <entry key="json" value="application/json" /> <entry key="xml" value="application/xml" /> </map> </property> </bean> ...
A JAX-RS Application subclass can be combined with a Spring DispatcherServlet and used in the same web application. An application combined in this way allows you to dispatch to either the Spring controller or the JAX-RS resource using the same base URL. In addition you can use the Spring ModelAndView objects as return arguments from @GET resource methods.
Configuring a web application of this type requires a web.xml and spring-servlet.xml file and a reference to springmvc-resteasy.xml. A servlet definition is required for both the Spring DispatcherServlet and the Application subclass in the web.xml, as well as RESTEasy Configuration Switch, resteasy.scan.resources. Here is an example of the minimum configuration information needed in the web.xml.
<web-app> <servlet> <servlet-name>mySpring</servlet-name> <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> <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 JAX-RS resource files --> <context-param> <param-name>resteasy.scan.resources</param-name> <param-value>true</param-value> </context-param> </web-app>
Note that RESTEasy parameters like resteasy.scan.resources may be set in a variety of ways. See Section 3.4, “Configuring RESTEasy” for more information about application configuration.
If your web application contains JAX-RS provider classes the RESTEasy Configuration Switch, resteasy.scan.providers, will also be needed. And if the url-pattern for the JAX-RS Application subclass is other than /* you will need to declare the RESTEasy Configuration Switch, resteasy.servlet.mapping.prefix. This switch can be declare either as a context-param or as a servlet init-param. It's value must be the text that preceeds the /*. Here is an example of such a web.xml.
<web-app> <servlet> <servlet-name>spring</servlet-name> <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>spring</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> <servlet> <servlet-name>myAppSubclass</servlet-name> <servlet-class>org.my.app.EntryApplicationSubclass</servlet-class> <init-param> <param-name>resteasy.servlet.mapping.prefix</param-name> <param-value>/resources</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>myAppSubclass</servlet-name> <url-pattern>/resources/*</url-pattern> </servlet-mapping> <context-param> <param-name>resteasy.scan.resources</param-name> <param-value>true</param-value> </context-param> <context-param> <param-name>resteasy.scan.providers</param-name> <param-value>true</param-value> </context-param> </web-app>
The spring-servlet.xml file must import springmvc-resteasy.xml, however this file does not need to be present in the archive. In addition a component-scan, declaration of the packages that contain you application classes is needed. At minimum your spring-servlet.xml should contain these statements.
<beans> <import resource="classpath:springmvc-resteasy.xml"/> <context:component-scan base-package="org.my.app"/> </beans>
The RESTEasy project does not include its own component for Spring Boot integration, however PayPal has developed a very interesting RESTEasy Spring Boot starter and shared it with the community. You can see below an example of how to use it. Please refer to the relevant documentation on GitHub for further information.
First, add dependency com.paypal.springboot:resteasy-spring-boot-starter
to your Spring
Boot application. It is recommended to you use the latest version.
Second, optionally you can register one or more JAX-RS application classes. To do so, just define it as a
Spring bean, and it will be automatically registered. See the example below.
package com.sample.app; import org.springframework.stereotype.Component; import javax.ws.rs.ApplicationPath; import javax.ws.rs.core.Application; @Component @ApplicationPath("/sample-app/") public class JaxrsApplication extends Application { }
Finally, to register JAX-RS resources and providers, just define them as Spring beans, and they will be automatically registered. Notice that JAX-RS resources can be singleton or request scoped, while JAX-RS providers must be singletons.
We provide a undertow-based embedded spring container module, called "resteasy-undertow-spring". To use it, you need to add the following additional dependencies into your project:
<dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-undertow</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-undertow-spring</artifactId> <scope>test</scope> </dependency>
In the "resteasy-undertow-spring" module, we have a embedded server class called "UndertowJaxrsSpringServer". In its "undertowDeployment(...)" method, it will accept the spring context configuration file:
public DeploymentInfo undertowDeployment(String contextConfigLocation, String mapping)
We can provide a minimal spring config like the following:
<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>
In above configuration, the "springmvc-resteasy.xml" in the classpath is provided by the "resteasy-spring" module by default. Let's name the above configuration file with "spring-servlet.xml", and the following code will include it and setup the UndertowJaxrsSpringServer and start it:
UndertowJaxrsSpringServer server = new UndertowJaxrsSpringServer(); server.start(); DeploymentInfo deployment = server.undertowDeployment("classpath:spring-servlet.xml", null); deployment.setDeploymentName(BasicSpringTest.class.getName()); deployment.setContextPath("/"); deployment.setClassLoader(BasicSpringTest.class.getClassLoader()); server.deploy(deployment);
Above is the code example to setup and start UndertowJaxrsSpringServer. To see a complete example, please check the resteasy-springMVC as demo app.
Note.
As noted inSection 3.1.2, “Upgrading RESTEasy within WildFly”, the RESTEasy distribution comes with a zip file
called resteasy-jboss-modules-<version>.zip
,
which can be unzipped into the modules/system/layers/base/ directory of WildFly to upgrade to a new version
of RESTEasy.
Because of the way resteasy-spring is used in WildFly, after unzipping the zip file, it is also necessary to
remove the
old resteasy-spring jar from
modules/system/layers/base/org/jboss/resteasy/resteasy-spring/main/bundled/resteasy-spring-jar.