Documentation

You are viewing the documentation for the 2.4.x release series. 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");

You can also set the content type on the HTTP response context:

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

§Setting HTTP response headers

public Result index() {
    response().setContentType("text/html");
    response().setHeader(CACHE_CONTROL, "max-age=3600");
    response().setHeader(ETAG, "xxx");
    return ok("<h1>Hello World!</h1>");
}

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:

response().setCookie("theme", "blue");

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:

response().setCookie(
        "theme",        // name
        "blue",         // value
        3600,           // maximum age
        "/some/path",   // path
        ".example.com", // domain
        false,          // secure
        true            // http only
);

To discard a Cookie previously stored on the web browser:

response().discardCookie("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() {
    response().setContentType("text/html; charset=iso-8859-1");
    return ok("<h1>Hello World!</h1>", "iso-8859-1");
}

Next: Session and Flash scopes


Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.