Play Framework Cookbook

All you need is a browser and some basic knowledge about unzipping and copying files in your operating system. Also be aware that you can install Play on Microsoft Windows, Linux as well as Mac OS X or even BSD.

Open up a browser and go to http://www.playframework.org/download and download the most up-to-date stable version http://download.playframework.org/releases/play-1.2.zip (at the time of writing this recpe play 1.2 was the latest stable version).

After downloading it, unzip it, either with a GUI tool or via command line zip:

unzip play-1.1.zip

If you are using Linux or MacOS you might want to put the unzipped directory in /usr/local/ in order to make Play available to all the users on your system; however, this is optional and requires the root access on the particular system:

mv play-1.1 /usr/local/

As a last step adding the Play binary inside the play-1.1 directory to the PATH environment variale is encouraged. This is easily possible with a symlink:

ln -s /usr/local/play-1.1/play /usr/local/bin/play

If you enter play on your commandline, you should get an ASCII art output along with some help and, most importantly, the version of Play you just called. If you do not want to create a symlink, you can also copy the Play binary to a path, which is already included in the PATH variable. In the preceding example you could have copied it to /usr/local/bin.

As just mentioned, Play would also work by just unzipping the Play framework archive and always using the absolute path of your installation. However, as this is not very convenient, you should put your installation at the defined location. This also makes it quite easy for you to replace old Play framework versions against newer ones, without having to change anything else than the created symlink.

If you are on a Linux system and you do not see the ASCII art output as mentioned some time back, it might very well be possible that you already have a Play binary on your system, installed. For example, the sox package, which includes several tools for audio processing, also includes a Play binary, which surprisingly plays an audio file. If you do not want to have this hassle, the simplest way is just to create the symlink with another name such as:

ln -s /usr/local/play-1.1/play /usr/local/bin/play-web

Now calling play-web instead of play will for sure always call the Play framework specific script.

Change into a directory where you want to create a new application and execute the following command:

play new myApp

This command will create a new directory named myApp and copy all needed resources for any project into it. After this is done, it should be finished in almost no time. The following file system layout exists inside the myApp directory:

./conf
./conf/dependencies.yml
./conf/routes
./conf/application.conf
./conf/messages
./test
./lib
./public
./app
./app/models
./app/controllers
./app/views

If you are familiar with a rails application, you might be able to orientate very quickly. Basically, the conf directory contains configuration and internationalization files, where as the app folder has a subdirectory for its model definitions. Its controllers contain the business logic and its views, being a mix of HTML and the Play template language. The lib directory contains jar libraries needed to run your application. The public folder contains static content like JavaScript, CSS, and images; and finally the test folder contains all types of tests.

Generally speaking, you can add arbitrary content in the form of directories and files in the application directory; for example, the files needed to support Eclipse, or NetBeans will be put here as well. However, you should never remove data which has been copied during the creation of the application unless you really know what you are doing.

As seen some time back in the filesystem layout, after creating a new application, there is a conf/routes file. This file can be seen as the central point of your application. In order to have a truly REST based architecture, the combination of the HTTP method and URL define an implicit action. Using HTTP GET on any URL should never ever change any resource because such calls are seen as idempotent calls and should always return the same result.

In order to fully understand the importance of the routes file, this graphic illustrates that it is the starting point for every incoming HTTP request:

The image is also available at http://www.playframework.org/documentation/1.2/images/diagrams_path.

Basically the router component parses the routes file on startup and does the mapping to the Controller.

Always be aware that no logic can be executed from an external source if not triggered by the router component, which in turn is configured by default in the conf/routes file.

Edit your routes file as shown in the following code snippet:

GET      /              Application.index
POST     /users         Application.createUser
GET      /user/{id}     Application.showUser
DELETE   /user/{id}     Application.deleteUser

# Map static resources from the /app/public folder to the /public path 

GET     /public         staticDir:public

