GoogleCloudPlatform / appengine-java-standard

Google App Engine Standard Java runtime: Prod runtime, local devappserver, Cloud SDK Java components, GAE APIs, and GAE API emulators.

Google App Engine Standard Environment Source Code for Java 8, Java 11, Java 17, Java 21.

This repository contains the Java Source Code for Google App Engine standard environment, the production runtime, the AppEngine APIs, and the local SDK.

Prerequisites

Use a JDK8 environment, so it can build the Java8 GAE runtime.

jdk8, but using a JDK11 or JDK17 of JDK21 is also possible.

The shared code base is also used for GAE Java 11, Java 17 and Java 21 build and test targets, using GitHub actions:

• Java 17/21 Continuous Integration

Releases

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. On Maven Central, the released artifacts from the internal source repository are using the versions like 1.9.xx. The open source release mechanism used with this GitHub repository is using the version starting at 2.0.x. Soon we will stop entirely pushing internal 1.9.xx artifacts and encourage all App Engine customers to use the new artifacts built from the GitHub project.

Modules

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

App Engine Java APIs

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

• 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>2.0.26</version><!-- or later-->
      </dependency>
      <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1</version>
        <scope>provided</scope>
  </dependency>
  ...
  

• Maven Java 21 with Jarkata 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>2.0.26</version><!-- or later-->
      </dependency>
      <dependency>
        <groupId>javax.servlet</groupId>
         <artifactId>jakarta.servlet-api</artifactId>
        <version>6.0.0</version>
        <scope>provided</scope>
  </dependency>
  ...
  

• Java 21 with Jakarta or javax appengine-web.xml

  <?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>
  
    <!-- Add optionally:
    <system-properties>
      <property name="appengine.use.EE8" value="true"/>
  </system-properties>
  If you want to keep javax.servlet APIs and not jarkata.servlet by default
  -->
  </appengine-web-app>
  

• Public Java 21 Documentation
• How to upgrade to Java21

• 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 11 appengine-web.xml

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

App Engine Java Remote APIs

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 Jarkata EE10 web.xml

   <servlet>
     <display-name>Remote API Servlet</display-name>
     <servlet-name>RemoteApiServlet</servlet-name>
     <servlet-class>com.google.apphosting.utils.remoteapi.EE10RemoteApiServlet</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>2.0.26</version><!-- Or later-->
    </dependency>

User Visible Changes With Maven Builds

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>2.0.26</version><!-- Or later-->
    </dependency>

Local Unit Testing for Java 8, 11, 17, 21

• Code Sample

• Latest javadoc.io Javadocs from this repository

  • Maven pom.xml

    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-testing</artifactId>
       <version>2.0.26</version><!-- Or later-->
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-api-stubs</artifactId>
       <version>2.0.26</version><!-- Or later-->
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-tools-sdk</artifactId>
       <version>2.0.26</version><!-- Or later-->
      <scope>test</scope>
    </dependency>

App Engine Java local development implementation of the APIs

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

App Engine Java various local development utilities and devappserver

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)

App Engine Java production runtime execution environment

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

Default entrypoint used by Java11, Java17 and Java21

The Java 11, Java 17 and 21 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 -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

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 to open some necessary JDK APIs.

Entry Point Features

The entry point for the Java 11, Java 17, 21 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:

Env Var	Description	Type	Default
CPROF_ENABLE	Stackdriver Profiler	boolean	false
GAE_MEMORY_MB	Available memory	size	Set by GAE or /proc/meminfo-400M
HEAP_SIZE_RATIO	Memory for the heap	percent	80
HEAP_SIZE_MB	Available heap	size	${HEAP_SIZE_RATIO}% of ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS	JVM heap args	JVM args	-Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS	JVM GC args	JVM args	-XX:+UseG1GC plus configuration
JAVA_USER_OPTS	JVM other args	JVM args
JAVA_OPTS	JVM args	JVM args	See below

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>

Contributing

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.