Upgrade an existing application

You must upgrade your applications to the latest supported runtime version to continue receiving security updates and be eligible for technical support.

The process of upgrading an existing app depends on the runtime version that your app currently uses:

  • Java 8: You must migrate your app to the latest supported Java version. Java 8 has reached end of support on January 31,2024. Your existing Java 8 applications will continue to run and receive traffic. However, you cannot deploy new or update existing applications that use runtimes after their end of support date.

  • Java second-generation runtimes (after end of support): To upgrade to a supported version of Java, do the following:

    • Update the app.yaml file by specifying a version of Java that you want your app to run. For example:

        runtime: javaVERSION
      

      Where VERSION is the MAJOR version number. For example, to use the latest Java version, Java 21, specify 21. For more information, see the Java runtime overview.

    • If you use legacy bundled services, you must upgrade your apps to run on either:

      • Java Enterprise Edition 10 (EE10 - default, recommended): Java EE10 does not support javax.servlet.* APIs and requires you to update your apps and third-party dependencies to use newer Java artifacts like the Jakarta namespace.

      • Java Enterprise Edition 8 (EE8): Java EE8 lets you use javax.servlet.* APIs, but you must make minor configuration changes to your appengine-web.xml file.

        See Upgrade to Java 21 for legacy bundled services for all options.

  • Java 17:

    App Engine supports this version. To continue to upgrade to the latest support version, do the following:

    • Update the app.yaml file by specifying a version of Java that you want your app to run. For example:

        runtime: javaVERSION
      

      Where VERSION is the MAJOR version number. For example, to use the latest Java version, Java 21, specify 21. For more information, see the Java runtime overview.

    • If you use legacy bundled services, you must upgrade your apps to run on either:

      • Java Enterprise Edition 10 (EE10 - default, recommended): Java EE10 does not support javax.servlet.* APIs and requires you to update your apps and third-party dependencies to use newer Java artifacts like the Jakarta namespace.

      • Java Enterprise Edition 8 (EE8): Java EE8 lets you use javax.servlet.* APIs, but you must make minor configuration changes to your appengine-web.xml file.

      See Upgrade to Java 21 for legacy bundled services for all options.

Upgrade to Java 21 for legacy bundled services

Java runtime compatibility

Refer to the following table to understand which Java versions are compatible with your versions of Jetty and servlet:

Enterprise Edition (EE) Jetty version Java version Servlet Compatibility
EE7 9.4 11 2.5 or 3.1
EE7 9.4 17 2.5 or 3.1
EE8 12 21 2.5 and later Java EE8 is backward compatible with Java EE6 and later. For more information, see Upgrade to Java 21 on EE8.
EE10 12 21 6.0 (recommended). Java 21 is configured to run EE10 by default. To use Java EE10, you must update your application servlets and dependencies to include the Jakarta namespace. For more information, see Upgrade Java 21 on EE10.

Upgrade to Java 21 on EE10

To use Java 21 on Enterprise Edition 10 (EE10), you must upgrade your application servlets and dependencies in your Maven and Gradle files to include the Jakarta namespace:

  1. Change the version number in your web.xml configuration file to version=6.0. For example:

        <web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
          version="6.0">
          ...
        </web-app>
    
  2. Rename your application servlets and dependencies from javax.servlet.* to jakarta.servlet.*:

         import jakarta.servlet.ServletException;
         import jakarta.servlet.annotation.WebServlet;
         import jakarta.servlet.http.Cookie;
         import jakarta.servlet.http.HttpServlet;
         import jakarta.servlet.http.HttpServletRequest;
         import jakarta.servlet.http.HttpServletResponse;
    
         @WebServlet(name = "viewer", urlPatterns = {"/view"})
         public class MyServlet extends HttpServlet {
        ......
    
  3. Update your remaining application third-party dependencies to newer Java artifacts depending on the Jakarta namespace.

  4. Optional: Java 21 includes support for virtual threads. To enable virtual threads, you add the appengine.use.virtualthreads property within the system-properties tag in your appengine-web.xml file.

Upgrade to Java 21 on EE8

You can continue using javax.servlet.* APIs on Java EE8 without major application configuration changes, because Jetty 12 offers backward compatibility for Java EE6 and later. To run your applications on Java EE8, you must declare a new system-properties tag in your appengine-web.xml file with the non-default app.engine.use.EE8 configuration:

   <?xml version="1.0" encoding="utf-8"?>
   <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java21</runtime>
      <system-properties>
        <property name="appengine.use.EE8" value="true"/>
      </system-properties>
      <app-engine-apis>true</app-engine-apis>
   </appengine-web-app>

Optional: Java 21 includes support for virtual threads. To enable virtual threads, you add the appengine.use.virtualthreads property within the system-properties tag. Example: <property name="appengine.use.virtualthreads" value="true"/>