The preceding example features a basic application for user management. It utilizes HTTP methods and URIs appropriately. For the sake of simplicity, updating a user is not intended in this example. Every URI (alternatively called a resource) maps to a Java method in a controller, which is also called an action. This method is the last part of the line, with the exception to the HTTP resource /public, where the public directory is mapped to the public URI. You might have already noticed the usage of some sort of expression language in the URI. The ID variable can be used in the controller and will contain that part of the URI. So /user/alex will map alex to the ID variable in the showUser and deleteUser methods of the controller.

Please be aware that some browsers currently only support GET and POST methods. However, you can freely use PUT and DELETE as well, because Play has a built-in workaround for this which uses POST and setting the X-HTTP-Method-Override header telling the framework to execute the code as needed. Be aware to set this request header when writing applications yourself, that connect to a play-based application.

As seen in the preceding screenshot, the router component can do more than parsing the routes file. It is possible to have more complex rules such as using regular expressions.

Using regular expressions in the URL is actually pretty simple, as you can just include them:

GET     /user/{<[0-9]+>id}		Application.showUser

This ensures that only numbers are a valid user ID. Requesting a resource like /user/alex now would not work anymore, but /user/1234 instead would work. You can even create a List from the arguments in the URL with the following line of code:

GET     /showUsers/{<[\0-9]+>ids}/?	Application.showUsers

In your application code you know you could use a List<Integer> IDs and show several users at once, when the URL /showUsers/1234/1/2 is called. Your controller code would start like this:

public static void showUsers(@As("/") List<Integer> ids) {

This introduces some new complexity in your application logic, so always be aware if you really want to do this. One of the usecases where this is useful is when you want to use some sort of hierarchical trees in your URLs, like when displaying a mailbox with folders and arbitrary subfolders.

You can also use annotations to create routing, which offers you some more flexibility. See the first recipe in Chapter 2. Furthermore, routing can also be done for virtual host, and this will also be presented later on.

Just open conf/application.conf with your any editor supporting UTF-8, be it Eclipse, Vim, textmate, or even notepad.

Now every configuration option follows the scheme:

# Some comment
key = value

Notable for application start is the http.port option, which runs your Play application per default on port 9000; this can be changed to any port above 1024 if you are a non-root user, which is highly recommended anyway.

By definition Java property files are ISO-8859-1 and nothing else. Play, however, is thought of as an everything-UTF-8 framework; hence, the application configuration filename does not have a .properties suffix. For more info about standard Java properties, please refer to:

http://download.oracle.com/javase/6/docs/api/java/util/Properties.html

As the documentation covers most of the possible parameters in the configuration file pretty well, this file will only be mentioned if the default configuration has to be changed.

Most importantly, adding and configuring modules in order to enhance the basic functionality of Play is part of the application.conf, and each module requires enabling it via defining its path:

module.foo=${play.path}/modules/foo

After starting your Play application, the console output should include information about which of your configured modules have been loaded successfully.

Another important setup is the log level of your application when using log4j, which is used by Play framework all over the place. When in production mode, it should be set to INFO or ERROR; however, in testing mode the following line might help you to discover problems:

application.log=DEBUG

We will refer to the application.conf file when setting up special databases later on in this chapter. Also there is an own Configuring log4j for log rotation recipe in the Chapter 7, Running in Production.

In order to follow this recipe, you should use the conf/routes file defined in the recipe Defining routes as the entry point to your application in this chapter.

Fire up your favorite editor, open app/controllers/Application.java, and put the following into the file:

package controllers;

import play.*;
import play.mvc.*;
public class Application extends Controller {

    public static void index() {
        render();
    }

    public static void showUser(String id) {
         render();
    }   

    public static void deleteUser(String id) {
        render();
    }

    public static void createUser(User user) {
        render();     
    }   
}

Absolutely no business logic happens here. All that is done here is to create a possibility to execute business logic. When looking back at the conf/routes file you see the use of the id parameter, which is again used here as a parameter for the static method inside the Application class. Due to the name of the parameter it is automatically filled with the corresponding part of the URL in the request; for example, calling GET /user/1234 will result in putting "1234" in the ID parameter of the showUser method. The most important fact to make a Java class work as controller is to have it extend from play.mvc.Controller. Furthermore, all your actions have to be static in order to be executed as controller methods.

As no business logic is executed here (such as creating or deleting a user from some database) the render() method is called. This method is again defined in the controller class and tells the controller to start the rendering phase. A template is looked up and rendered. As Play also follows the convention over configuration pattern, a default template location is assumed, which follows an easy naming scheme:

./app/views/${controller}/{method}.html

In the case of showing a user it would be:

./app/views/Application/showUser.html

This not only looks pretty simple, it actually is. As Play framework follows the MVC principle, you should be aware that the controller layer should be as thin as possible. This means that this layer is not for business logic but merely for validation in order to ensure the model layer will only get valid data.

    public static void createUser(User user) {

        // Do something with the user object
        // ...
        render();
    }

   public static void createUser(User user) {

        // store user here..., then call showUser()showUser(user.id);
    }

Many recipes will change controller logic. Consider dealing with controllers which is absolute and essential core knowledge.

Any model you define should go into the models package, which resides in the app/models directory.

As in the recipes before, this was already a reference to a user entity. It is the right time to create one now. Store this in the file app/models/User.java:

package models;

import javax.persistence.Entity;
import play.data.validation.Email;
import play.data.validation.Required;
import play.db.jpa.Model;

@Entity
public class User extends Model {

        public String login;

        @Required @Email
        public String email;
}

Although there are not many lines of code, lots of things are included here. First, there are JPA annotations marking this class to be stored in a database. Second, there are validation annotations, which can be used to ensure which data should be in the object from an application point of view and not dependent on any database.

The next crucially important point is the fact that the User class inherits from Model. This is absolutely essential, because it allows you to use the so-called ActiveRecord pattern for querying of data.

Also, by inheriting from the Model class you can use the save() method to persist the object to the database. However, you should always make sure you are importing the correct Model class, as there exists another Model class in the Play framework, which is an interface.

The last important thing which again will be mainly noticed by the Java developers is the fact, that all fields in the example code are public. Though the preceding code does not explicitly define getters and setters, they are injected at runtime into the class. This has two advantages. First, you as a developer do not have to write them, which means that your entity classes are very short and concise and not filled with setters and getters irrelevant to your logic. Second, if you really want to put logic into setters such as adding some complex check or changing the result before really storing it to the database, then it is possible without any problem. If you want you can also reuse your existing JPA entities, which are likely to have getters and setters. It is all a matter of choice. But the shorter your models are the more concise and easy to understand they will be.

Now let's talk about some other options, or possibly some pieces of general information that are relevant to this task.

User user = User.find("byName", name).).).first();

