Documentation

You are viewing the documentation for the 2.7.0 release in the 2.7.x series of releases. The latest stable release series is 3.0.x.

§Manipulating the response

§Changing the default Content-Type

The result content type is automatically inferred from the Java value you specify as body.

For example:

Result textResult = ok("Hello World!");

Will automatically set the Content-Type header to text/plain, while:

JsonNode json = Json.toJson(object);
Result jsonResult = ok(json);

will set the Content-Type header to application/json.

This is pretty useful, but sometimes you want to change it. Just use the as(newContentType) method on a result to create a new similar result with a different Content-Type header:

Result htmlResult = ok("<h1>Hello World!</h1>").as("text/html");

§Setting HTTP response headers

public Result index() {
    return ok("<h1>Hello World!</h1>").as("text/html")
            .withHeader(CACHE_CONTROL, "max-age=3600")
            .withHeader(ETAG, "some-etag-calculated-value");
}

Note that setting an HTTP header will automatically discard any previous value.

§Setting and discarding cookies

Cookies are just a special form of HTTP headers, but Play provides a set of helpers to make it easier.

You can easily add a Cookie to the HTTP response:

public Result index() {
    return ok("<h1>Hello World!</h1>").as("text/html")
            .withCookies(Cookie.builder("theme", "blue").build());
}

If you need to set more details, including the path, domain, expiry, whether it’s secure, and whether the HTTP only flag should be set, you can do this with the overloaded methods:

public Result index() {
    return ok("<h1>Hello World!</h1>").as("text/html")
            .withCookies(
                    Cookie.builder("theme", "blue")
                            .withMaxAge(Duration.ofSeconds(3600))
                            .withPath("/some/path")
                            .withDomain(".example.com")
                            .withSecure(false)
                            .withHttpOnly(true)
                            .withSameSite(Cookie.SameSite.STRICT)
                            .build()
            );
}

To discard a Cookie previously stored on the web browser:

public Result index() {
    return ok("<h1>Hello World!</h1>").as("text/html")
            .discardingCookie("theme");
}

If you set a path or domain when setting the cookie, make sure that you set the same path or domain when discarding the cookie, as the browser will only discard it if the name, path and domain match.

§Specifying the character encoding for text results

For a text-based HTTP response it is very important to handle the character encoding correctly. Play handles that for you and uses utf-8 by default.

The encoding is used to both convert the text response to the corresponding bytes to send over the network socket, and to add the proper ;charset=xxx extension to the Content-Type header.

The encoding can be specified when you are generating the Result value:

public Result index() {
    return ok("<h1>Hello World!</h1>", "iso-8859-1").as("text/html; charset=iso-8859-1");
}

Next: Session and Flash scopes