Your first Play! – GAE – Siena application: Tutorial with Example

Convention over configuration has became a buzz word these days. It is a software design paradigm which seeks to decrease the number of decisions that developers need to make, gaining simplicity, but not necessarily losing flexibility. More and more web frameworks are using this approach and making web development simple. Ruby on rails, DJango, Grails, CakePHP, ASP .NET, Apache Wicket etc are few in top demand these days.

What’s Play!?

One of the newest one is Play! framework. Play is heavily inspired by Ruby on Rails and Django. A developer familiar with any of these frameworks will feel at home. Play leverages the power of Java to build web applications in an environment that is not Java Enterprise Edition-centric. By lifting away the Java EE constraints, Play provides developers with an easy-to-develop and elegant stack aimed at productivity.

I have worked in CakePHP and I am a big fan of it. I believe Play! is bringing the same experience of fast web application development to the Java world, right from hello world baby steps to create a full production ready application and writing tests.

When you visit Play!’s overview webpage on their site, the very first line will surely catch your attention.

The Play framework is a clean alternative to bloated Enterprise Java stacks. It focuses on developer productivity and targets RESTful architectures. Play is a perfect companion to agile software development.

Although the words “bloated Enterprise Java stacks” may offend many Java developers who are very used to work with Spring MVC, Struts of JavaServer Faces; I think its more of less correct and many of us already feels so working for years now in Spring / Struts and realizing how much boiler plate code is being pushed into system and how complex things became over period of time.

What I like most about Play! framework is the flexibility of this new framework and how easy it makes the life of developer. The application development becomes a piece of cake (like most CakePHP developers will feel). And the best part is all this you can do with Java without switching your favorite language and shifting to other like Rube or PHP.

Highlights of Play! framework

Let us see few differences of Play! from other Java frameworks (Courtesy Wiki):

Play is fully RESTful – there is no Java EE session per connection. This makes Play more outwardly-scalable than many other frameworks.

No configuration: download, unpack and develop – it’s that simple.

Easy round trips: no need to deploy to an application server, just edit the code and press the refresh button on the browser.

Integrated unit testing: unit testing is at the core of Play!

Elegant API: rarely will a developer need to import any third party library – Play comes with all the typical stuff built-in.

CRUD module: easily build administration UI with little code.

Play is a web framework: it is language agnostic and currently supports Java and Scala.

Modular architecture

Your first Play! application

Hello world in Play! is straight forward. I will not spend much time in describing steps for installing and configuring Play!. On its homepage, Play! framework developer Guillaume Bort has made this wonderful getting started screencast which you can follow to create your very first Play! application.

Few points I would like to highlight here is:

Play is a real “Share nothing” system. Ready for REST, it is easily scaled by running multiple instances of the same application on several servers.

Play! loads the code dynamically. Just fix the bug in Java file and hit reload and voila, the change will get reflected instantly on webpage. No need to go through those sluggish rebuild / deployment / server restart.

Play! comes with a very efficient template system. The template system is based on Groovy as an expression language. It provides template inheritence, includes and tags.

A fully functional stack of modules are available in Play!. Provides integration with Hibernate, OpenID, Memcached… And a plugin system to create your own customize plugin or include one from hundreds of freely available ones.

Error discovery is very easy with Play!. When an error occurs, play shows you the source code and the exact line containing the problem. Even in templates.

Your first Play! – GAE – Siena application

For this tutorial, I have chosen a little complex example which we develop in Play! and deploy on Google App Engine (GAE). The GAE offers fast development and deployment; simple administration, with no need to worry about hardware, patches or backups; and effortless scalability. The Google app engine does not support SQL or RDBMS. The App Engine datastore provides robust, scalable storage for your web application, with an emphasis on read and query performance. An application creates entities, with data values stored as properties of an entity. The app can perform queries over entities. All queries are pre-indexed for fast results over very large data sets.

Our demo application called eazyBookmark is already running on Google App engine. This is a Bookmark application where user can login and save their bookmarks. Click below image to visit online demo.

The above Hello World video shows in depth how to install and use Play and create your first application.

Adding Google App Engine (GAE) and Siena module to Play!

We need two modules for our eazybookmark application. One is Google App engine (GAE) and another one is Siena. You can install these modules by running following command with Play!.

C:\Play> play install gae
..
..
C:\Play> play install siena

The above commands will install latest version of these modules. If you are behind proxy than the above command may fails. Currently there is no way of setting up proxy with Play! (v1.1) so you can manually download gae and siena from its homepage and copy them in /modules directory of your Play!.

