Access legacy bundled services for Java 11/17

This page describes how to install and use the bundled services with the Java 11/17 runtime for App Engine standard environment. Your app can access the bundled services through the App Engine API JAR.

Before you begin

Installing the App Engine API JAR

To use legacy bundled services in your Java 11/17 app, you must use an appengine-web.xml to configure your app (instead of an app.yaml file). For example, add the following settings in your appengine-web.xml file:

Java 17

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

Java 11

<?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>

To specify the legacy bundled services as a dependency, add the following lines in your pom.xml file:

 <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.4</version> <!-- or later-->
  </dependency>

If your app uses a web.xml file, you must add the <app-engine-apis> element and set it to true:

  <app-engine-apis>true</app-engine-apis>

To deploy your Java 11/17 app, run the mvn appengine:deploy command, or the gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml command on a compiled and staged web application.

Default entrypoint used by Java 11/17

The Java 11/17 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 -agentpath:/opt/cdbg/cdbg_java_agent.so=--log_dir=/tmp,--alsologtostderr=true,--cdbg_extra_class_path=/workspace/WEB-INF/classes:/workspace/WEB-INF/lib -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/17 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 App Engine 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>

Migration considerations

You should be aware of the following considerations if you are migrating to the Java 11/17 runtimes and your app uses legacy bundled services:

  • To test the legacy bundled services functionality in your Java 11/17 app, you can use the local development server.
  • Unlike the Java 8 runtime, the Java 11/17 runtimes includes the JVM as part of the instance memory. If you see memory-related errors in the logs, consider increasing the instance class size in your appengine-web.xml file.
  • If your application is trying to call an API which is not enabled for the Java 11/17 runtimes, it will receive a com.google.apphosting.api.ApiProxy$FeatureNotEnabledException error.
  • All apps are assumed to be thread safe in the Java 11/17 runtimes. You must remove the threadsafe element in your app.yaml or appengine-web.xml file when upgrading to Java 11/17 runtimes.

Example (Datastore)

For an example of how to use Firestore in Datastore mode (Datastore), see the legacy bundled services for Java 11 code sample in GitHub.