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 have App Engine run your application in the Java 8 runtime, add <runtime>java8</runtime> to your appengine-web.xml file and redeploy the app.

Migrating from services not supported by the Java 8 runtime

Some deprecated services available to the Java 7 runtime are not supported in 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:

Deprecated service Recommended alternative
Cloud Endpoints v1 Migrate to v2, the product has been renamed to Cloud Endpoints Frameworks. Note that this might require you to change your Web, Android, or iOS applications.
AppStats (appengine-api-labs jar) Migrate to Stackdriver Trace. The SDK generates an error for apps using the com.google.appengine.tools.AppstatsFilter class in the Java 8 runtime. Make sure you delete all references to AppstatsFilter from your web.xml.

Note that the App Engine API jar contained many repackaged classes such as Guava, which were not intended for customer use. If your app uses a repackaged class such as com.google.appengine.repackaged.com.google.common.base.Optional then it will not work when run on Java 8, because the repackaged class is now com.google.appengine.repackaged.com.google.common.base.$Optional, with $ prefixed to the class name. You should import and use the proper dependencies.

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, you must add a line to your appengine-web.xml file that sets set <url-stream-handler> to urlfetch:

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

If you don't make this change, you will get the runtime errors listed in the url-stream-handler documentation.

Alternatively, instead of specifying urlfetch per the above instructions, you could enable billing for your application and use the default native setting. Your app should not incur more costs than it did running on Java 7.

Changing the default file encoding

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

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

Issues may arise 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, suppose you print the hex bytes that result from calling Éamonn.getBytes(). With UTF-8 you will get this: c3 89 61 6d 6f 6e 6e (Éamonn), whereas with US-ASCII you will get this: 3f 61 6d 6f 6e 6e (?amonn). The value in UTF-8 is c3 89, which is the UTF-8 encoding of É, but in US-ASCII it is 3f. The remaining values are amonn, the same as in ASCII because ASCII values are encoded as themselves in UTF-8.

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 is now used and supports both Servlet 2.5 and 3.1 web applications including the use of servlet annotations.
  • There is no longer a java.lang.SecurityManager installed at startup, which means all Java standard classes are now available and there is no longer a whitelist.
  • The /tmp filesystem is writable - this comes out of the app's RAM allotment.
  • 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.

Send feedback about...

App Engine standard environment for Java