<chapter id="Migration_from_older_versions">
<title>Migration from older versions</title>
<sect1>
    <title>Migrating from Resteasy 2 to Resteasy 3</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 finally removed in Resteasy 3.1.0.Final. 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_3_0_25">
    <title>Migrating to 3.0.25</title>
    
    <para>
        A bug discovered in the resource method matching algorithm in Resteasy versions 3.0.x prior to 3.0.26.Final
        allowed Resteasy to consider too many resource methods in responding to requests. There are three stages in
        the matching algorithm:
    </para>
    
    <orderedlist>
        <listitem>Use the request path to choose possible resource classes.</listitem>
        <listitem>Use the request path to choose possible resource methods.</listitem>
        <listitem>Use the HTTP verb and media types, coming and going, to choose a final resource method.</listitem>
    </orderedlist>
    
    <para>
        In step 2, the set of potential resource methods are sorted, based on properties of @Path values like number
        of literals, and only the maximal elements are passed on to step 3. However, the Resteasy implementation
        prior to 3.0.26.Final passes ALL methods to step 3. For example,
    </para>
    
<programlisting>
   @Path("/")
   public static class TestResource
   {
      @GET
      @Path("complex/match")
      public String get()
      {
         return "content";
      }

      @POST
      @Path("complex/{param}")
      public String post(@PathParam("param") String param)
      {
         return "&lt;" + param + "/&gt;";
      }
   }
</programlisting>

    <para>
        Both methods can match a request with path "complex/match", but <methodname>get()</methodname> comes
        out ahead of <methodname>post()</methodname> because it has more literal characters, and 
        only <methodname>get()</methodname> is considered in step 3. [For more details about the sort, see
        the specification for JAX-RS 2.0.]
    </para>
    
    <para>
        Prior to version 3.0.25, Resteasy passes both methods to step 3. In fact, passing both methods might be considered
        preferable, since, if the request verb is POST, no matching method will be found. In fact, the matching
        algorithm is changed in the specification of JAX-RS 2.1 so that it passes all matching resource methods
        to step 3. However, Resteasy 3.0.x adheres to JAX-RS 2.0, and the bug is fixed in release 3.0.25.
    </para>
    
    <para>
        In order to make the older, if incorrect, behavior available, a context-param configuration switch, 
        "resteasy.loose.step2.request.matching", is introduced in version 3.0.26.Final. It defaults to "false",
        but, if it is set to "true", the older, looser behavior is enabled.
    </para>
</sect1>
<sect1>
    <title>Migrating to 3.0.17</title>
    <itemizedlist>
        <listitem>
        Module resteasy-spring is now included in the Resteasy distribution zip file. For more information see 
        <ulink url="https://issues.jboss.org/browse/RESTEASY-1354">https://issues.jboss.org/browse/RESTEASY-1354</ulink>.
        </listitem>
        <listitem>
        Resteasy client proxies now support an <methodname>as()</methodname> method for casting to subinterfaces.
        For more information see 
        <ulink url="https://issues.jboss.org/browse/RESTEASY-1332">https://issues.jboss.org/browse/RESTEASY-1332</ulink>.
        </listitem>
        <listitem>
        <classname>org.jboss.resteasy.plugins.server.netty.NettyJaxrsServer</classname> in module resteasy-netty4
        can now be configured to close idle connections.  For more information see 
        <ulink url="https://issues.jboss.org/browse/RESTEASY-1325">https://issues.jboss.org/browse/RESTEASY-1325</ulink>.
        </listitem>
        <listitem>
        Resteasy Spring integration now includes a Spring Boot Starter. For more information see
        <ulink url="https://issues.jboss.org/browse/RESTEASY-1305">https://issues.jboss.org/browse/RESTEASY-1305</ulink>.
        </listitem>
        <listitem>
        resteasy-wadl now supports subresource locators. For more information see
        <ulink url="https://issues.jboss.org/browse/RESTEASY-1297">https://issues.jboss.org/browse/RESTEASY-1297</ulink>.
        </listitem>
        <listitem>
        Resteasy has a new builtin producer that implements <classname>MessageBodyWriter&lt;Number&gt;</classname>. For more information see
        <ulink url="https://issues.jboss.org/browse/RESTEASY-1282">https://issues.jboss.org/browse/RESTEASY-1282</ulink>.
        </listitem>
        <listitem>
        Links can be added manually to <classname>org.jboss.resteasy.Links.RESTServiceDiscovery</classname> in resteasy-links module.
        See <ulink url="https://issues.jboss.org/browse/RESTEASY-833">https://issues.jboss.org/browse/RESTEASY-833</ulink> for more information. 
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0.13 to 3.0.14</title>
    <itemizedlist>
        <listitem>
        Resteasy introduces a <classname>@QueryParam</classname> annotation which allows capturing the name of
        a query parameter. See <ulink url="https://issues.jboss.org/browse/RESTEASY-715">https://issues.jboss.org/browse/RESTEASY-715</ulink>
        for more information.
        </listitem>
        <listitem>Resteasy now supports WADL. See <xref linkend="WADL"/> for more information. Also see
        <ulink url="https://issues.jboss.org/browse/RESTEASY-166">https://issues.jboss.org/browse/RESTEASY-166</ulink>. 
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0.12 to 3.0.13</title>
    <itemizedlist>
        <listitem>Resteasy 3 log messages and exceptions are now internationalized. See