List<User> users = User.find("byEmailLike", "alexander@%").fetch();

List<User> users = User.find("byEmailLike", "alexander@%")
                                        .from(20).fetch(10);

long results = User.count("byEmailLike", "alexander@%");

For more information on the active record pattern you might want to check the Wikipedia entry http://en.wikipedia.org/wiki/Active_record or the more Ruby on Rails specific active record API at http://ar.rubyonrails.org/. There is also an active record implementation in pure Java at http://code.google.com/p/activejdbc.

There is a recipe for encrypting passwords before storing them on the database which makes use of creating an own setter.

Define a fixtures file and store it under conf/initial-data.yml:

User(alr):
        login: alr
        password: test
        email: alr@spinscale.de

Tweet(t1):
        content: Lets get ready to tweet
        postedAt: 2010-11-22T08:23:15
        login: alr

As you can see in the preceding snippet, there are two entities defined. The first one only consists of strings, whereas the second one consists of a date and a reference to the first one, which uses the name in parentheses after the type as a reference.

Fixtures are helpful in two cases. For one you can ensure the same test data in your unit, functional, and selenium tests. Also you can make sure, that your application is initialized with a certain set of data, when the application is loaded for the first time.

@OnApplicationStart
public class Bootstrap extends Job {

    public void doJob() {
        // Check if the database is empty
        if(User.count() == 0) {
          Fixtures.load("initial-data.yml");
        }
    }

tags:             [tag1, tag2, tag3, tag4]

The first step is to get the user inside the controller and allow it in the view to be used. Edit app/controllers/Application.java and change the showUser() method to this:

public static void showUser(Long id) {
        User user = User.findById(id);
        notFoundIfNull(user);
        render(user);
}

After that create an HTML template file in ./app/views/Application/showUser.html:

#{extends 'main.html' /}
#{set title:'User info' /}

<h1>${user.login}</}</}</h1>

