<chapter id="Migration_from_older_versions">
<title>Migration from older versions</title>
<sect1>
    <title>Migration to RESTEasy 3.0 series</title>
    
    <para>
        Many facilities from RESTEasy 2 appear in a different form in RESTEasy 3. For example, much
        of the client framework in RESTEasy 2 is formalized, in modified form, in JAX-RS 2.0. RESTEasy
        versions 3.0.x implement both the older deprecated form and the newer conformant form. The
        deprecated form is moved to legacy module in RESTEasy 3.1 and finally removed in RESTEasy 4.
        For more information on upgrading from various deprecated facilities in RESTEasy 2, see
        <ulink url="http://docs.jboss.org/resteasy/docs/resteasy-upgrade-guide-en-US.pdf">http://docs.jboss.org/resteasy/docs/resteasy-upgrade-guide-en-US.pdf</ulink>
    </para>
</sect1>



<sect1 id="Migration_to_RESTEasy_3.1">
    <title>Migration to RESTEasy 3.1 series</title>

    <para>
    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
    </para>
    
    <itemizedlist>
      <listitem>module reorganization</listitem>
      <listitem>package reorganization</listitem>
      <listitem>new features</listitem>
      <listitem>minor behavioral changes</listitem>
      <listitem>miscellaneous changes</listitem>
    </itemizedlist>
    
    <para>
    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:
    </para>
    
    <orderedlist>
      <listitem>
      <para><emphasis role="bold">RESTEasy 2</emphasis>: 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.</para>
      </listitem>
      <listitem>
      <para><emphasis role="bold">RESTEasy 3</emphasis>: 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.</para>
      </listitem>
    </orderedlist>
    
    <para>
    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.
    </para>
    
    <para>
    Now, there are three potential target audiences of users planning to upgrade to RESTEasy 3.1.0.Final:
    </para>
    
    <orderedlist>
      <listitem>
      <para>Those currently using RESTEasy API 3 with some RESTEasy 3.0.x release</para>
      </listitem>
      <listitem>
      <para>Those currently using RESTEasy API 2 with some RESTEasy 2.x or 3.0.x release and planning
      to upgrade to RESTEasy API 3</para>
      </listitem>
      <listitem>
      <para>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</para>
      </listitem>
    </orderedlist>
    
    <para>
    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
    <ulink url="http://docs.jboss.org/resteasy/docs/resteasy-upgrade-guide-en-US.pdf">Upgrading from RESTEasy 2 to RESTEasy 3</ulink>.
    </para>

    <para>
    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.
    </para>
    
    <sect1>
    <title>Upgrading with RESTEasy 3 API</title>
    
    <para>
    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
    </para>
    
    <itemizedlist>
      <listitem>
      <ulink url="https://issues.jboss.org/browse/RESTEASY-1341">RESTEASY-1341: Build method of org.jboss.resteasy.client.jaxrs.internal.ClientInvocationBuilder always return the same instance.</ulink>
      <para>
      When a <methodname>build()</methodname> method from
      </para>
      <itemizedlist>
         <listitem><classname>org.jboss.resteasy.client.jaxrs.internal.ClientInvocationBuilder</classname> in resteasy-client,</listitem>
         <listitem><classname>org.jboss.resteasy.specimpl.LinkBuilderImpl</classname> in resteasy-jaxrs,</listitem>
         <listitem><classname>org.jboss.resteasy.specimpl.ResteasyUriBuilder</classname> in resteasy-jaxrs</listitem>
      </itemizedlist>
      <para>
      is called, it will return a new object. This behavior might be seen indirectly. For example,
      </para>
      <programlisting>