<xref linkend="I18N"/> for more information. Also see 
<ulink url="https://issues.jboss.org/browse/RESTEASY-1224">https://issues.jboss.org/browse/RESTEASY-1224</ulink>. 
        </listitem>
        <listitem><literallayout><classname>org.jboss.resteasy.client.jaxrs.ResteasyClientBuilder</classname> has a new method,
<methodname>asyncExecutor(ExecutorService asyncExecutor, boolean cleanupExecutor)</methodname>, with a new
second parameter which tells the <classname>Client</classname> to shut down the Executor upon closing. See
<ulink url="https://issues.jboss.org/browse/RESTEASY-1181">https://issues.jboss.org/browse/RESTEASY-1181</ulink> for more information. 
</literallayout>
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating to 3.0.12</title>
    <itemizedlist>
        <listitem>
<methodname>org.jboss.resteasy.client.jaxrs.ResteasyClient.property()</methodname> will now
remove a property when the value is set to null. See
<ulink url="https://issues.jboss.org/browse/RESTEASY-1184">https://issues.jboss.org/browse/RESTEASY-1184</ulink> for more information.
</listitem>
        <listitem>
<literallayout><classname>org.jboss.resteasy.plugins.server.netty.NettyJaxrsServer</classname> in module resteasy-netty4
has a new method, <methodname>setHttpChannelHandlers()</methodname>, that allows adding channel handlers that are 
processed after the HTTP handlers. See
<ulink url="https://issues.jboss.org/browse/RESTEASY-1171">https://issues.jboss.org/browse/RESTEASY-1171</ulink> for more information. 
</literallayout>       
        </listitem>
        <listitem><literallayout><classname>org.jboss.resteasy.api.validation.ResteasyViolationException</classname> is now a subclass of 
<classname>javax.validation.ConstraintViolationException</classname> instead of
<classname>javax.validation.ValidationException</classname>. Now, an <classname>ExceptionMapper</classname> for
<classname>ConstraintViolationException</classname> will catch <classname>ResteasyViolationException</classname>s.
See <ulink url="https://issues.jboss.org/browse/RESTEASY-1137">https://issues.jboss.org/browse/RESTEASY-1137</ulink> for more information.</literallayout>
        </listitem>
        <listitem><literallayout>There is a new context parameter, "resteasy.buffer.exception.entity". See
<xref linkend="configuration_switches"/> for more information. Also, see
<ulink url="https://issues.jboss.org/browse/RESTEASY-981">https://issues.jboss.org/browse/RESTEASY-981</ulink>.
</literallayout>
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0.7 to 3.0.9</title>
    <itemizedlist>
        <listitem>
            You may need to upgrade your JDK to the latest 1.7.x or 1.8 releases if you are using JAXB.  There's some
            entity expansion security vulnerabilities that we had to patch and it seems the fix doesn't work on earlier
            versions of JDK 1.7.
        </listitem>
        <listitem>
            ContainerRequestContext.setRequestUri() method behavior has been changed to match the behavior of the JAXRS RI.
            The relative URI must be equal to are an extension of the base URI or it will not work. i.e.
<programlisting>
    context.setRequestUri(URI.create("https://foo.com/base"),
                          URI.create("https://foo.com/base/path"));  // legal
    context.setRequestUri(URI.create("https://foo.com/base"),
                          URI.create("/path"));  // "path" is ignored
    // if base uri is "http://foo.com/base"
    context.setRequestUri(URI.create("http://foo.com/base/path")); // legal
    context.setRequestUri(URI.create("/path")); // ignored
</programlisting>
        </listitem>
    </itemizedlist>
</sect1>