Send <a href="mailto:${user.email}">}">}">mail</a>

Though again only a couple of lines have been written, a lot of things have happened. Beginning with the name and path of the template location, it is just the name of the class (including the package, which the controller does not have in this case) and its method name appended with a file format. Of course, you can change it, but this way it is pretty easy to understand which view code belongs to which controller action.

Regarding the controller logic all that has been done is to query the database for the user with a specific ID (the one specified in the URL) and to return a HTTP 404 error, if the returned object is null. This eliminates the nasty null checks from your code to keep it as clean as possible. The last part triggers the rendering. The argument handed over (you can choose an arbitrary amount of arguments) can be referenced in the HTML template under the name you put in the render() method. If you used render(userObj) you could reference it as userObj in the template.

The template contains lots of information in the four lines of code. First, Play template specific tags always use a #{} notation. Second, Play templates support some sort of inheritance with the #{extends} tag, as the main.html has been chosen here as a template into which the rest of the code is embedded. Third, you can set variables in this template, which are parsed in the main.html template, like the variable title, which is set in line two. Lastly you can easily output fields from the user object by writing the name of the object inside the template and its field name. As already done before, the field is not accessed directly, but the getter is called.

Templating is covered fairly well in the documentation and in the example, so be sure to check it out.

It is very easy to write your own tags, so be sure to follow the next recipe as well as get some information about mixins, which allows you to define some more logic for displaying data without changing it in the model; for example, replacing the last digits with XXX for privacy issues.

Furthermore, a recipe with an own renderRSS() is shown as last recipe in Chapter 2, which is about controllers.

In this example, we will write a small tag called #{loginStatus /}, which will print the username or write a small note, that the user is not logged in. This is a standard snippet, which you might include in all of your pages, but do not want to write over again.

The following logic is assumed in the controller, here in Application.java:

public static void login(String login, String password) {
   User user = User.find("byLoginAndPassword", login, password).first();
   notFoundIfNull(user);
   session.put("login", user.login);
}

A new tag needs to be created in app/views/tags/loginStatus.html:

<div class="loginStatus">
#{if session.login}
Logged in as ${session.login}
#{/if}
#{else}
Not logged in
#{/else}
</div>

Using it in your own templates is now easy, just put the following in your templates:

#{loginStatus /}

The controller introduces the concept of state in the web application by putting something in the session. The parameters of the login method have been (if not specified in routes file) constructed from the request parameters. In this case, from a request, which has most likely been a form submit. Upon calling the controller, the user is looked up in the database and the user's login name is stored in the session, which in turn is stored on the client side in an encrypted cookie.

Every HTML file in the app/views/tags directory is automatically used as a tag, which makes creating tags pretty simple. The tag itself is quite self explanatory, as it just checks whether the login property is set inside the session.

As a last word about sessions, please be aware that the session referenced in the code is actually not a HttpSession as in almost all other Java based frameworks. It is not an object stored on the server side, but rather its contents are stored as an encrypted cookie on the client side. This means you cannot store an arbitrary amount of data in it.

You should use tags whenever possible instead of repeating template code. If you need more performance you can even write them in Java instead of using the templating language.

Keep on reading the next recipe, where we will reformat a Date type from boring numbers to a string without using a tag, but a so-called extension.

Just create a tiny application. You will need to create a new application and add a database to the application configuration, so entities can be specified.

You need a route to show your tweets in conf/routes:

GET      /{username}/timeline           Application.showTweet

After that we can model a tweet model class:

package models;


import java.util.Date;
import javax.persistence.Entity;
import play.data.validation.Max;
import play.db.jpa.Model;

@Entity
public class Tweet extends Model {

