h1. 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: 

* "Codec":/@api/play/libs/Codec.html: Utilities to encode and decode data.
* "Crypto":/@api/play/libs/Crypto.html: Cryptographics utilities.
* "Expression":/@api/play/libs/Expression.html: Evaluate dynamic expressions.
* "F":/@api/play/libs/F.html: Functional programming with Java.
* "Files":/@api/play/libs/Files.html: File system manipulation helpers.
* "I18N":/@api/play/libs/I18N.html: Internationalization helpers.
* "IO":/@api/play/libs/IO.html: Stream manipulation helpers.
* "Images":/@api/play/libs/Images.html: Image manipulation utilities.
* "Mail":/@api/play/libs/Mail.html: E-mail functions.
* "MimeTypes":/@api/play/libs/MimeTypes.html: Dealing with MIME types.
* "OAuth":/@api/play/libs/OAuth.html: OAuth client protocol.
* "OAuth2":/@api/play/libs/OAuth2.html: OAuth2 client protocol.
* "OpenID":/@api/play/libs/OpenID.html: OpenID client protocol.
* "Time":/@api/play/libs/Time.html: Time and duration utilities.
* "WS":/@api/play/libs/WS.html: Powerful Web Service client.
* "XML":/@api/play/libs/XML.html: Loading XML structures.
* "XPath":/@api/play/libs/XPath.html: Parsing XML using XPath.

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

h2. Parsing XML using XPath

"XPath":http://en.wikipedia.org/wiki/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:

bc. 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);
        …
    }
    
    …
}

h2. Web Service client

The @play.libs.WS@ provides a powerful HTTP client. Under the hood it uses "Async HTTP client":https://github.com/AsyncHttpClient/async-http-client. 

Making a request is easy:

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

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

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

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

bc. 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:

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

h2. 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>@ (a T value that can be or not set)
* @Either<A,B>@ (contains either a A value or a B value)
* @Tuple<A,B>@ (contains both A and B values)

h3. @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”":http://en.wikipedia.org/wiki/Pointer_(computing)#Null_pointer.
@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:

bc. /* 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:

bc. 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>@:

bc. 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.

h3. @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:

bc. 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:

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

p(note). 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>@.

h3. 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:

bc. 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:

bc. 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.

h3. 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:

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

h2. OAuth

"OAuth":http://oauth.net/ 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:

* Redirect the user to the provider’s authorization page
* After the user grants authorization, he is redirected back to your server along with an unauthorized token
* Your server exchanges the unauthorized token with an access token specific to the current user, that needs to be saved in order to perform requests to the service. This step is done as server-to-server communication.

The Play framework takes care of most of the process.

h3. <a>OAuth 1.0</a>

The OAuth 1.0 functionality is provided by the @play.libs.OAuth@ class and is based on "oauth-signpost":http://code.google.com/p/oauth-signpost/. It is used by services such as "Twitter":http://apiwiki.twitter.com/ or "Google":http://code.google.com/apis/accounts/docs/OAuth.html

To connect to a service, you need the create a OAuth.ServiceInfo instance using the following information, obtained from the service provider:
* Request token URL
* Access token URL
* Authorize URL
* Consumer key
* Consumer secret

The access token can be retrieved this way:

bc. 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:

bc. 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@.

h3. <a>OAuth 2.0</a>

OAuth 2.0 is much simpler than OAuth 1.0 because it doesn’t involve signing requests. It is used by "Facebook":http://developers.facebook.com/docs/authentication/ and "37signals":http://37signals.com.

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:
* Access token URL
* Authorize URL
* Client ID
* Secret

bc. 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:

bc. 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@.


h2. OpenID

"OpenID":http://openid.net/ 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:

* For each request, check if the user is connected
* If not, display a page where the user can submit his OpenID
* Redirect the user to the OpenID provider
* When the user comes back, get the verified OpenID and save it in the HTTP session.

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

bc. @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:

bc. #{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:

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

p(note). **Continuing the discussion**
 
Now we’ll check how to perform operations outside any HTTP request using %(next)"Ansynchronous Jobs":jobs%.