This repository contains the Java source code for Google App Engine standard environment, the production runtime, the App Engine APIs, and the local SDK.

jdk17, but using a JDK21 or JDK25 is also possible.

The shared codebase is also used for GAE Java 17, Java 21 and Java 25 build and test targets, using GitHub actions:

• Java 17/21/25 Continuous Integration

This repository is the open source mirror of the Google App Engine Java source code that was used to produce Maven artifacts and runtime jars. The open source release mechanism used with this GitHub repository is using the version starting at 3.0.x, compatible for Java 17 or above.

This repository is organized into several Maven modules. For a detailed description of each module, its dependencies, and how they relate to each other, see modules.md.

Orange items are public modules artifacts and yellow are internal ones. Modules ending with * are only used on the production server side.

Source code for all public APIs for com.google.appengine.api.* packages.

• Public Documentation
• Latest javadoc.io API Javadocs from this repository
• Javadocs
• Source Code
• Source Code for repackaged API jar

Note that some App Engine APIs such as Blobstore and Taskqueues provide classes that depend on servlet APIs. The base packages com.google.appengine.api.blobstore and com.google.appengine.api.taskqueue contain classes that use javax.servlet.* for EE6/EE8 compatibility. For EE10 and EE11 environments that use the jakarta.servlet.* namespace, use classes from com.google.appengine.api.blobstore.jakarta and com.google.appengine.api.taskqueue.jakarta packages. The packages com.google.appengine.api.blobstore.ee10 and com.google.appengine.api.taskqueue.ee10 are deprecated starting from version 3.0.0.

• Maven pom.xml

  <packaging>war</packaging><!-- Servlet 3.1 WAR packaging-->
  ...
  <dependencies>
      <dependency>
          <groupId>com.google.appengine</groupId>
          <artifactId>appengine-api-1.0-sdk</artifactId>
          <version>5.2.0</version> <!-- GAE latest -->
      </dependency>
      <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1</version>
        <scope>provided</scope>
  </dependency>
  ...
  

• Maven Java 21 with jakarta EE 10 support pom.xml

  <packaging>war</packaging><!-- Servlet 6.0 WAR packaging-->
  ...
  <dependencies>
      <dependency>
          <groupId>com.google.appengine</groupId>
          <artifactId>appengine-api-1.0-sdk</artifactId>
          <version>5.2.0</version> <!-- GAE latest -->
      </dependency>
      <dependency>
        <groupId>jakarta.servlet</groupId>
        <artifactId>jakarta.servlet-api</artifactId>
        <version>6.0.0</version>
        <scope>provided</scope>
      </dependency>
  ...
  

• Maven Java 25 with jakarta EE 11 support pom.xml (EE10 is not supported in Java25, EE11 is fully compatible with EE10)

  <packaging>war</packaging><!-- Servlet 6.1 WAR packaging-->
  ...
  <dependencies>
      <dependency>
          <groupId>com.google.appengine</groupId>
          <artifactId>appengine-api-1.0-sdk</artifactId>
          <version>5.2.0</version> <!-- GAE latest -->
      </dependency>
      <dependency>
        <groupId>jakarta.servlet</groupId>
        <artifactId>jakarta.servlet-api</artifactId>
        <version>6.1.0</version>
        <scope>provided</scope>
      </dependency>
  ...
  

• Java 21/25 with javax EE8 profile appengine-web.xml

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <runtime>java25</runtime> <-- or java21-->
    <app-engine-apis>true</app-engine-apis>
  
    <!-- Add optionally:
    <system-properties>
      <property name="appengine.use.EE8" value="true"/>
  </system-properties>
  If you want to keep javax.servlet APIs and not jakarta.servlet by default
  -->
  </appengine-web-app>
  

• Public Java 17/21/25 Documentation
• How to upgrade to Java21/25

• Java 17 appengine-web.xml

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <runtime>java17</runtime>
    <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>
  

• Java 21 appengine-web.xml (will default to EE10, but EE8 possible)

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

• Java 25 appengine-web.xml (will default to EE11, but EE8 possible)

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <runtime>java25</runtime>
    <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>
  

Source code for remote APIs for App Engine.

• Public Documentation
• Latest javadoc.io Javadocs from this repository
• Public Sample remote server
• Public Sample remote client
• Source Code

• Servlet web.xml

   <servlet>
     <display-name>Remote API Servlet</display-name>
     <servlet-name>RemoteApiServlet</servlet-name>
     <servlet-class>com.google.apphosting.utils.remoteapi.RemoteApiServlet</servlet-class>
     <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
     <servlet-name>RemoteApiServlet</servlet-name>
     <url-pattern>/remote_api</url-pattern>
   </servlet-mapping>

• Servlet jakarta EE10 and EE11 web.xml

   <servlet>
     <display-name>Remote API Servlet</display-name>
     <servlet-name>RemoteApiServlet</servlet-name>
     <servlet-class>com.google.apphosting.utils.remoteapi.JakartaRemoteApiServlet</servlet-class>
     <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
     <servlet-name>RemoteApiServlet</servlet-name>
     <url-pattern>/remote_api</url-pattern>
   </servlet-mapping>

