The Java runtime

The Java runtime is the software stack responsible for installing your application code and dependencies, and then running that application in the flexible environment.

  • Version 11 and later are built using buildpacks, which requires you to choose an operating system in your app.yaml file. For example, to use Java 21, you must specify Ubuntu 22 as the operating system.

  • The Java 8 / Jetty 9 runtime provides OpenJDK 8 and Eclipse Jetty 9 with support for the Java Servlet 3.1 Specification. The Jetty image inherits from the OpenJDK image.

For the full list of supported Java versions, and their corresponding Ubuntu version, see the Runtime support schedule.

Prerequisites

To use the Java runtime:

  • You must install gcloud CLI version 420.0.0 or later. You can update your CLI tooling by running the gcloud components update command. To view your installed version, you can run the gcloud version command.

  • To deploy using Maven, you will need to add the App Engine Maven Plugin to your pom.xml:

    <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>2.7.0</version>
    </plugin>

    Other options for deploying include the gcloud app deploy command or the App Engine Gradle plugin.

Organizing your files

Your source tree should look like this:

MyDir/
  [pom.xml]
  [build.gradle]
  [index.yaml]
  [cron.yaml]
  [dispatch.yaml]
  src/main/
    appengine/
      app.yaml
    docker/
      [Dockerfile]
    java/
      com.example.mycode/
        MyCode.java
    webapp/
      [index.html]
      [jsp.jsp]
      WEB-INF/
        [web.xml]

Choose a Java version

New runtime versions

For Java runtime version 11 and later, you must include the runtime_config and operating_system settings in your app.yaml file to specify an operating system.

Optionally, you can specify a runtime version by including the runtime_version setting in your app.yaml file. By default, the latest Java version is used if the runtime_version setting is not specified.

Examples

  • To specify Java 21 on Ubuntu 22:

    runtime: java
    env: flex
    
    runtime_config:
        operating_system: "ubuntu22"
        runtime_version: "21"
    
  • To specify the latest supported Java version on Ubuntu 22:

      runtime: java
      env: flex
    
      runtime_config:
          operating_system: "ubuntu22"
    

Previous runtime versions

For Java 8, specify runtime_config and jdk settings in your app.yaml file.

Java 8 supports:

  • The Eclipse Jetty 9 runtime and runs Jetty 9 using Servlet 3.1.
  • Your own server code that listens on port 8080 as part of your application. This feature enables you to use microservice frameworks like SparkJava and Spring-Boot.

Examples

  • Specifying Jetty version 9 (default / optional):

      runtime_config:
        jdk: openjdk8
        server: jetty9
    
  • Specifying Java version 8:

      runtime_config:
        jdk: openjdk8
    
  • Sample app.yaml for Java 8:

    runtime: java
    env: flex
    
    handlers:
    - url: /.*
      script: this field is required, but ignored

See pom.xml for configuring Maven and build.gradle for configuring Gradle.

Optional files

These configuration files are optional:

Place these files at the top level of MyDir. If you use any these files, you must deploy them separately with the gcloud app deploy command.

web.xml is optional and only needed if you are not using Servlet 3.x annotations.

You can place static web content, as well as your JavaServer pages, in your webapp/ directory. Jetty 9, which the App Engine flexible environment uses as its Servlet container, uses Apache Jasper as the default JSP implementation and includes JSTL taglibs.

The Dockerfile file is optional and used to customize the Java runtime.

Enabling gzip compression

The gzip handler is bundled with Jetty but not activated by default. To activate this module, set the environment variable, JETTY_MODULES_ENABLE=gzip, in the app.yaml file:

env_variables:
  JETTY_MODULES_ENABLE: 'gzip'

Using Quickstart

Jetty can speed up the start time of your application by pre-scanning its content and generating configuration files. If you are using an extended image you can activate quickstart by executing /scripts/jetty/quickstart.sh in your Dockerfile, after the application WAR is added.

Environment variables

You can set the following optional environment variables that are specific to the Java 8/Jetty 9 runtime. You can set OpenJDK 8 environment variables as well.

To set environment variables, use the env_variables key in the app.yaml file.

Env Var Maven Prop Value/Comment
JETTY_PROPERTIES Comma separated list of name=value pairs appended to $JETTY_ARGS
JETTY_MODULES_ENABLE Comma separated list of modules to enable by appending to $JETTY_ARGS
JETTY_MODULES_DISABLE Comma separated list of modules to disable by removing from $JETTY_BASE/start.d
JETTY_ARGS Arguments passed to jetty's start.jar. Any arguments used for custom jetty configuration should be passed here.
JAVA_OPTS JVM runtime arguments

Enhanced Cloud Logging (Beta)

When running on the App Engine flex environment, you can configure Java Util Logging to send logs to Cloud Logging by setting the JETTY_ARGS environment variable. For example:

 env_variables:
   JETTY_ARGS: -Djava.util.logging.config.file=WEB-INF/logging.properties

You must provide a logging.properties file that configures a LoggingHandler as follows:

handlers=com.google.cloud.logging.LoggingHandler

# Optional configuration
.level=INFO
com.google.cloud.logging.LoggingHandler.level=FINE
com.google.cloud.logging.LoggingHandler.log=gae_app.log
com.google.cloud.logging.LoggingHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=%3$s: %5$s%6$s

Local testing

When testing in your local environment, you may use emulated Google Cloud services, rather than remote Google Cloud services. You can use the following emulators:

Use the gcloud command to start them before you run your app:

gcloud beta emulators datastore start
gcloud beta emulators pubsub start
gcloud beta emulators bigtable start

Maven

Add these lines in your maven pom.xml file to add the Jetty 9 Maven Plugin:

<plugin>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-maven-plugin</artifactId>
  <version>9.4.2.v20170220</version>
</plugin>

To run your app locally, use the Maven command:

mvn jetty:run-exploded

Gradle

Follow the Creating a new Gradle project instructions to add the Gretty Gradle plugin to your build.gradle, and use the command:

gradle jettyRun

Deploying your app

To initialize the Google Cloud CLI, run:

gcloud init

After completing the configurations, you can use the Google Cloud CLI to deploy this directory containing the app.yaml and WAR files using:

gcloud app deploy app.yaml

If you are using any of the optional configuration files (index.yaml, cron.yaml, and dispatch.yaml) deploy them separately with the gcloud command. For example:

gcloud app deploy cron.yaml

Maven

Use Maven to deploy your app:

mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

Replace PROJECT_ID with the ID of your Google Cloud project. If your pom.xml file already specifies your project ID, you don't need to include the -Dapp.deploy.projectId property in the command you run.

Gradle

Use Gradle to deploy your app:

gradle appengineDeploy

Customizing the Java 8 / Jetty 9 runtime

You don't need a Dockerfile to deploy your app into the Java 8/Jetty 9 runtime. If your app requires additional configuration, you can explicitly provide a Dockerfile to customize the Java runtime. The Dockerfile must include the base image. You can add additional directives to the Dockerfile to customize the Java runtime. See Building custom runtimes.

In this case, your-application.war is the name of the built WAR file in your target/ directory (maven), or build/staged-app/ (gradle).