You are viewing the documentation for Play 1. The documentation for Play 2 is here.

Google App Engine support

The GAE module enables Google App Engine support for your application. It wraps commons GAE services in play basic services whenever possible (Logging, Mail, Cache...) and expose directly other Google specifics services (User services, Datastore...)

Moreover, this module sets up a GAE development environment directly in the play development server, so you don’t need to develop directly in the Google App Engine SDK (but it’s supported too).

What is supported?

The application layout is totally standard.
Auto reload works as expected.
Logging is correctly dispatched to java.util.logging when the module is enabled.
tmp folder is disabled because you can’t write to the filesystem in GAE.
Direct datastore access is fully supported.
JPA support can be enabled but you still depends on GAE JPA limitations.
Cache is correctly wrapped to the GAE memcached instance.
Mail is correctly wrapped to the GAE mail service.
Users services is available with a ‘sign in’ page simulation in the development server.
You can still break out your application into several modules.
PROD mode is forced when the application is running on the GAE production environment.

Setting up the GAE module

Start to create a new application in the classical way.

# play new test-gae

Then edit the conf/application.conf file to enable the GAE module:

# Additional modules
# ~~~~~
# A module is another play! application. Add a line for each module you want
# to add to your application. Module paths are either absolutes or relative to
# the application root.
#
module.gae=${play.path}/modules/gae

Now you can start your application, and play will start a GAE development environment:

# play run test-gae
 
~        _            _ 
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/   
~
~ play! 1.0-stable5-localbuild, http://www.playframework.org
~
~ Ctrl+C to stop
~ 
11:37:02,228 INFO  ~ Starting /Volumes/Data/Desktop/test-gae
11:37:02,240 INFO  ~ Module gae is available (/Volumes/Data/Desktop/play/modules/gae)
11:37:02,350 WARN  ~ 
11:37:02,351 WARN  ~ Google App Engine module
11:37:02,351 WARN  ~ ~~~~~~~~~~~~~~~~~~~~~~~
11:37:02,351 WARN  ~ No Google App Engine environment found. Setting up a development environment
11:37:02,379 WARN  ~ Don't forget to define your GAE application id in the 'war/WEB-INF/appengine-web.xml' file
11:37:02,379 WARN  ~ 
11:37:02,380 WARN  ~ You're running play in DEV mode
11:37:02,381 INFO  ~ Application 'Test of GAE' is ready !
11:37:02,529 INFO  ~ Listening for HTTP on port 9000 ...
11:37:02,529 INFO  ~

A blank appengine-web.xml file has been created in the war/WEB-INF directory. Don’t forget to set up a correct GAE application id before running it into the GAE SDK.

Note

Content of the war directory will be merged during the war export command. It’s not specific to the GAE module.

Deployment

To deploy your application to Google’s cloud, you need to export your application as war
then upload it using the Google App Engine SDK:

# play war test-gae -o test-gae.war
# appcfg.sh update test-gae.war

Make sure to specify your GAE application id in the ‘war/WEB-INF/appengine-web.xml’ file.

About JPA

Play offers a cool abstraction of JPA through the JPASupport/Model classes. But when you use these classes on GAE a lot of problems occur. This is because the JPA support in GAE is very different of Hibernate + a relational database.

There are two reasons you would like use JPA on Google App Engine :

To be able to transparently move your application in/out of GAE
Because you already know the JPA API very well, and you want reuse this knowledge.

But these 2 reasons fail. The JPA support is so different in GAE that you just can’t use it in a transparent way. It will work only for a single simple entity without relations. But even with a simple relation, you’ll have to rely on special Google classes. And because the JPA support is very different,
you can’t do things the way you are used to.

That’s why our advice is to not use JPA on Google App Engine. If you really want to use JPA, you should avoid using the JPASupport/Model helpers and just rely on simple JPA examples that Google provides.

We provide an alternative persistence manager module called Siena. It’s a better match and your application code should be even simpler than if you used JPA.

Sample application

You can take a look at the samples-and-tests/lists-with-gae as a sample of a real Google App Engine application.

This app is available online at http://play-lists.appspot.com.