• Maven javax and jakarta API pom.xml

    <dependency>
       <groupId>com.google.appengine</groupId>
       <artifactId>appengine-remote-api</artifactId>
       <version>5.2.0</version> <!-- GAE latest -->
    </dependency>

We moved com.google.appengine.api.memcache.stdimpl and its old dependency javax.cache from appengine-api-1.0-sdk.jar to a new jar appengine-api-legacy.jar.

• Latest javadoc.io Javadocs from this repository

  Users who depend on the moved classes will need to also include appengine-api-legacy.jar when they build/deploy. Separating these classes allows appengine-api-1.0-sdk users to choose any version of javax.cache rather than being constrained by an obsolete included version.

  • Maven pom.xml

    <dependency>
       <groupId>com.google.appengine</groupId>
       <artifactId>appengine-api-legacy.jar/artifactId>
       <version>5.2.0</version> <!-- GAE latest -->
    </dependency>

• Code Sample

• Latest javadoc.io Javadocs from this repository

  • Maven pom.xml

    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-testing</artifactId>
      <version>5.2.0</version> <!-- GAE latest -->
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-api-stubs</artifactId>
      <version>5.2.0</version> <!-- GAE latest -->
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-tools-sdk</artifactId>
      <version>5.2.0</version> <!-- GAE latest -->
      <scope>test</scope>
    </dependency>

Implementation of all the App Engine APIs for local environment (devappserver) and local testing of an application before deployment.

• Public Documentation
• Source Code
• Source Code for repackaged APIs stubs jar

Source code for the App Engine local dev application server and local utilities.

• Public Documentation
• Source Code for tools APIs (appcfg)
• Source Code for XML validator (appcfg)
• Source Code for local devappserver
• Source Code for shared utilities (appcfg)
• Source Code for shared utilities (config)

Source code for the App Engine production application server and utilities. It is based on the Jetty9.4 Web Server.

• Public Documentation
• Source Code for the runtime implementation
• Source Code for the Java Main
• End-to-End test Web Applications
• End-to-End tests
• Source Code for runtime utilities

The Java 17, Java 21 and 25 runtimes can benefit from extra user configuration when starting the JVM for web apps.

The default entrypoint used to boot the JVM is generated by App Engine Buildpacks. Essentially, it is equivalent to define this entrypoint in the appengine-web.xml file. For example:

java --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED --add-opens java.logging/java.util.logging=ALL-UNNAMED -showversion -Xms32M -Xmx204M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com.google.apphosting.runtime.JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime

For Java25, the base layer is in the builder image under /layers/google.java.appengine/java_runtime, so:

java --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED --add-opens java.logging/java.util.logging=ALL-UNNAMED -showversion -Xms32M -Xmx204M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags -Dclasspath.runtimebase=/layers/google.java.appengine/java_runtime -Djava.class.path=/layers/google.java.appengine/java_runtime/runtime-main.jar -Djava.library.path=/layers/google.java.appengine/java_runtime: com.google.apphosting.runtime.JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /layers/google.java.appengine/java_runtime

We do not recommend changing this default entrypoint as the memory settings are calculated based on the instance type (F1, F2, F4) and memory available.

By default, we use --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED to open some necessary JDK APIs.

The entry point for the Java 17, Java 21, 25 runtimes can be customized with user-defined environment variables added in the appengine-web.xml configuration file.

The following table indicates the environment variables that can be used to enable/disable/configure features, and the default values if they are not set:

If not explicitly set, JAVA_OPTS is defaulted to:

JAVA_OPTS:=-showversion \
           ${DBG_AGENT} \
           ${PROFILER_AGENT} \
           ${JAVA_HEAP_OPTS} \
           ${JAVA_GC_OPTS} \
           ${JAVA_USER_OPTS}

When CPROF_ENABLE is true, the default entrypoint adds the PROFILER_AGENT as:

-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr

For example, if your application code needs more -add-opens flags, you can use the JAVA_USER_OPTS environment variable defined in the appengine-web.xml file:

  <env-variables>
     <env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
   </env-variables>

Note:

• Only one of appengine.use.EE8, appengine.use.EE10, or appengine.use.EE11 can be set to true at a time.
• Flags can be set in WEB-INF/appengine-web.xml or via Java system properties (e.g., -Dappengine.use.EE10=true). System properties override appengine-web.xml.
• EE6 = Servlet 3.1 (javax.*), EE8 = Servlet 4.0 (javax.*), EE10 = Servlet 5.0 (jakarta.*), EE11 = Servlet 6.0 (jakarta.*).
• Jetty 12.1 should be fully backward compatible with Jetty 12.0 and EE11 version should also be backward compatible with EE10.
• EE8 should also be backward compatible with EE6.

Note: * We are gradually rolling out an update that switches Java 17 applications from Jetty 9.4 to Jetty 12.0 with EE8. If your application has been updated, you will see the following message in your logs:

AppEngine runtime configuration: runtimeId=java17, with Jetty 12, with HTTP Connector, appengine.use.EE8=true.

Check out the contributing guide to learn how you can report issues and help make changes.

Always be sure to follow the Code of Conduct.