§ボディパーサー

§ボディパーサーの概要

HTTP PUT や POST リクエストはボディを含みます。このボディは Content-Type リクエストヘッダで指定さえしておけば、どんなフォーマットであっても構いません。 ボディパーサー はリクエストボディを Java の値に変換する役割を持ちます。

ノート: Java を使って BodyParser を直接実装する事はできません。Play の BodyParser はリクエストボディの内容を Iteratee[Array[Byte], A] を使ってインクリメンタルに処理する必要があるため、 Scala で実装しなければなりません。

しかし Play が提供するデフォルトの BodyParser はほとんどのケースで十分機能します (Json、Xml、テキストの解析やファイルアップロードなど)。そしてこれらのデフォルトパーサーを再利用して独自のボディパーサーを作ることができます。例えば、テキストのパーサーから RDF のパーサーを提供することができます。

§`BodyParser` API

リクエストボディを取り扱う場合は、コントローラに以下をインポートしていることを確認してください:

import play.mvc.*;
import play.mvc.Http.*;

Java では全てのボディパーサーは play.mvc.Http.RequestBody を生成します。ボディパーサーから算出されたこの値は request().body() から取得できます。

public Result index() {
    RequestBody body = request().body();
    return ok("Got body: " + body);
}

アクションで使用する BodyParser を指定したい場合は、@BodyParser.Of アノテーションを使用します。

@BodyParser.Of(BodyParser.Json.class)
public Result index() {
    RequestBody body = request().body();
    return ok("Got json: " + body.asJson());
}

§`Http.RequestBody` API

先ほど Java の API では全てのボディパーサーは play.mvc.Http.RequestBody を提供すると述べました。このボディオブジェクトからはリクエストボディの内容を Java における適切な型で取得できます。

ノート: asText() や asJson() 等の RequestBody のメソッドは、パーサーがこのコンテントタイプをサポートしていない場合は null を返します。例えば、@BodyParser.Of(BodyParser.Json.class) アノテーションが付いたアクションメソッド内では、リクエストボディの asXml() を呼び出すと null を返します。

§デフォルトのボディパーサー： AnyContent

ボディパーサーを指定しない場合、Play はデフォルトのボディパーサーを使用します。このパーサーは Content-Type ヘッダから最も適切なコンテントタイプを推測してくれます。

text/plain: String。asText() でアクセスできます
application/json: JsonNode。asJson() でアクセスできます
application/xml, text/xml または application/XXX+xml: org.w3c.Document。asXml() でアクセスできます
application/form-url-encoded: Map<String, String[]>。asFormUrlEncoded() でアクセスできます
multipart/form-data: Http.MultipartFormData。asMultipartFormData() でアクセスできます
その他の Content-Type: Http.RawBuffer。asRaw()でアクセスできます

例えば、以下のように使用します。

public Result save() {
    RequestBody body = request().body();
    String textBody = body.asText();

    if(textBody != null) {
        return ok("Got: " + textBody);
    } else {
        return badRequest("Expecting text/plain request body");
    }
}

§最大 content length

テキストベースのボディパーサー ( text, json, xml, formUrlEncoded 等) は全てのコンテンツを一旦メモリにロードする必要があるため、最大 content length が設定されています。これらがパースするデフォルトの最大コンテント長は 100KB です。これは application.conf 内で play.http.parser.maxMemoryBuffer を指定して上書くことができます:

play.http.parser.maxMemoryBuffer=128K

raw データや multipart/form-data などの、ディスクにコンテンツをバッファリングするパーサの最大コンテント長は play.http.parser.maxDiskBuffer プロパティを使って指定され、デフォルトは 10MB です。multipart/form-data パーサは、データフィールドを集約するためにテキストの最大コンテンツ長も適用します。

@BodyParser.Of アノテーションを使って、特定のアクションで最大コンテント長のデフォルト値を上書くこともできます:

// Accept only 10KB of data.
@BodyParser.Of(value = BodyParser.Text.class, maxLength = 10 * 1024)
public Result index() {
    return ok("Got body: " + request().body().asText());
}

Next: アクションの合成

このドキュメントの翻訳は Play チームによってメンテナンスされているものではありません。間違いを見つけた場合、このページのソースコードをここで確認することができます。ドキュメントガイドラインを読んで、お気軽にプルリクエストを送ってください。

§ボディパーサー