<sect1>
    <title>Migrating from 3.0.6 to 3.0.7</title>
    <itemizedlist>
        <listitem>
            Scannotation has been removed.  If you are not running within an application server you must use the
            ResteasyServletInitializer.  See docs for more detail.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0 to 3.0.4</title>
    <itemizedlist>
        <listitem>
            Servlet 3.0 deployments within standalone Tomcat or Jetty can now use the Resteasy <literal>ServletContainerInitializer</literal>.
            This allows tighter integration with Resteasy much like you have within JBoss/WildFly.  Check out 
            <xref linkend="Installation_Configuration"/> for more information.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0-beta-6 and 3.0-rc-1</title>
    <itemizedlist>
        <listitem>
            Form parameters are now read via a provider where earlier they were read from HttpServletRequest.getParameterMap().
            This may break deployments that depend on that behavior, i.e. if you have a servlet filter that calls that very method.
            For those situations I added the switch resteasy.use.container.form.params
        </listitem>
        <listitem>
            The JAX-RS TCK has become very strict with a ton more tests.  I can't remember them all, but there are a number
            of edge cases which earlier Resteasy releases misinterpreted.
        </listitem>
        <listitem>
            Any Failure exceptions in the SPI now have a corresponding JAX-RS 2.0 exception, so they have been deprecated
            Resteasy no longer uses these old SPI exceptions internally.  It now uses the JAX-RS 2.0 ones.
        </listitem>
        <listitem>
            A number of SPIs have changed.  Shouldn't be an issue for those of you who use Restasy as-is.  Specifically
            InjectorFactory and Registry have changed.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0-beta-5 and 3.0-beta-6</title>
    <itemizedlist>
        <listitem>
            The JAX-RS 2.0 TCK has become very very strict in terms of the matching algorithm.  Unfortunately, the matching
            algorithm is quite poor so there are a number of resource schemes that will no longer match.
            For example, resource classes are scanned for a best match, other are ignored in the match.
            Resource locators are not visited unless they are a best match over resource methods.  There is one config switch
            I added so that Resteasy will ignore the Spec defined class expression filtering step and instead match
            base on the full expressions of each JAX-RS method.  resteasy.wider.request.matching.  Set that to true
            and you will at least be able to avoid that.
        </listitem>
        <listitem>
            The JAX-RS TCK has become very strict with a ton more tests.  I can't remember them all, but there are a number
            of edge cases which earlier Resteasy releases misinterpreted.
        </listitem>
        <listitem>
            Any Failure exceptions in the SPI now have a corresponding JAX-RS 2.0 exception, so they have been deprecated
            Resteasy no longer uses these old SPI exceptions internally.  It now uses the JAX-RS 2.0 ones.
        </listitem>
        <listitem>
            A number of SPIs have changed.  Shouldn't be an issue for those of you who use Restasy as-is.  Specifically
            InjectorFactory and Registry have changed.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0-beta-4 and 3.0-beta-5</title>
    <itemizedlist>
        <listitem>
            JSONP support is no longer on by default.  A few users have complained that it is a security hole for their applications.
        </listitem>
        <listitem>
            A number of SPIs have changed.  Shouldn't be an issue for those of you who use Restasy as-is.  Specifically
            InjectorFactory and Registry have changed.
        </listitem>
    </itemizedlist>
