docs/src/main/docbook/migration.xml

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

    Copyright (c) 2012, 2023 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-3.0.0">
        <title>Migrating from Jersey 2.32+ to 3.0.x.</title>
        <section xml:id="mig-3.0.0-breaking-changes">
            <title>Breaking Changes</title>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            The most fundamental change in Jersey 3.0.0 and later is namespace change.
                            Since Jakarta EE 9 the <literal>jakarta.</literal> namespace is introduced as a replacement
                            for javax namespace from Java EE.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Some Jersey modules require higher versions of Java SE. See <xref linkend="se_compatibility"/>.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Examples and tests are reduced in quantity (so you probably will not find all those examples which were available
                            in the 2.32 version).
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            &jersey.server.ServerProperties.UNWRAP_COMPLETION_STAGE_IN_WRITER_ENABLE; is by default
                            <literal>true</literal>.
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </section>
        <section xml:id="mig-3.0.0-removed-deprecated">
            <title>Removed deprecated APIs</title>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            Jackson 1 support was removed.
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </section>
        <section xml:id="mig-3.0.0-application-servers">
            <title>Application servers for Jersey</title>
            <para>
                Note that only a few servers support Jakarta EE 9 compatible Servlet API and they are tested with Jersey.
                Those are:
                <literal>GlassFish 6</literal>,
                <literal>Grizzly 3</literal>,
                <literal>Jetty 11 (JDK 11+ required)</literal>,
                <literal>Payara 6</literal>, and
                <literal>Tomcat 10</literal>.
            </para>
        </section>
    </section>
    <section xml:id="mig-3.1.0">
        <title>Migrating from Jersey 3.0.x to &version;.</title>
        <section xml:id="mig-3.1.0-breaking-changes">
            <title>Breaking Changes</title>
            <para>
                <itemizedlist>
                    <listitem>
                        <para>
                            Jersey 3.1.0+ is the implementation of Jakarta RESTful WebServices 3.1, which is part of
                            Jakarta EE 10. Jakarta EE 10 defines the minimum JDK 11 requirement and hence Jersey no longer
                            supports JDK 8.
                        </para>
                        <para>
                            Some Jersey modules require higher versions of Java SE. See <xref linkend="se_compatibility"/>.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Since Jersey 3.1.0+ the <literal>getRequestHeader(String name)</literal> method of the
                            <literal>ClientRequest</literal> class returns NULL (instead of an empty List) in case if
                            the specified header does not exist.
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </section>
        <section xml:id="mig-3.1.0-application-path">
            <title>@ApplicationPath Annotation Support</title>
            <para>
                Jersey 3.1 supports <literal>@ApplicationPath</literal> annotation by every container, not only the
                <literal>Servlet</literal> container. This can affect tests, as well as deployments to containers
                where the annotation used to be ignored by previous versions of Jersey.
            </para>
        </section>
        <section xml:id="mig-3.1.4-jetty-modules">
            <title>Jetty Modules</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Jersey 3.0.x, and 3.1.0 - 3.1.3 Jetty modules (jersey-jetty-connector, jersey-container-jetty-http,
                        jersey-container-jetty-servlet, jersey-test-framework-provider-jetty) are based on Jetty 11,
                        which is Jakarta EE 9 related.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Jersey 3.1.4 modules use Jetty 12 which is Jakarta EE 10 related (as well as Jersey 3.1.x).
                        Jetty 12 dependencies use modules names different from Jetty 11.
                    </para>
                </listitem>
            </itemizedlist>
        </section>
        <section xml:id="mig-3.1.4">
            <title>Migrating from Jersey 3.1.3 to 3.1.4</title>
            <section xml:id="mig-3.1.4-jackson-changes">
                <title>Changes in Jackson</title>
                <para>
                    Jersey 3.1.4 starts to support Jackson 2.15 which comes with default limitations for the length of parsed text,
                    numbers, and nesting depth. Jersey keeps the Jackson default value, but it allows to override the maximum
                    length of parsed text using the &jersey.message.MessageProperties.JSON_MAX_STRING_LENGTH; property if needed.
                </para>
            </section>
        </section>
    </section>

</chapter>