docs/src/main/docbook/migration.xml

<?xml version="1.0"?>
<!--

    Copyright (c) 2012, 2024 Oracle and/or its affiliates. All rights reserved.

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License v. 2.0, which is available at
    http://www.eclipse.org/legal/epl-2.0.

    This Source Code may also be made available under the following Secondary
    Licenses when the conditions for such availability set forth in the
    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
    version 2 with the GNU Classpath Exception, which is available at
    https://www.gnu.org/software/classpath/license.html.

    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

-->

<!DOCTYPE chapter [<!ENTITY % ents SYSTEM "jersey.ent" > %ents;]>
<chapter xmlns="http://docbook.org/ns/docbook"
         version="5.0"
         xml:lang="en"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
                             http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
         xml:id="migration">
    <title>Migration Guide</title>

    <section xml:id="mig-4.0.0">
        <title>Migrating from Jersey 3.x to 4.0.x.</title>
        <section xml:id="mig-4.0.0-breaking-changes">
            <title>Breaking Changes</title>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            Jersey 4.x is implementation of Jakarta REST 4.0, part of Jakarta EE 11.
                            For APIs and implementations in Jakarta EE 11, JDK 17 minimum is required.
                            However, some modules may require higher versions of Java SE. See <xref linkend="se_compatibility"/>.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Jakarta REST 4.0 dropped classes bound to JAX-B, since JAX-B has been removed from Jakarta EE 11 Core
                            profile. These classes were <literal>jakarta.ws.rs.core.Link.JaxbLink</literal> and
                            <literal>jakarta.ws.rs.core.Link.JaxbAdapter</literal> along with related methods working with these
                            classes.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Some modules supporting obsolete libraries were dropped.
                            The Apache 4 HTTP Client supported by <literal>jersey-apache-connector</literal>
                            is replaced by <literal>jersey-apache5-connector</literal>, using the Apache 5 HTTP Client.
                        </para>
                        <para>
                            <literal>jersey-jetty11-connector</literal> based on Jetty 11 HTTP Client has been dropped, with
                            <literal>jersey-jetty-connector</literal> based on Jetty 12 HTTP Client as a replacement.
                        </para>
                        <para>The same with <literal>jersey-container-jetty11-http</literal> with <literal>jersey-container-jetty-http</literal>
                            atop Jetty 12 as a replacement.
                        </para>
                        <para>
                            <literal>jersey-container-simple-http</literal> module was removed without a replacement.
                        </para>
                    </listitem>
                    <listitem>
                        <para>Given JDK 17 does not allow reflection on JDK internal classes, it is no longer possible
                            to support additional HTTP methods with the default <literal>HttpUrlConnector</literal>, such as popular
                            HTTP Patch.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Jersey 4.x still uses HK2 as a main DI framework. However, in the future releases (5.x+), the main
                            DI container would be the CDI container. In CDI, it is not possible to register beans in the injection
                            container in runtime the way it is possible in HK2 using AbstractBinder; the
                            &jersey.common.internal.inject.AbstractBinder; is moved to the <literal>jersey-hk2</literal> package.
                            Also, a releated <literal>org.glassfish.jersey.internal.inject.Bindings</literal> class was moved
                            into the same package. A few internal <literal>Binding</literal> subclasses and related Jersey
                            most innate classes are hidden from public usage.
                            See Section <xref linkend="ioc"/>.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Jersey stopped providing jersey as a bundle, known as <literal>jaxrs-ri</literal>. Jersey jars used
                            in the bundle was only a subset of possibilities Jersey provides with a variety of modules each of
                            which handles an additional customer use-case. Some modules are not designed to be together on a
                            classpath with a module from the <literal>jaxrs-ri</literal> bundle and that has been leading to a confusion.
                        </para>
                        <para>
                            The <literal>jaxrs-ri</literal> bundle also contained third party libraries with a different licensing
                            than Jersey, which also led to a confusion about whole <literal>jaxrs-ri</literal> bundle and
                            Jersey itself license.
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </section>
        <section xml:id="mig-4.0.0-application-servers">
            <title>Application servers for Jersey</title>
            <para>
                Note that only a few servers support Jakarta EE 11 compatible Servlet API and they are tested with Jersey.
                Those are:
                <literal>GlassFish 8</literal>,
                <literal>Tomcat 11</literal>.
                The other containers will follow.
            </para>
        </section>
    </section>

</chapter>