Once the modules are installed successfully, you can add following lines in eazybookmark apps /conf/application.conf file.

You may want to restart the Play application to reflect the changes of the modules.

Once the application is restarted, the GAE module creates /war/WEB-INF/appengine-web.xml file. You need to update this file and add the application id of GAE. In our case we will have following data.
File: /war/WEB-INF/appengine-web.xml

You may want to replace eazybookmark with your own GAE Application ID.

Play! and Siena models

Let us first review the model classes we going to use for our application. We will have four model classes.

User – This is a User model. All user related information such as email, name, etc will get stored here.

Link – This is Link model. All links related information such as URL, title, description etc will get stored here.

Tag – This is Tag model. All the tags related information such as tagname etc will get stored here.

LinkTag – This is a mapping model which maps Links with Tag. In Siena to create Many to Many relationship we need to create three classes. This class maps Link and Tag and add a many to many relationship to these entities.

The Link model class is similar to User. It has its own attributes such as url, title, description etc. Also note that Link model has few methods like findById(), findTagsByLink(), addTag(), addTagsFromCSV() etc. These methods are used from the controller to manipulate the link data. The Link has a many to many relationship with Tag. One link can have multiple tags attached to it.

The Tag model has one attribute tag name. This can be anything like travel, leisure, technology, news etc. Also note that each tag has one to one mapping with User. This is defined by @Index("user_index") annotation with object User. The Tag has usual methods findById, findByName, findByUser, findOrCreateByName etc which is used from controller to manipulate the Tag data.

The LinkTag model links the models Link and Tag. It adds the Many-to-many relationship between these models. We have few useful methods like findByLink, findByTag to get the list of relationship.

The Play! Controllers

The controller in Play! framework handles all the request / response between client and web server. It is a plain Java class which extends Controller class of Play!. In our application we will use two controller classes: Application and Profile. We will also have a helper class called Auth which has few useful methods to determine is a user is logged in, or to get email address of logged in user. This class invoke GAE module to get the authentication details and route user to Google page for authentication.

Note that above Auth class is not part of controller (We haven’t extended it with Controller). It is just a utility class that we can use from other controllers to access user information. You may want to create your own package utils and keep this class there. For sake of simplicity, I am keeping this in controllers package.

Check the Application controller which is the entry point to our application. The index() method will be called whenever user request homepage /. In index() method we are checking if user is logged in. If not, then we show her a Login page using render() method. This method renders the default view of this action. We will see this view later in our example. Also note that if user is authenticated, we redirect it to Profile.index action. If user has logged in for first time in eazyBookmark, she will be redirected to Edit Profile page where she can select username for her profile.

The Profile controller is extended from Application controller to take advantage of login() / logout() method. Also note that this is not the full code for Profile.java. You can check the full source in the project source code.

The View

All the view files in Play! framework as saved in /views/ folder with .html extension. These are the plain HTML files with certain groovy template tags. Read more about built-in template tags in Play! here. There is a file main.html in /views folder which act as the template for all other views. Following is the content of main.html for eazyBookmark.

In above template main.html file, we have #{doLayout /} tag which renders the content. Also note that we are displaying error / success message using flash mechanism of Play!.

For each controller, we create a separate folder in views/ folder. And these folders will contain the view file for each action in given controller. Thus in /views/Application folder we will have index.html and in /views/Profile folder we will have edit.html, editlink.html and index.html. Download these html files from the source code attached at the end of tutorial.

Deploying Play! app in Google App Engine (GAE)

We are done with the coding of our eazyBookmark application. Now we can deploy this app in our GAE account. For that follow the basic steps given here:

Get yourself a GAE account and set up an application. you will need the ID.

Hello,
Great article!
I’m Siena committer and great fan of play! and I also develop some applications for GAE+Siena and it’s really nice to see people use it as you did!
Would you accept to be referenced on Siena site as an example of site?

The tutorial was great, thanks a lot. I have just one little problem, two actually. I would like to understand fully when to use those annotations you used, like ‘@Index’, ‘@Filter”, ‘and @Embedded and I would also like to understand more fully when there is a one to many, many to one, or many to many relationship between the models. Thanks.

Hi Friends, I newly joined a software company, they are using play
framework 1.2.4 as the IDE to develop a web application. My Question is, Which Version of Play framework is easy for a Junior level programmer, as i have basics of Java programming