Upgrade an existing application

Java 25 (preview, EE 11)

To use Java 25 (preview) on Enterprise Edition 11 (EE 11), follow these steps:

1. Change the version number in your web.xml configuration file to version=6.1. 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_1.xsd"
         version="6.1">
         ...
       </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>java25</runtime>
       <system-properties>
         <property name="appengine.use.EE11" value="true"/>
       </system-properties>
       <app-engine-apis>true</app-engine-apis>
   </appengine-web-app>
   

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

Java 21 (EE 10)

To use Java 21 on Enterprise Edition 10 (EE 10), follow these steps:

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.

Java 17 and later (EE 8)

Use javax.servlet.* APIs on Java EE 8 without major application configuration changes. EE 8 offers backward compatibility for Java EE 6 and later.

To run your applications on Java EE 8, 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>java17</runtime>
      <system-properties>
        <property name="appengine.use.EE8" value="true"/>
      </system-properties>
      <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>

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