        @Max(140) public String content;
        public Date postedAt;
        public User user;
}

As well as a simple user entity:

@Entity
public class User extends Model {

        @Column(unique=true) 
        public String login;
}

The controller is quite short. It uses an alternative query for the 20 newest tweets, which is more JPA like:

public static void showTweets(String username) {
        User user = User.find("byLogin", username).first();
        notFoundIfNull(user);
        List<Tweet> tweets = Tweet.find("user = ? order by postedAt DESC", user).fetch(20);
        render(tweets, user);
}

The rendering code will look like this:

#{extends 'main.html' /}
#{set 'title'}${user.login} tweets#{/set}

#{list tweets, as:'tweet'}
<div><h3>${tweet.content}</h3> by ${tweet.user.login} at <i>${tweet.postedAt.since()}</i></h3></div>
#{/list}

Now this code works. However, the since() Java Extension, which is built in with Play only works when you hand over a date in the past as it calculates the difference from now. What if you want to add a feature of a future tweet which is blurred, but will show a time when it is shown? You need to hack up your own extensions to do this. Create a new class called CustomExtensions in the extensions package inside your application directory (so the file is ./app/extensions/CustomExtension.java)

public class CustomExtensions extends JavaExtensions {

        private static final long MIN   = 60;
        private static final long HOUR  = MIN * 60;
        private static final long DAY   = HOUR * 24;
        private static final long MONTH = DAY * 30;
        private static final long YEAR  = DAY * 365;

        public static String pretty(Date date) {
                Date now = new Date();
                if (date.after(now)) {
	                long delta = (date.getTime() - now.getTime()) / 1000;

                if (delta < 60) {
                    return Messages.get("in.seconds", delta,
 pluralize(delta));
                }

                if (delta < HOUR) {
                    long minutes = delta / MIN;
                    return Messages.get("in.minutes", minutes, pluralize(minutes));
                }

                if (delta < DAY) {
                    long hours = delta / HOUR;
                    return Messages.get("in.hours", hours,
 pluralize(hours));
                }

                if (delta < MONTH) {
                    long days = delta / DAY;
                    return Messages.get("in.days", days, pluralize(days));
                }

                if (delta < YEAR) {
                    long months = delta / MONTH;
                    return Messages.get("in.months", months,
 pluralize(months));
                }

                long years = delta / YEAR;
                return Messages.get("in.years", years, pluralize(years));

                } else {
                        return JavaExtensions.since(date);
                }

        }
}

Update your ./app/conf/messages file for successful internationalization by appending to it:

in.seconds = in %s second%s
in.minutes = in %s minute%s
in.hours   = in %s hour%s
in.days    = in %s day%s
in.months  = in %s month%s
in.years   = in %s year%s

The last change is to replace the template code to:

#{list tweets, as:'tweet'}
<div><h3>${tweet.content}</h3> by ${tweet.user.login} at <i>${tweet.postedAt.pretty()}</i></h3></div>
#{/list}

A lot of code has been written for an allegedly short example. The entity definitions, routes configuration, and controller code should by now be familiar to you. The only new thing is the call of ${tweet.postedAt.since()} in the template, which does call a standard Java Extension already shipped with Play. When calling the since() method, you must make sure that you called it on an object from the java.util.Date class. Otherwise, this extension will not be found, as they are dependent on the type called on. What the since() method does, is to reformat the boring date to a pretty printed and internationalized string, how long ago this date is from the current time. However this functionality only works for dates in the past and not for future dates.

Therefore the CustomExtensions class has been created with the pretty() method in it. Every class which inherits from JavaExtensions automatically exposes its methods as extension in your templates. The most important part of the pretty() method is actually its signature. By marking the first parameter as type java.util.Date you define for which data type this method applies. The logic inside the method is pretty straightforward as it also reuses the code from the since() extension. The only unknown thing is the call to Messages.get(), which just returns the string in the correct language, such as"3 days ago" in English and "vor 3 Tagen" in German.

Last but not least, the template code is changed to use the new extension instead of since().

