# Migration to RESTEasy 3.5 series

RESTEasy 3.5 series is a spin-off of the old RESTEasy 3.0 series, featuring JAX-RS 2.1 implementation.

The reason why 3.5 comes from 3.0 instead of the 3.1 / 4.0 development streams is basically providing users with a selection of RESTEasy 4 critical / strategic new features, while ensuring full backward compatiblity. As a consequence, no major issues are expected when upgrading RESTEasy from 3.0.x to 3.5.x.

The natural upgrade path for users already on RESTEasy 3.1 series is straight to RESTEasy 4 instead.

## Migration to RESTEasy 3.1 series

RESTEasy 3.1.0.Final release comes with many changes compared to previous 3.0 point releases. User discernible changes in RESTEasy 3.1.0.Final include

- module reorganization
- package reorganization
- new features
- minor behavioral changes
- miscellaneous changes

In this chapter we focus on changes that might cause existing code to fail or behave in new ways. The audience for this discussion may be partitioned into three subsets, depending on the version of RESTEasy currently in use, the API currently in use, and the API to be used after an upgrade to RESTEasy 3.1. The following APIs are available:

1. RESTEasy 2: RESTEasy 2 conforms to the JAX-RS 1 specification, and adds a variety of additional facilities, such as a client API, a caching system, an interceptor framework, etc. All of these user facing classes and interfaces comprise the RESTEasy 2 API.

2. RESTEasy 3: RESTEasy 3 conforms to the JAX-RS 2 specification, and adds some additional facilities. Many of the non-spec facilities from the RESTEasy 2 API are formalized, in altered form, in JAX-RS 2, in which case the older facilites are deprecated. The non-deprecated user facing classes and interfaces in RESTEasy 3 comprise the RESTEasy 3 API.

These definitions are rather informal and imprecise, since the user facing classes / interfaces in Resteasy 3.0.19.Final, for example, are a proper superset of the user facing classes / interfaces in RESTEasy 3.0.1.Final. For this discussion, we identify the API with the version currently in use in a given project.

Now, there are three potential target audiences of users planning to upgrade to RESTEasy 3.1.0.Final:

1. Those currently using RESTEasy API 3 with some RESTEasy 3.0.x release

2. Those currently using RESTEasy API 2 with some RESTEasy 2.x or 3.0.x release and planning to upgrade to RESTEasy API 3

3. Those currently using RESTEasy API 2 with some RESTEasy 2.x or 3.0.x release and planning to continue to use RESTEasy API 2

Of these, users in Group 2 have the most work to do in upgrading from RESTEasy API 2 to RESTEasy API 3. They should consult the separate guide Upgrading from RESTEasy 2 to RESTEasy 3.

Ideally, users in Groups 1 and 3 might make some changes to take advantage of new features but would have no changes forced on them by reorganization or altered behavior. Indeed, that is almost the case, but there are a few changes that they should be aware of.

## Upgrading with RESTEasy 3 API

All RESTEasy changes are documented in JIRA issues. Issues that describe detectable changes in release 3.1.0.Final that might impact existing applications include

- RESTEASY-1341: Build method of org.jboss.resteasy.client.jaxrs.internal.ClientInvocationBuilder always return the same instance.

  When a `build()` method from

  - `org.jboss.resteasy.client.jaxrs.internal.ClientInvocationBuilder` in resteasy-client,
  - `org.jboss.resteasy.specimpl.LinkBuilderImpl` in resteasy-jaxrs,
  - `org.jboss.resteasy.specimpl.ResteasyUriBuilder` in resteasy-jaxrs

  is called, it will return a new object. This behavior might be seen indirectly. For example,

      Builder builder = client.target(generateURL(path)).request();
      ...
      Link link = new LinkBuilderImpl().uri(href).build();
      ...
      URI uri = uriInfo.getBaseUriBuilder().path("test").build();

- RESTEASY-1433: Compile with JDK 1.8 source/target version

  As it says. Depending on the application, it might be necessary to recompile with a target of JDK 1.8 so that calls to RESTEasy code can work.

- RESTEASY-1484: CVE-2016-6346: Abuse of GZIPInterceptor in can lead to denial of service attack

  Prior to release 3.1.0.Final, the default behavior of RESTEasy was to use GZIP to compress and decompress messages whenever "gzip" appeared in the Content-Encoding header. However, decompressing messages can lead to security issues, so, as of release 3.1.0.Final, GZIP compression has to be enabled explicitly. For details, see Chapter GZIP Compression/Decompression.

  Note. Because of some package reorganization due to RESTEASY-1531 (see below), the GZIP interceptors, which used to be in package `org.jboss.resteasy.plugins.interceptors.encoding` are now in `org.jboss.resteasy.plugins.interceptors`.

- RESTEASY-1531: Restore removed RESTEasy internal classes into a deprecated/disabled module

  This issue is related to refactoring deprecated elements of the RESTEasy 2 API into a separate module, and, ideally, would have no bearing at all on RESTEasy 3. However, a reorganization of packages has led to moving some non-deprecated API elements in the resteasy-jaxrs module:

  -     org.jboss.resteasy.client.ClientURI is now
                  org.jboss.resteasy.annotations.ClientURI

  -     org.jboss.resteasy.core.interception.JaxrsInterceptorRegistryListener is now
        org.jboss.resteasy.core.interception.jaxrs.JaxrsInterceptorRegistryListener

  -     org.jboss.resteasy.spi.interception.DecoratorProcessor is now
        org.jboss.resteasy.spi.DecoratorProcessor

  -     All of the dynamic features and interceptors in the package
        org.jboss.resteasy.plugins.interceptors.encoding are now in
        org.jboss.resteasy.plugins.interceptors

## Upgrading with RESTEasy 2 API

Most of the deprecated classes and interfaces from RESTEasy 2 have been segregated in a separate module, resteasy-legacy, as of release 3.1.0.Final. A few remain in module resteasy-jaxrs for technical reasons. Eventually, all such classes and interfaces will be removed from RESTEasy. Most of the relocated elements are internal, so ensuring that resteasy-legacy is on the classpath will make most changes undetectable. One way to do that, of course, is to include it in an application's WAR. In the context of WildFly, it is also possible to use a jboss-deployment-structure.xml file in the WEB-INF directory of your WAR file. For example:

    <jboss-deployment-structure>
        <deployment>
            <dependencies>
                <module name="org.jboss.resteasy.resteasy-legacy"/>
            </dependencies>
        </deployment>
    </jboss-deployment-structure>

There are a few API classes and interfaces from resteasy-jaxrs that have moved to a new package in resteasy-legacy. These are

-     org.jboss.resteasy.annotations.ClientResponseType is now
      org.jboss.resteasy.annotations.legacy.ClientResponseType

-     org.jboss.resteasy.spi.Link is now
      	    org.jboss.resteasy.client.Link

-     org.jboss.resteasy.spi.LinkHeader is now
      	    org.jboss.resteasy.client.LinkHeader