Building Blocks

I recently moved one of my applications to Google AppEngine. What I found missing was an explanatory tutorial to get started. As I mostly work with C#, I kept running into issues simply because I wasn’t too familiar with the technologies used.

Thus I’m writing this easy to follow all-steps-included tutorial, to help people whom are in a similar position to quickly get started developing with Grails for Google AppEngine.

This tutorial will take you through setting up a simple Grails application running on Google AppEngine; using the app-engine and GORM-JPA plugins to Grails. If you run into trouble, I’ve added a trouble shooting section at the end.

First of make sure you have the latest version of the Google AppEngine SDK, and Grails 1.1.1 or better. If you want to deploy your application to Google AppEngine, make sure you have an active account.

I also added a Known Issues section at the end, it’s there to assist you if you run into trouble.

Lets get started.

Create a Grails Application

First create a Grails Application using the create-app command. For this tutorial we’re creating an application called AppEngineDemo; but the name is not important.

C:\Users\Morten\IdeaProjects>grails create-app
Welcome to Grails 1.1.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: c:\dev\grails-1.1.1

Base Directory: C:\Users\Morten\IdeaProjects
Running script c:\dev\grails-1.1.1\scripts\CreateApp_.groovy
Environment set to development
Application name not specified. Please enter:
AppEngineDemo

Install the App-Engine plugin

The app-engine plugin requires a environment variable to be set to the location in which the Google SDK is installed. I recommend you take a minute or two to read through the plugin information page. I’ll add some examples form running the installation on the command line.

Move to the newly created application and install the app-engine plugin to the application.

C:\Users\Morten\IdeaProjects>cd AppEngineDemo

C:\Users\Morten\IdeaProjects\AppEngineDemo>grails install-plugin app-engine
Welcome to Grails 1.1.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: c:\dev\grails-1.1.1

Base Directory: C:\Users\Morten\IdeaProjects\AppEngineDemo
Running script c:\dev\grails-1.1.1\scripts\InstallPlugin.groovy
Environment set to development
Reading remote plugin list ...
Reading remote plugin list ...
Plugin list out-of-date, retrieving..

During the installation the plugin will ask you which persistence provider you want to use. We want to use the GORM-JPA plugin so select JPA for persistence.

Do you want to use JPA or JDO for persistence? (jpa, jdo)
jpa

This will create a file called persistance.xml in your Grails conf directory. In this file we will specify which domain objects we can persist to the Google AppEngine data storage.

Install GORM-JPA plugin

The GORM-JPA plugin will allow us to use the convenient dynamic methods for persistence; for example save() or findby…()

It is a straight forward to install the plugin

C:\Users\Morten\IdeaProjects\AppEngineDemo>grails install-plugin gorm-jpa
Welcome to Grails 1.1.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: c:\dev\grails-1.1.1

Base Directory: C:\Users\Morten\IdeaProjects\AppEngineDemo
Running script c:\dev\grails-1.1.1\scripts\InstallPlugin.groovy
Environment set to development
Reading remote plugin list ...

Create a domain class

We want to create a domain class for the application, in this tutorial we will create a domain class called Note.

C:\Users\Morten\IdeaProjects\AppEngineDemo>grails create-domain-class
Welcome to Grails 1.1.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: c:\dev\grails-1.1.1

Base Directory: C:\Users\Morten\IdeaProjects\AppEngineDemo
Running script c:\dev\grails-1.1.1\scripts\CreateDomainClass.groovy
Environment set to development
Domain class name not specified. Please enter:
Note
Created DomainClass for Note
Created Tests for Note

Next we generate the necessary controllers and views for the Note domain class.

C:\Users\Morten\IdeaProjects\AppEngineDemo>grails generate-all Note
Welcome to Grails 1.1.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: c:\dev\grails-1.1.1

Base Directory: C:\Users\Morten\IdeaProjects\AppEngineDemo
Running script c:\dev\grails-1.1.1\scripts\GenerateAll.groovy
---
Generating views for domain class Note ...
Generating controller for domain class Note ...
Finished generation for domain class Note

Move the domain classes into a package

The storage platform used by Google AppEngine doesn’t allow you to have your persisted domain classes in the default package. Not to worry, this is also good practice. We move our Note domain class into the package called persisted.

package persisted;

import javax.persistence.*;
// import com.google.appengine.api.datastore.Key;

class Note implements Serializable {

