Documentation

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

Play libs

The play.libs package contains several useful libraries that will help you to achieve common programming tasks.

Most of these libraries are simple helpers that are really straightforward to use:

The following sections provide more information about the most important libraries.

Parsing XML using XPath

XPath is probably the easiest way to parse an XML document without having to use code generation tools. The play.libs.XPath library offers all the needed primitives to efficiently achieve this task.

The XPath operations operate on all org.w3.dom.Node types:

org.w3.dom.Document xmlDoc = … // retrieve a Document somewhere
  
for(Node event: XPath.selectNodes("events//event", xmlDoc)) {
    
    String name = XPath.selectText("name", event);
    String data = XPath.selectText("@date", event);
    
    for(Node place: XPath.selectNodes("//place", event)) {
        String place = XPath.selectText("@city", place);
        …
    }
    
    …
}

Web Service client

The play.libs.WS provides a powerful HTTP client. Under the hood it uses Async HTTP client.

Making a request is easy:

HttpResponse res = WS.url("http://www.google.com").get();

Once you have an HttpResponse object you can access all the response properties.

int status = res.getStatus();
String type = res.getContentType();

You can also retrieve the body content in several content types:

String content = res.getString();
Document xml = res.getXml();
JsonElement json = res.getJson();
InputStream is = res.getStream();

You can also use the async API to make HTTP requests in a non-blocking way. Then you will receive a Promise<HttpResponse>. Once redeemed, you can use the HttpResponse as usual:

Promise<HttpResponse> futureResponse = WS.url(
    "http://www.google.com"
).getAsync();

Functional programming with Java

The play.libs.F library provide several useful constructs coming from functional programming. These constructs are used to handle complex abstraction cases. For those that are accustomed to functional programming we provide:

Option<T>, Some<T> and None<T>

When you write a function that may not return a result in some cases (e.g. a find method), a common (bad) Java pattern is to return null when there is no result. This practice is dangerous because the function return type does not clearly shows that it may not return an object and it has been recognized by the nullable references inventor to be a “billion-dollar mistake”.
Option<T> is an elegant solution to this problem: instead of returning an object of type T, the function returns an Option<T>. If the function succeeds, it returns an object of type Some<T> (wrapping the real result), otherwise an object of type None<T>, which both are subtypes of Option<T>.
Here is an example:

/* Safe division (will never throw a runtime ArithmeticException) */
public Option<Double> div(double a, double b) {
    if (b == 0)
        return None();
    else
        return Some(a / b);
}

Here is a way to use this function:

Option<Double> q = div(42, 5);
if (q.isDefined()) {
    Logger.info("q = %s", q.get()); // "q = 8.4"
}

But there is a more convenient syntax to use it, leveraging the fact that Option<T> implements Iterable<T>:

for (double q : div(42, 5)) {
    Logger.info("q = %s", q); // "q = 8.4"
}

The body of the for loop is be executed once, only if the div function succeeded.

Tuple<A, B>

The handy Tuple<A, B> class wraps two objects of type A and B. You can retrieve the objects using the _1 and _2 fields, respectively. For example:

public Option<Tuple<String, String>> parseEmail(String email) {
    final Matcher matcher = Pattern.compile("(\\w+)@(\\w+)").matcher(email);
    if (matcher.matches()) {
        return Some(Tuple(matcher.group(1), matcher.group(2)));
    }
    return None();
}

Then:

for (Tuple<String, String> email : parseEmail("[email protected]")) {
    Logger.info("name = %s", email._1); // "name = foo"
    Logger.info("server = %s", email._2); // "server = bar.com"
}

The T2<A, B> class is an alias for Tuple<A, B>. To handle tuples of 3 elements use the T3<A, B, C> class, and so on up to T5<A, B, C, D, E>.

Pattern Matching

Sometimes we feel that we need pattern matching in Java. Unfortunately Java does not have built-in pattern matching, and because of the lack of functional constructs, it is difficult to add it as a library. Anyway we’ve worked on a solution that is not so bad.

Our idea was to use the latest ‘for loop’ syntax to achieve basic pattern matching for Java. Pattern matching must both check if your object matches the required conditions and extract the interesting value. The Pattern matching library for Play is part of the play.libs.F library.

Let’s see a simple example; you have a reference of type Object and you want to check that it is a string that starts by ‘command:’.

The standard way would be:

Object o = anything();
 
if(o instanceof String && ((String)o).startsWith("command:")) {
    String s = (String)o;
    System.out.println(s.toUpperCase());
}

Using the Play pattern matching library, you can write it as:

for(String s: String.and(StartsWith("command:")).match(o)) {
    System.out.println(s.toUpperCase());
}

The for loop is executed once, only if the condition is met, and it automatically extracts the String value without the need for casting. Because there is no explicit cast, everything is type-safe, and checked by the compiler.

Promises

A Promise is Play’s custom Future type. In fact a Promise<T> is also a Future<T> so you can use it as a standard Future. But it has also a very interesting property: the ability to register callback using onRedeem(…) that will be called as soon as the promised value is available.