</sect1>
    <sect1>
    <title>Migrating from 3.0-beta-2 and 3.0-beta-4</title>
    <itemizedlist>
        <listitem>
            The JAX-RS 2.0 class ClientFactory no longer exists.  It has been replaced with ClientBuilder.  You can
            still call newClient(), but there is now an additional builder interface.  Likewise, there is no
            ResteasyClientFactory.  We also have an extension to ClientBuilder called ResteasyClientBuilder.  So docs
            for more details.
        </listitem>
        <listitem>
            Filter execution and exception handling now matches the JAX-RS 2.0 spec.  Exceptions thrown from filters/interceptors
            can now be mapped if possible.  Responses returned from ExceptionMappers are now filtered.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 3.0-beta-1 and 3.0-beta-2</title>
    <itemizedlist>
        <listitem>
            The constructors for ResteasyClient class are no longer public.  You need to use the new ResteasyClientBuilder
            class.  One thing to note is that when a ResteasyClient is created by a builder, it no longer
            uses ResteasyProviderFactory.getInstance(), but instead instantiates a new one.  This will probably
            not effect most uses.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 2.x to 3.0-beta-1</title>
    <itemizedlist>
        <listitem>
            Resteasy manual client API, interceptors, StringConverters, StringParamterConverters, and Async HTTP APIs have all been
            deprecated and will be removed possibly in a later release.  There is now a JAX-RS 2.0 equivalent for each
            of these things.
        </listitem>
        <listitem>
            resteasy-crypto: SignedInput and SignedOutput must have a multipart/signed content type set either through
            the request or response object, or by annotation @Consumes/@Produces
        </listitem>
        <listitem>
            Server-side cache setup has been changed. Please see documentation for more details.
        </listitem>
        <listitem>
            The security filters for @RolesAllowed, etc. now return 403, Forbidden instead of 401.
        </listitem>
        <listitem>
            Most add() methods have been removed or made protected in ResteasyProviderFactory.  Use registerProvider() and registerProviderInstance() methods.
        </listitem>
        <listitem>
            The new JAX-RS 2.0 client-side filters will not be bound and run when you are using Resteasy's old client api.
        </listitem>
        <listitem>
            On server-side, all old Resteasy interceptors can run in parallel with the new JAX-RS 2.0 filter and interceptor
            interfaces.
        </listitem>
        <listitem>
            Some SPIs have changed.  This should not effect applications unless you are doing something you aren't supposed
            to do.
        </listitem>
        <listitem>
            The async tomcat and async jboss web modules have been removed.  If you are not running under Servlet 3.0,
            async HTTP server-side, will be faked and run synchronously in same request thread.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 2.3.2 to 2.3.3</title>
    <itemizedlist>
        <listitem>
            MultipartInput has a new close() method.  If you have a read body that is MultipartInput or one of
            its subinterfaces, then you must call this method to clean up any temporary files created.  Otherwise,
            these possible temporary files are deleted on GC or JDK shutdown.  Other multipart providers clean up
            automatically.
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 2.3.0 to 2.3.1</title>
    <itemizedlist>
        <listitem>
            sjsxp has been removed as a dependency for the Resteasy JAXB provider
        </listitem>
    </itemizedlist>
</sect1>
<sect1>
    <title>Migrating from 2.2.x to 2.3</title>
    <itemizedlist>
        <listitem>
            The Apache Abdera integration has been removed as a project.  If you want the integration back, please
            ping our dev lists or open a JIRA.
        </listitem>
        <listitem>
            Apache Http Client 4.x is now the default underlying client HTTP mechanism.  If there are problems, you
            can change the default mechanism by calling ClientRequest.setDefaultExecutorClass.
        </listitem>
        <listitem>
            ClientRequest no longer supports a shared default executor.  The 
            <code>createPerRequestInstance</code> parameter has been removed from
            <methodname>ClientRequest.setDefaultExecutorClass()</methodname>.
        </listitem>
        <listitem>
          resteasy-doseta module no longer exists.  It is now renamed to the resteasy-crypto module and also includes other things beyond doseta.
        </listitem>
        <listitem>
          Doseta work has be refactored a bit and may have broken backward compatibility.
        </listitem>
        <listitem>
          Jackson has been upgraded from 1.6.3 to 1.8.5.  Let me know if there are any issues.
        </listitem>
        <listitem>
          Form parameter processing behavior was modified because of RESTEASY-574.  If you are having problems with form paramater processing on Tomcat after
          this fix, please log a JIRA or contact the resteasy-developers email list.
        </listitem>
        <listitem>
	  Some subtle changes were made to ExceptionMapper handling so that you can write ExceptionMappers for any exception thrown internally or within
	  your application.  See JIRA Issue RESTEASY-595 for more details.  This may have an effect on existing applications that have an ExceptionMapper
	  for RuntimeException in that you will start to see Resteasy internal exceptions being caught by this kind of ExceptionMapper.
        </listitem>
        <listitem>
            The resteasy-cache (Server-side cache) will now invalidate the cache when a PUT, POST, or DELETE is done on a particular URI.
        </listitem>
    </itemizedlist>
</sect1>
<sect1 id="22_221">
    <title>Migrating from 2.2.0 to 2.2.1</title>
    <itemizedlist>
        <listitem>
	  Had to upgrade JAXB libs from 2.1.x to 2.2.4 as there was a concurrency bug in JAXB impl.
        </listitem>
    </itemizedlist>
</sect1>
<sect1 id="21_22">
    <title>Migrating from 2.1.x to 2.2</title>
    <itemizedlist>
        <listitem>
            ClientRequest.getHeaders() always returns a copy. It also converts the values within
            ClientRequest.getHeadersAsObjects() to string. If you
            add values to the map returned by getHeaders() nothing happen. Instead add values to the
            getHeadersAsObjects() map. This allows non-string header objects
            to propagate through the MessageBodyWriter interceptor and ClientExecutor interceptor chains.
        </listitem>
    </itemizedlist>