 Long id

}

Note the green code line in the above code.

Might as well add some code while were at it. The complete code for the Note domain class should be the following:

package persisted;

import javax.persistence.*;
// import com.google.appengine.api.datastore.Key;

class Note implements Serializable {

 Long id

 String message
}

Update the domain class with annotations

Now we must specify that the Note class can be persisted, and how it will be persisted. This is done using JPA annotations.

You might have noticed the @Entity, @Id,  @GeneratedValue… lines in the above code. These are JPA annotations added by Grails when you created the domain class. Now we must specify one for our added Message property.

We just want to say that it should be persisted along with the class. For this we add the @Basic annotation above the line declaring the message property. This will tell the persistence layer that this property should be saved.

package persisted;

import javax.persistence.*;
// import com.google.appengine.api.datastore.Key;

@Entity
class Note implements Serializable {

 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 Long id

@Basic
 String message

}

A list of the JPA annotations and their usages can be found here.

Generate the views and controllers

Now it’s time to generate view and controllers for the Note class. This is done as normal, specifying which class to generate for.

C:\Users\Morten\IdeaProjects\AppEngineDemo>grails generate-all persisted.Note
Welcome to Grails 1.1.1 - http://grails.org/
Licensed under Apache Standard License 2.0
Grails home is set to: c:\dev\grails-1.1.1

Base Directory: C:\Users\Morten\IdeaProjects\AppEngineDemo
Running script c:\dev\grails-1.1.1\scripts\GenerateAll.groovy
Environment set to development
 [groovyc] Compiling 1 source file to C:\Users\Morten\.grails\1.1.1\projects\AppEngineDemo\classes
 [copy] Copying 1 file to C:\Users\Morten\.grails\1.1.1\projects\AppEngineDemo
 [groovyc] Compiling 1 source file to C:\Users\Morten\.grails\1.1.1\projects\AppEngineDemo\classes
 [copy] Copying 1 file to C:\Users\Morten\.grails\1.1.1\projects\AppEngineDemo
Generating views for domain class persisted.Note ...
Generating controller for domain class persisted.Note ...
Finished generation for domain class persisted.Note
C:\Users\Morten\IdeaProjects\AppEngineDemo>

Notice that I specified the package name for the class.

First time deployment to Google AppEngine

Create an application on Google AppEngine using Google’s AppEngine website. When you create your application you specify an name for it. You need to include this name in the grails-app/conf/config.groovy file in your application. Add the following line to the file:

google.appengine.application = "<your application name>"

To host your application on Google AppEngine you need to set the version to a number between 1-100. It has to be an integer, floats are not accepted.

then do the following:

grails set-version 1
grails app-engine package
$APPENGINE_HOME/bin/appcfg.sh update ./target/war

and now to deploy

grails app-engine deploy

Congratulations, your first, basic Google AppEngine application is now running.

Known Issues

Since Grails on Google AppEngine is pretty new, not to mention Java on Google AppEngine. There are still some issues to work through.

Staging dir not cleared

Before we start I just want to mention some known Issues. There is an issue where the staging dir is not removed, you have to delete this manually. You can find it under:

 <user directory>\.grails\1.1.1\projects\<projectname>\stage

the 1.1.1 is the version Grails your using. This causes issues if you install the ui-performance plugin.

Rendering JSON

There is also an issue with rendering JSON. Rendering JSON can cause access exceptions when rendering entities fetched using the GORM. Please see this blog post for details.

Update: I recentlly wrote this post on Fun times with JSON rendering. Containing more details about JSON Rendering.

Generating controllers

You can run into issues generating controllers and views for your domain classes. The current workaround as far as I know is to install the hibernate plugin, generate the views or controllers, then uninstall the hibernate plugin. You can see the details here.

Command Line too long on Windows machines

If your on a Windows machine you might run into a problem where you cannot enhance your classes (preparing them for storage on the GoogleAppEngine data store). The problem is that the command line when enhancing them becomes too long. You can find more details in my previous blog posts on the subject.

• Grails and Google AppEngine
• Grails and Google AppEngine on Windows

Saving Entities with constraints

If you add constraints to your classes you can run into issues where Google AppEngine will try to save the entity using the wrong class. More details in this blog post.

Recommended reading

Here is link to the open JIRA issues for the AppEngine plugin.

If you find any errors in this tutorial or have ideas to improve it, please let me know.

Hope it helps!