Promise instances are used everywhere in Play in place of Future instances (for Jobs, WS.async, etc…).

Promises can be combined in several ways. For example:

Promise p = Promise.waitAll(p1, p2, p3)
Promise p = Promise.waitAny(p1, p2, p3)
Promise p = Promise.waitEither(p1, p2, p3)

OAuth

OAuth is an open protocol for secure API authorization, using a simple and standard approach, from desktop and web applications.

Two different specifications exist: OAuth 1.0 and OAuth 2.0. Play provides libraries to connect as a consumer to services proposing either of these specifications.

The general process is the following:

The Play framework takes care of most of the process.

OAuth 1.0

The OAuth 1.0 functionality is provided by the play.libs.OAuth class and is based on oauth-signpost. It is used by services such as Twitter or Google

To connect to a service, you need the create a OAuth.ServiceInfo instance using the following information, obtained from the service provider:

The access token can be retrieved this way:

public static void authenticate() {
    // TWITTER is a OAuth.ServiceInfo object
    // getUser() is a method returning the current user 
    if (OAuth.isVerifierResponse()) {
        // We got the verifier; 
        // now get the access tokens using the request tokens
        OAuth.Response resp = OAuth.service(TWITTER).retrieveAccessToken(
            getUser().token, getUser().secret
        );
        // let's store them and go back to index
        getUser().token = resp.token; getUser().secret = resp.secret;
        getUser().save()
        index();
    }
    OAuth twitt = OAuth.service(TWITTER);
    Response resp = twitt.retrieveRequestToken();
    // We received the unauthorized tokens 
    // we need to store them before continuing
    getUser().token = resp.token; getUser().secret = resp.secret;
    getUser().save()
    // Redirect the user to the authorization page
    redirect(twitt.redirectUrl(resp.token));
}

Calls can now be done by signing the requests using the token pair:

mentions = WS.url(url).oauth(TWITTER, getUser().token, getUser().secret).get().getString();

While the example doesn’t check for errors, in production you should. The OAuth.Response object holds an error field that is non-null when an error occurred. Most likely it could be that the user didn’t grant you access, that the provider is down or buggy.

The full example usage is available in samples-and-tests/twitter-oauth.

OAuth 2.0

OAuth 2.0 is much simpler than OAuth 1.0 because it doesn’t involve signing requests. It is used by Facebook and 37signals.

Functionality is provided by play.libs.OAuth2.

To connect to a service, you need the create a OAuth2 instance using the following information, obtained from the service provider:

public static void auth() {
    // FACEBOOK is a OAuth2 object
    if (OAuth2.isCodeResponse()) {
        // authUrl must be the same as the retrieveVerificationCode call
        OAuth2.Response response = FACEBOOK.retrieveAccessToken(authUrl);
        // null if an error occurred
        String accessToken = response.accessToken;
        // null if the call was a success
        OAuth2.Error = response.error;
        // Save accessToken, you will need it to request the service
        index();
    }
    // authUrl is a String containing an absolute URL where the service 
    // should redirect the user back
    // This will trigger a redirect
    FACEBOOK.requestVerificationCode(authUrl);
}

Once you have the access token associated to the current user, you can use it to query the service on behalf of the user:

WS.url(
    "https://graph.facebook.com/me?access_token=%s", access_token
).get().getJson();

The full example usage is available in samples-and-tests/facebook-oauth2.

OpenID

OpenID is an open and decentralized identity system. You can easily accept new users in your application without having to keep specific user information. You just have to keep track of authorized users through their OpenID.

This example provides a high-level view of how OpenID authentication can be used within a Play application:

The OpenID functionality is provided by the play.libs.OpenID class.

@Before(unless={"login", "authenticate"})
static void checkAuthenticated() {
    if(!session.contains("user")) {
        login();
    }
}
 
public static void index() {
    render("Hello %s!", session.get("user"));
}
     
public static void login() {
    render();
}
    
public static void authenticate(String user) {
    if(OpenID.isAuthenticationResponse()) {
        UserInfo verifiedUser = OpenID.getVerifiedID();
        if(verifiedUser == null) {
            flash.error("Oops. Authentication has failed");
            login();
        } 
        session.put("user", verifiedUser.id);
        index();
    } else {
        if(!OpenID.id(user).verify()) { // will redirect the user
            flash.error("Cannot verify your OpenID");
            login();
        } 
    }
}

And the login.html template:

#{if flash.error}
<h1>${flash.error}</h1>
#{/if}
 
<form action="@{Application.authenticate()}" method="POST">
    <label for="user">What’s your OpenID?</label>
    <input type="text" name="user" id="user" />
    <input type="submit" value="login…" />
</form>
</code>

And finally the routes definitions:

GET   /                     Application.index
GET   /login                Application.login
*     /authenticate         Application.authenticate

Continuing the discussion

Now we’ll check how to perform operations outside any HTTP request using Ansynchronous Jobs.