Builder builder = client.target(generateURL(path)).request();
...
Link link = new LinkBuilderImpl().uri(href).build();
...
URI uri = uriInfo.getBaseUriBuilder().path("test").build();
      </programlisting>
      </listitem>
      
      <listitem>
      <ulink url="https://issues.jboss.org/browse/RESTEASY-1433">RESTEASY-1433: Compile with JDK 1.8 source/target version</ulink>
      <para>
      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.
      </para>
      </listitem>
      
      <listitem>
      <ulink url="https://issues.jboss.org/browse/RESTEASY-1484">RESTEASY-1484: CVE-2016-6346: Abuse of GZIPInterceptor in can lead to denial of service attack</ulink>
      <para>
      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 <link linkend='gzip'>GZIP Compression/Decompression</link>.
      </para>
      <para><emphasis role="bold">Note.</emphasis> Because of some package reorganization due to RESTEASY-1531 (see below),
      the GZIP interceptors, which used to be in package <classname>org.jboss.resteasy.plugins.interceptors.encoding</classname> are
      now in <classname>org.jboss.resteasy.plugins.interceptors</classname>.</para>
      </listitem>
      
      <listitem>
      <ulink url="https://issues.jboss.org/browse/RESTEASY-1531">RESTEASY-1531: Restore removed RESTEasy internal classes into a deprecated/disabled module</ulink>
      <para>
      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:
      </para>
      
      <itemizedlist>
        <listitem>
          <literallayout><classname>org.jboss.resteasy.client.ClientURI</classname> is now
          <classname>org.jboss.resteasy.annotations.ClientURI</classname></literallayout>
        </listitem>
        <listitem>
          <literallayout><classname>org.jboss.resteasy.core.interception.JaxrsInterceptorRegistryListener</classname> is now
<classname>org.jboss.resteasy.core.interception.jaxrs.JaxrsInterceptorRegistryListener</classname></literallayout>
        </listitem> 
	    <listitem>
	      <literallayout><classname>org.jboss.resteasy.spi.interception.DecoratorProcessor</classname> is now
<classname>org.jboss.resteasy.spi.DecoratorProcessor</classname></literallayout>
	    </listitem>
        <listitem>
          <literallayout>All of the dynamic features and interceptors in the package
<classname>org.jboss.resteasy.plugins.interceptors.encoding</classname> are now in
<classname>org.jboss.resteasy.plugins.interceptors</classname></literallayout>
        </listitem>
	  </itemizedlist>
	  </listitem>
    </itemizedlist>
    </sect1>

    <sect1>
    <title>Upgrading with RESTEasy 2 API</title>
    
    <para>
    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:
    </para>
    
        <programlisting><![CDATA[
<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="org.jboss.resteasy.resteasy-legacy"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>]]></programlisting>

    <para>
    There are a few API classes and interfaces from resteasy-jaxrs that have moved to a new package
    in resteasy-legacy. These are
    </para>
    
    <itemizedlist>
      <listitem><literallayout><classname>org.jboss.resteasy.annotations.ClientResponseType</classname> is now
<classname>org.jboss.resteasy.annotations.legacy.ClientResponseType</classname></literallayout>
      </listitem>
      <listitem><literallayout><classname>org.jboss.resteasy.spi.Link</classname> is now
	    <classname>org.jboss.resteasy.client.Link</classname></literallayout>
      </listitem>
      <listitem><literallayout><classname>org.jboss.resteasy.spi.LinkHeader</classname> is now
	    <classname>org.jboss.resteasy.client.LinkHeader</classname></literallayout>
      </listitem>
    </itemizedlist>
    </sect1>

</sect1>


<sect1>
    <title>Migration to RESTEasy 3.5+ series</title>
    <para>
      RESTEasy 3.5 series is a spin-off of the old RESTEasy 3.0 series, featuring JAX-RS 2.1 implementation.
    </para>
    <para>
      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 3.6 and all other 3.x minors after that are backward compatible evolutions of 3.5 series.
    </para>
    <para>
      The natural upgrade path for users already on RESTEasy 3.1 series is straight to RESTEasy 4 instead.
    </para>
</sect1>