Java Extensions can be incredibly handy if used right. You should also make sure that this area of your application is properly documented, so frontend developers know what to search for, before trying to implement it somehow in the view layer.

public static void pretty(Date date, String name) {

In this example the "search" module is going to be installed. It is a great module which allows you to integrate with Apache Lucene by just adding two annotations to your JPA models. From then on you can do lightning fast queries instead of using your database for full tex search ueries. However, if you want to install any module, you need to have an Internet connection for the first installation. Furthermore, this search module is used as an example in this case; there will be no implementation hits on using it. Please refer to the documentation for this.

Check whether the module is already installed. This should be executed in the directory of a Play application in order to return useful data:

play modules

Check whether the module you want to install is available:

play list-modules

Put this in your conf/dependencies.yml file:

require:
    - play
    - play -> search head

Then run play deps. After you have run and downloaded the module, you will have a ./modules/search-head directory in your application, which gets automatically loaded on application startup.

When starting your application the next time you should see the following startup message:

10:58:48,825 INFO  ~ Module search is available (/path/to/app/modules/search-head)

In case you are using an older version of Play than version 1.2, there is another mechanism to install a module, which needs further configuration. Make sure you are inside of the Play application where you want to install the module:

play install search

You are asked whether you are sure you want to install the module, because you need to check whether this module is compatible with the version of Play you are using. The installation tries to install the latest version of the module, but you can choose the module version in case you need an older one.

Follow the hint in the last line and put it into the conf/application.conf file:

module.search=${play.path}/modules/search-head

When starting your application the next time you should see the following startup message:

10:58:48,825 INFO  ~ Module search is available (/home/alex/devel/play/play-1.1/modules/search-head)

From now on you can use the module and its functionality in your code.

The steps are pretty straightforward as it is automated as much as possible. When calling Play install, everything is downloaded as a big package from the Web, unpacked in your Play installation (not your application) and from then on, ready to run in any Play web, once enabled in the configuration. The main difference between the old and new way of adding modules is the fact that the old mechanism stored the modules not in the application but in the framework directory, where as the new mechanism only stores modules inside of the application directory.

Many modules require additional configuration in the conf/application.conf file. For example, if you install a module which persists your models in a MongoDB database, you will need to configure the database connection additionally. However, such cases are always documented, so just check the module documentation in case.

Also if modules do not work, first check whether they work in your version of Play. If this is the case, you should also file a bug report or inform the module maintainer. Many modules are not maintained by the core developers of Play, but instead by users of the Play framework.

If you are interested in modules, check out the Chapter 5, Introduction to Writing Modules in this book. It also includes a recipe Using Solr for indexing, which takes up the search topic again.

Just add driver-specific configuration in your configuration file. In order to support PostgreSQL, this is the way:

db.url=jdbc:postgresql:accounting_db
db.driver=org.postgresql.Driver

db.user=acct
db.pass=Bdgc54S

Oracle can also be configured without problems:

db.url=jdbc:oracle:thin:@db01.your.host:1521:tst-db01

db.driver=oracle.jdbc.driver.OracleDriver

As the JDBC mechanism already provides a generic way to unify the access to arbitrary databases, the complexity to configure different database is generally pretty low in Java. Play supports this by only needing to configure the db.url and db.driver configuration variables to have support for most databases, which provide a JDBC driver.

You can even go further and configure your connection pool (if the JDBC driver has support for that), reusing application server resources, or check whether changing your JPA dialect is also needed when changing your default database.

db=java:/comp/env/jdbc/myDatasource

# db.pool.timeout=1000
# db.pool.maxSize=30
# db.pool.minSize=10

jpa.dialect=org.hibernate.dialect.Oracle10gDialect

In order to have a simple test, you could create a small application which creates a big PDF report. Then access the URL mapped to the PDF report creation more often simultaneous than you have CPU cores. So you would have to request this resource three times at once on a duo core machine. You will see that a maximum two HTTP connections are executed simultaneously; in development mode it will be only one, regardless of your CPU count.

Play 1.2 introduces a new feature called continuations, which allows transparent suspension of threads including recovery without writing any additional code to do this:

public static void generateInvoice(Long orderId) {
    Order order = Order.findById(orderId);
    InputStream is = await(new OrderAsPdfJob(order).now());
    renderBinary(is);
}

Of course, the OrderAsPdfJob needs a signature like this:

public void OrderAsPdfJob extends Job<InputStream> {

    public InputStreamdoJobWithResult() {
        // logic goes here
    }
}

You can suspend your logic for a certain amount of time like this:

public static void stockChanges() {
   List<Stock> stocks = Stock.find("date > ?", request.date).fetch();
   if (stocks.isEmpty()) {
       suspend("1s");
   }
renderJSON(stocks);
}

Alternatively, you can wait until a certain job has finished its business logic:

public static void generateInvoice(Long orderId) {
    if(request.isNew) {
        Order order = Order.findById(orderId);
        Future<InputStream> task = new OrderAsPdfJob(order).now();
        request.args.put("task", task);
        waitFor(task);
    }
    renderBinary((Future<InputStream>)request.args.get("task").get());
}

Following the three lines of code in the first example, you see that there is actually no invocation telling the framework to suspend the thread. The await() method takes a so-called Promise as argument, which is returned by the now() method of the job. A Promise is basically a standard Java Future with added functionality for invocation inside of the framework, when the task is finished.

The stockChanges() example is pretty self explanatory as it waits the defined amount of time before it is called again. This means that the operation is only called again if there was no updated stock available and it is very important it is called again from the beginning. Otherwise it will happily render the JSON output and has to be triggered by the client again. As you can see, this would be a pretty interesting starting point for implementing SLAs for your customers in a stock rate application, as you could allow your premium customers quicker updates.

The second example takes another approach. The controller logic is actually run twice. In the first run, the isNew parameter is true and starts a Play job to create the PDF of an invoice. This parameter is automatically set by the framework depending on the status of the request and gives the developer the possibility to decide what should happen next. The waitFor() tells the framework to suspend here. Again, after the task is finished, the whole controller method will be called again, but this time only the renderBinary() method is called as isNew is false, which returns the result by calling get() on the Future type.

Always think whether introducing such a suspended response is really what you want or whether this just shows certain problems in your application design. Most of the time such a mechanism is not needed.

The recipe Integration with Munin in Chapter 7 shows how to monitor your controller execution times in order to make sure you are suspending the right requests.

Use the session object inside the controller to write something into it. This is a standard task during a login:

public static void login(String login, String password) {
    User user = User.find("byLoginAndPassword", login, password).first();
    notFoundIfNull(user);
    session.put("login", user.login);
    index();
}

The session variable can now be accessed from any other controller method as long as it is not deleted. This works for small content, like a login:

String login = session.get("login");

Now, you can also use the built-in cache functionality instead of the session to store data on the server side. The cache allows you to put more data than the session maximum of 4 kilobytes into the cache (for the sake of having a lot of data assume that you are a subcontractor of Santa Claus, responsible for the EMEA region and constantly filling your shopping cart without checking out):

Cache.set(login, shoppingCart, "20mn");

Querying is as easy as calling:

Cache.get(login)

Adding data to the session is as easy as using a regular session object. However, there is no warning if there is data put into the session, which is bigger than the maximum allowed cookie size. Unfortunately, the application will just break when getting the data out of the cookie, as it is not stored in the cookie, and the session.get() call will always fail.

In order to avoid this problem, just use the Cache class for storing such data. You can also add a date when the data should expire out of the cache.

Caching is a very powerful weapon in the fight for performance. However, you always gain performance at the cost of reducing the actuality of your data. Always decide what is more important. If you can keep your data up-to-date by scaling out and adding more machines, this might be more useful in some cases, than caching it. As easy as caching is, it should always be the last resort.

memcached=enabled
memcached.host=127.0.0.1:11211

There is a recipe on writing your own cache implementation in Chapter 4 called Writing your own cache implementation, where Hazelcast is used to store data. In Chapter 3 there is also a general recipe Basics of caching about caching different aspects of your application.