<chapter id="doc">
    <title>Documentation Support</title>
    <para>There's a great javadoc engine that allows you to generate javadocs for JAX-RS and JAXB called<ulink
            url="http://www.lunatech-labs.com/open-source/jax-doclets">JAX-Doclet</ulink>. Follow the link for more
        details.
    </para>
</chapter>

<chapter id="Migration_from_older_versions">
<title>Migration from older versions</title>
<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>