<sect1>
    <title>Migration to RESTEasy 4 series</title>
    <para>
      User migrating from RESTEasy 3.0 and 3.5+ series should be aware of the changes mentioned in the
      <xref linkend="Migration_to_RESTEasy_3.1">RESTEasy 3.1 migration section</xref>. In addition to that,
      the aspects from the following sections are to be considered.
    </para>
    <section>
        <title>Public / private API</title>
        <para>
            The <classname>resteasy-jaxrs</classname> and <classname>resteasy-client</classname> modules
            in RESTEasy 3 contain most of the framework classes and
            there's no real demarcation between what is internal implementation detail and what is for public
            consumption. In WildFly, the artifact archives from those modules are also included in a public module.
            Given the common expectation of full backward compatibility of whatever comes from public modules,
            to allow for easier project evolution and maintenance, in RESTEasy 4.0.0.Final those big components
            have been split as follows: 
        </para>
        <section>
          <title>resteasy-core-spi</title>
          <para>
            The public classes of the former <classname>resteasy-jaxrs</classname> module; the following packages
            are included:
          </para>
          <itemizedlist>
            <listitem><classname>org.jboss.resteasy.annotations</classname></listitem>
            <listitem><classname>org.jboss.resteasy.api.validation</classname></listitem>
            <listitem><classname>org.jboss.resteasy.spi</classname></listitem>
            <listitem><classname>org.jboss.resteasy.plugins.providers.validation</classname></listitem>
          </itemizedlist>
        </section>
        <section>
          <title>resteasy-core</title>
          <para>
            The internal details of the former <classname>resteasy-jaxrs</classname> module, including classes
            from the following packages:
          </para>
          <itemizedlist>
            <listitem><classname>org.jboss.resteasy.core</classname></listitem>
            <listitem><classname>org.jboss.resteasy.mock</classname></listitem>
            <listitem><classname>org.jboss.resteasy.plugins</classname></listitem>
            <listitem><classname>org.jboss.resteasy.specimpl</classname></listitem>
            <listitem><classname>org.jboss.resteasy.tracing</classname></listitem>
            <listitem><classname>org.jboss.resteasy.util</classname></listitem>
          </itemizedlist>
        </section>
        <section>
          <title>resteasy-client-api</title>
          <para>
            The public classes from the former <classname>resteasy-client</classname> module, basically whatever
            is used for configuring the RESTEasy client additions:
          </para>
          <itemizedlist>
            <listitem><classname>ClientHttpEngine</classname> and <classname>ClientHttpEngineBuilder</classname></listitem>
            <listitem><classname>ProxyBuilder</classname> and <classname>ProxyConfig</classname></listitem>
            <listitem><classname>ResteasyClient</classname></listitem>
            <listitem><classname>ResteasyClientBuilder</classname></listitem>
            <listitem><classname>ResteasyWebTarget</classname></listitem>
          </itemizedlist>
        </section>
        <section>
          <title>resteasy-client</title>
          <para>
            The remainings of the former <classname>resteasy-client</classname> module, internal details.
          </para>
        </section>
        <para>
          As a consequence of the split, all modules except <classname>resteasy-core-spi</classname> and
          <classname>resteasy-client-api</classname> are effectively private / internal. User applications and
          integration code should not directly rely on classes from those modules, which can be changed without
          going through any formal deprecation process.
        </para>
        <para>
          Unfortunately, the refactoring that led to this implied some unavoidable class moves and changes breaking backward
          compatibility. A detailed list of the potentially problematic changes is available on the
          <ulink url="https://github.com/resteasy/Resteasy/pull/1697">refactoring PR</ulink>.
        </para>
    </section>
    <section>
        <title>Deprecated classes and modules removal</title>
        <para>
          All classes and modules that were deprecated in RESTEasy 3 have been dropped in 4. In particular, this
          includes the legacy modules (<classname>resteasy-legacy</classname>, <classname>security-legacy</classname>)
          that were introduced in 3.1.
        </para>
        <para>
          In addition to the legacy modules, few other modules have been dropped for multiple different reasons,
          including dependency on unsupported / abandoned libraries, better options available, etc:
        </para>
        <itemizedlist>
          <listitem><classname>resteasy-jackson-provider</classname>, users should rely on <classname>resteasy-jackson2-provider</classname> instead;</listitem>
          <listitem><classname>resteasy-jettison-provider</classname>, users should rely on <classname>resteasy-jackson2-provider</classname> instead;</listitem>
          <listitem><classname>abdera-atom-provider</classname>;</listitem>
          <listitem><classname>resteasy-yaml-provider</classname>;</listitem>
          <listitem><classname>resteasy-rx-java</classname>, users should rely on <classname>resteasy-rx-java2</classname> instead;</listitem>
          <listitem><classname>tjws</classname>.</listitem>
        </itemizedlist>
        <para>
          The <classname>resteasy-validator-provider-11</classname> is also gone, with the
          <classname>resteasy-validator-provider</classname> one now supporting Bean Validation 2.0.
        </para>
    </section>
    <section>
        <title>Behavior changes</title>
        <para>
          With the <classname>ClientHttpEngine</classname> based on Apache HTTP Client 4.0 having gone (it
          was previously deprecated) and the engine based on version 4.3 of the same library being the default,
          the user might want to double check the notes about connection close in <xref linkend="apache_4_3"/>.
        </para>
        <para>
          The conversion of <classname>String</classname> ojects to <classname>MediaType</classname> objects is quite
          common in RESTEasy; for performances reasons a cache has been added to store the results of that conversion;
          by default the cache keeps the result of 200 conversions, but the number can be configured by setting the
          <classname>org.jboss.resteasy.max_mediatype_cache_size</classname> system property.
        </para>
    </section>
    <section>
        <title>Other changes</title>
        <itemizedlist>
            <listitem>
                In releases 3.x, when bean validation (<xref linkend="Validation"/>) threw instances of exceptions
                <para>
                    <itemizedlist>
                        <listitem><classname>javax.validation.ConstraintDefinitionException</classname>,</listitem>
                        <listitem><classname>javax.validation.ConstraintDeclarationException</classname>, or</listitem>
                        <listitem><classname>javax.validation.GroupDefinitionException</classname>,</listitem>
                    </itemizedlist>
                    they were wrapped in a
                    <classname>org.jboss.resteasy.api.validation.Resteasy.ResteasyViolationException</classname>,
                    which <classname>org.jboss.resteasy.api.validation.ResteasyViolationExceptionMapper</classname>,
                    the built-in implementation of
                    <classname>javax.ws.rs.ext.ExceptionMapper&lt;javax.validation.ValidationException&gt;</classname>,
                    then turned into descriptive text.
                    As of release 4.0.0, instances of <classname>ConstraintDefinitionException</classname>, etc., are thrown as is.
                    They are still caught by <classname>ResteasyViolationExceptionMapper</classname>, so, in general, there is
                    no detectable change. It should be noted, however, that an implementation of
                    <classname>ExceptionMapper&lt;ResteasyViolationException&gt;</classname>, which, prior to release
                    4.0.0, would have caught wrapped instances of <classname>ConstraintDefinitionException</classname>,
                    will not catch unwrapped instances.
                </para>
            </listitem>
            <listitem>
              The <classname>ResteasyProviderFactory</classname> is now an abstract class and is meant to be created using
              its <classname>getInstance()</classname> and <classname>newInstance()</classname> methods. Moreover, on client
              side, the resolution of the current instance is cached for each thread local context classloader.
            </listitem>
            <listitem>
              The <classname>ResteasyClient</classname> and <classname>ResteasyClientBuilder</classname> are now abstract
              classes (from <classname>resteasy-client-api</classname>) and are not meant for user direct instantiation;
              plain JAX-RS API usage is expected instead:
              <programlisting>
//ResteasyClient client = new ResteasyClientBuilder().build(); NO!
//if plan JAX-RS is enough ...
Client client = ClientBuilder.newClient();
...
//if RESTEasy API is needed ...
ResteasyClient client = (ResteasyClient)ClientBuilder.newClient();


//ResteasyClientBuilder builder = new ResteasyClientBuilder(); NO!
//if plan JAX-RS is enough ...
ClientBuilder builder = ClientBuilder.newBuilder();
...
//if RESTEasy API is needed ...
ResteayClientBuilder builder = (ResteasyClientBuilder)ClientBuilder.newBuilder();
              </programlisting>
            </listitem>
            <listitem>
              The package <classname>org.jboss.resteasy.plugins.stats</classname> (which contains a resource and some related classes) has
              been moved out of the <classname>resteasy-jaxb-provider</classname> module into a <classname>new resteasy-stats</classname> module.
            </listitem>
        </itemizedlist>
    </section>
</sect1>
</chapter>
