play2.0文档-面向java开发者(5)
Body parsers
Body解析器
What is a body parser?
body解析器是啥？
An HTTP request (at least for those using the POST and PUT operations) contains a body. This body can be formatted with any format specified in the Content-Type header. A body parser transforms this request body into a Java value.
一个HTTP请求包含一个Body(至少POST和PUT如此)。这个body可以按照指定的内容类型格式化。
一个Body解析器负责把请求的Body转换成Java值。
Note: You can’t write BodyParser implementation directly using Java. Because a Play BodyParser must handle the body content incrementaly using anIteratee[Array[Byte], A] it must be implemented in Scala.
注意： BodyParser 不能用Java实现，只能用scala实现，这是因为 BodyParser 用来处理渐增数据会用到scala实现的Iteratee[Array[Byte], A] 。
However Play provides default BodyParsers that should fit most use cases (parsing Json, Xml, Text, uploading files). And you can reuse these default parsers to create your own directly in Java; for example you can provide an RDF parsers based on the Text one.
然而，play提供了适合绝大多数情况下的默认 BodyParsers (解析Json, Xml, Text, 上载文件)
The BodyParser Java API
In the Java API, all body parsers must generate a play.mvc.Http.RequestBodyvalue. This value computed by the body parser can then be retrieved viarequest().body():
在Java API中，所有的body解析器都会生成一个 play.mvc.Http.RequestBody
pulic static Result index() { RequestBody body = request().body(); ok("Got body: " + body); }
You can specify the BodyParser to use for a particular action using [email protected] annotation:
@BodyParser.Of(BodyParser.Json.class) pulic static Result index() { RequestBody body = request().body(); ok("Got json: " + body.asJson()); }
The Http.RequestBody API
As we just said all body parsers in the Java API will give you aplay.mvc.Http.RequestBody value. From this body object you can retrieve the request body content in the most appropriate Java type.
就像刚才说的那样，所有body解析器都会得到一个play.mvc.Http.RequestBody 值，我们可以从这个body对象里获得适当类型body的内容。
Note: The RequestBody methods like asText() or asJson() will return null if the parser used to compute this request body doesn’t support this content type. For example in an action method annotated [email protected](BodyParser.Json.class), calling asXml() on the generated body will retun null.
注意：如果解析器不支持请求body的类型， asText() 或 asJson() 等RequestBody 的一些方法会返回null。例如一个action用了@BodyParser.Of(BodyParser.Json.class)注解，如果调用asXml()就会返回null。
Some parsers can provide a most specific type than Http.RequestBody (ie. a subclass of Http.RequestBody). You can automatically cast the request body into another type using the as(...) helper method:
一些解析器可能会提供最常用的类型（例如 Http.RequestBody的子类）。你可以用 as(...) 方法进行转换。
@BodyParser.Of(BodyLengthParser.class)
pulic static Result index() {
BodyLength body = request().body().as(BodyLength.class);
ok("Request body length: " + body.getLength());
}
Default body parser: AnyContent
默认的body解析器：AnyContent
If you don’t specify your own body parser, Play will use the default one guessing the most appropriate content type from the Content-Type header:
如果你不指定body解析器，play就会用默认的来推测类型：
- text/plain: String, accessible via asText()
- application/json: JsonNode, accessible via asJson()
- text/xml: org.w3c.Document, accessible via asXml()
- application/form-url-encoded: Map<String, String[]>, accessible viaasFormUrlEncoded()
- multipart/form-data: Http.MultipartFormData, accessible viaasMultipartFormData()
- Any other content type: Http.RawBuffer, accessible via asRaw()
Example:
pulic static Result save() {
RequestBody body = request().body();
String textBody = body.asText();
if(textBody != null) {
ok("Got: " + text);
} else {
badRequest("Expecting text/plain request body");
}
}
Max content length
最大content长度
Text based body parsers (such as text, json, xml or formUrlEncoded) use a max content length because they have to load all the content into memory.
基于文本的body解析器（例如 text, json, xml 或者 formUrlEncoded) 需要使用最大content长度，因为它们会把所有的内容加载到内存里。
There is a default content length (the default is 100KB).
这是个默认的内容长度（100KB）.
Tip: The default content size can be defined in application.conf:
提示：默认的content大小可以在application.conf 中定义：
parsers.text.maxLength=128K
You can also specify a maximum content length via the @BodyParser.Of annotation:
你也可以通过 @BodyParser.Of 注解来制定最大content长度：
// Accept only 10KB of data.
@BodyParser.Of(value = BodyParser.Text.class, maxLength = 10 * 1024)
pulic static Result index() {
if(request().body().isMaxSizeExceeded()) {
return badRequest("Too much data!");
} else {
ok("Got body: " + request().body().asText());
}
}