Migrating from Java 7 to Java 8 Runtime

This page describes how to migrate your existing App Engine app from the Java 7 runtime to the Java 8 runtime. Note that App Engine Java runtimes are based on OpenJDK.

Specifying the Java 8 runtime for your app

To run your app in the Java 8 runtime:

1. Add <runtime>java8</runtime> to your appengine-web.xml file:

   <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
     <runtime>java8</runtime>
     <threadsafe>true</threadsafe>
   </appengine-web-app>

2. Redeploy your app.

Migrating from unsupported services

Some deprecated services available to the Java 7 runtime are not supported by the Java 8 runtime. Google recommends that you migrate your application to the recommended alternatives and test your app in the Java 7 runtime with those changes prior to migrating to Java 8.

The following deprecated services are not available in the Java 8 runtime:

Repackaged classes will require new import paths on Java 8. For example, if your app used com.google.appengine.repackaged.com.google.common.base.Optional, you will need to import com.google.appengine.repackaged.com.google.common.base.$Optional, with $ prefixed to the class name.

Migrating free apps that use java.net.HttpURLConnection

If your app does not have billing enabled and makes HTTP(S) requests using the java.net.HttpURLConnection class or a Google client library that uses that class, it will cause runtime errors. To avoid this, set the <url-stream-handler> to urlfetch in your app's appengine-web.xml:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>

Alternatively, instead of specifying urlfetch, you can enable billing for your application and use the default native setting. Your app should not incur any increase in costs from running on Java 7. Note that if your app relies on the X-Appengine-Inbound-Appid HTTP header (used for Module-to-Module communication), urlfetch must be used.

Changing the default file encoding

App Engine has changed the default file encoding from US-ASCII in Java 7 to UTF-8 in Java 8. To change the default encoding back to US-ASCII in Java 8, add the following to your appengine-web.xml:

 <system-properties>
   <property name="appengine.file.encoding" value="US-ASCII"/>
 </system-properties>

Errors may occur if some characters are not in the ASCII set and your application makes certain assumptions, such as someString.getBytes().length == someString.length(). In US-ASCII encoding this is true because non ASCII characters get mapped to "?", but this is not necessarily true with UTF-8 encoding.

For example, if you print the hex bytes from calling Éamonn.getBytes(), with UTF-8 it will be: c3 89 61 6d 6f 6e 6e (Éamonn), whereas with US-ASCII you will get: 3f 61 6d 6f 6e 6e (?amonn) due to the different encoding value of É.

Taking full advantage of Java 8 runtime features

The following is a partial list of the advantages of migrating to the Java 8 runtime:

• Jetty 9 supports both Servlet 2.5 and 3.1 web applications, including servlet annotations.
• All standard Java classes are now available, and there is no class allowlist.
• The /tmp filesystem is writable - this takes up the app's RAM allocation.
• Network I/O can now be performed on any Java thread. App Engine API calls still require being on either a Request Thread or a thread created by the Thread Manager API.
• The full Java 8 language is now supported including the Stream API, Lambdas, and Date / Time API.