</sect1>
<sect1 id="20_21">
    <title>Migrating from 2.0.x to 2.1</title>
    <itemizedlist>
        <listitem>
            Slf4j is no longer the default logging mechanism for resteasy. Resteasy also no longer ships with SLF4J
            libraries. Please read the logging
            section in the Installation and Configuration chapter for more details.
        </listitem>
        <listitem>
            The constructor used to instantiate resource and provider classes is now picked based on the requirements of
            the JAX-RS specification.
            Specifically, the public constructor with the most arguments is picked. This behavior varies from previous
            versions where a no-arg
            constructor is preferred.
        </listitem>
    </itemizedlist>
</sect1>
<sect1 id="Migrating_to_Resteasy_12_20">
    <title>Migrating from 1.2.x to 2.0</title>

    <para>

        <itemizedlist>
            <listitem>
                TJWS has been forked to fix some bugs. The new groupId is org.jboss.resteasy, the artifactId is
                tjws. It will match the resteasy distribution version
            </listitem>
            <listitem>
                Please check out the JBoss 6 integration. It makes things a lot easier if you are deploying in that
                environment
            </listitem>
            <listitem>
                There is a new Filter implementation that is the preferred deployment mechanism. Servlet-based
                deployments are still supported, but it is suggested you use to using a FilterDispatcher. See
                documentation for more details.
            </listitem>
            <listitem>
                As per required by the spec List or array injection of empty values will return an empty collection
                or array, not null. I.e.
                (@QueryParam("name") List&lt;String&gt; param) param will be an empty List. Resteasy 1.2.x and
                earlier would return null.
            </listitem>
            <listitem>
                We have forked TJWS, the servlet container used for embedded testing into the group
                org.jboss.resteasy, with the artifact id of tjws. You will need
                to remove these dependencies from your maven builds if you are using any part of the resteasy
                embeddable server. TJWS has a number of startup/shutdown
                race conditions we had to fix in order to make unit testing viable.
            </listitem>
            <listitem>
                Spring integration compiled against Spring 3.0.3. It may or may not still work with 2.5.6 and lower
            </listitem>
        </itemizedlist>
    </para>
</sect1>
<sect1 id="migrating_1.2_1.2.1">
    <title>Migrating from 1.2.GA to 1.2.1.GA</title>
    <para>
        Methods @Deprecated within 1.2.GA have been removed. This is in the Client Framework and has to do with all
        references to Apache HTTP Client. You must now create an ClientExecutor if you want to manage your Apache
        HTTP Client
        sessions.
    </para>
</sect1>
<sect1 id="Migrating_to_Resteasy_1_1_1_2">
    <title>Migrating from 1.1 to 1.2</title>

    <para>

        <itemizedlist>
            <listitem>
                The resteasy-maven-import artifact has been renamed to resteasy-bom
            </listitem>
            <listitem>
                Jettison and Fastinfoset have been broken out of the resteasy-jaxb-provider maven module. You will
                now need to include resteasy-jettison-provider or resteasy-fastinfoset-provider if you use either
                of these libraries.
            </listitem>
            <listitem>
                The constructors for ClientRequest that have a HttpClient parameter (Apache Http Client 3.1 API) are
                now deprecated. They will be removed in the final release of 1.2. You must create a Apache hTTP
                Client Executor and pass it in as a parameter if you want to re-use existing Apache HttpClient
                sessions or do any special configuration. The same is true for the ProxyFactoyr methods.
            </listitem>
            <!--
            <listitem>
                Apache HttpClient 4.0 is now the default client used for our ClientRequest and ProxyFactory APIs.  Version 3.1 of this library is still support.  Just allocate an executor for that instead.  Or you can set the default one used by modifying the static field ClientRequest.defaultExecutorClass.
            </listitem>
            -->
            <listitem>
                Apache HttpClient 4.0 support is available if you want to use it. I've had some trouble with it so
                it is not the default implementation yet for the client framework.
            </listitem>
            <listitem>
                It is no longer required to call RegisterBuiltin.register() to initialize the set of providers. Too
                many users forgot to do this (include myself!). You can turn this off by calling the static method
                ResteasyProviderFactory.setRegisterBuiltinByDefault(false)
            </listitem>
            <listitem>
                The Embedded Container's API has changed to use org.jboss.resteasy.spi.ResteasyDeployment. Please
                see embedded documentation for more details.
            </listitem>
        </itemizedlist>
    </para>
</sect1>
</chapter>
