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 
     : 
      
     java VERSION 
     
     
    

    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 
     : 
      
     java VERSION 
     
     
    

    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 servlet:

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. Add the following system property in your appengine-web.xml file:

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

5. 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 17 or 21 on EE8

You can continue using javax.servlet.* APIs on Java EE8 without major application configuration changes, because EE8 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>  
<!--  
or  
java17  
-->  
<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"/>