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.11">
        <title>Migrating from Jersey 3.0.11 to 3.0.12</title>
        <section xml:id="mig-3.0.11-jackson-changes">
            <title>Changes in Jackson</title>
            <para>
                Jersey 3.0.12 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 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 &version; 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>
                        <para>
                            Due to required jakartification several modules where omitted (because of not satisfied dependencies).
                            Or require higher JDK (11+).
                        </para>
                        <para>
                            Spring for now is not supported.
                        </para>
                        <para>
                            Helidon connector for now is not supported.
                        </para>
                        <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>
                </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>
                    </listitem>
                    <listitem>
                        <para>
                            &jersey.server.ServerProperties.UNWRAP_COMPLETION_STAGE_IN_WRITER_ENABLE; is by default
                            <literal>true</literal>.
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </section>
    </section>

</chapter>