diff --git a/org.springframework.web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java b/org.springframework.web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java
index 7e001314dc..674cf7031b 100644
--- a/org.springframework.web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java
+++ b/org.springframework.web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java
@@ -91,10 +91,15 @@ import java.lang.annotation.Target;
* {@link org.springframework.http.HttpHeaders HttpHeaders} method parameter to
* gain access to all request headers.
*
{@link RequestBody @RequestBody} annotated parameters for access to
- * the Servlet request HTTP contents. Parameter values will be
+ * the Servlet request HTTP contents. The request stream will be
* converted to the declared method argument type using
* {@linkplain org.springframework.http.converter.HttpMessageConverter message
* converters}.
+ *
{@link org.springframework.http.HttpEntity HttpEntity<?>} parameters
+ * for access to the Servlet request HTTP headers and contents. The request stream will be
+ * converted to the entity body using
+ * {@linkplain org.springframework.http.converter.HttpMessageConverter message
+ * converters}.
*
{@link java.util.Map} / {@link org.springframework.ui.Model} /
* {@link org.springframework.ui.ModelMap} for enriching the implicit model
* that will be exposed to the web view.
@@ -141,6 +146,16 @@ import java.lang.annotation.Target;
* The handler method may also programmatically enrich the model by
* declaring a {@link org.springframework.ui.ModelMap} argument
* (see above).
+ *
{@link ResponseBody @ResponseBody} annotated methods for access to
+ * the Servlet response HTTP contents. The return value will be converted
+ * to the response stream using
+ * {@linkplain org.springframework.http.converter.HttpMessageConverter message
+ * converters}.
+ *
A {@link org.springframework.http.HttpEntity HttpEntity<?>} object
+ * to access to the Servlet reponse HTTP headers and contents. The entity body will
+ * be converted to the response stream using
+ * {@linkplain org.springframework.http.converter.HttpMessageConverter message
+ * converters}.
*
void if the method handles the response itself (by
* writing the response content directly, declaring an argument of type
* {@link javax.servlet.ServletResponse} / {@link javax.servlet.http.HttpServletResponse}
diff --git a/spring-framework-reference/src/mvc.xml b/spring-framework-reference/src/mvc.xml
index 45ed5e6b76..8203a1d126 100644
--- a/spring-framework-reference/src/mvc.xml
+++ b/spring-framework-reference/src/mvc.xml
@@ -1023,20 +1023,28 @@ public class RelativePathUriTemplateController {
- @RequestHeader annotated parameters
+ @RequestHeader annotated parameters
for access to specific Servlet request HTTP headers. Parameter
values are converted to the declared method argument
type.
- @RequestBody annotated parameters
+ @RequestBody annotated parameters
for access to the HTTP request body. Parameter values are
converted to the declared method argument type using
HttpMessageConverters. See .
+
+ HttpEntity<?> parameters
+ for access to the Servlet request HTTP headers and contents. The request stream will be
+ converted to the entity body using
+ HttpMessageConverters. See .
+
+
java.util.Map /
org.springframework.ui.Model /
@@ -1145,6 +1153,14 @@ public class RelativePathUriTemplateController {
linkend="mvc-ann-responsebody" />.
+
+ A HttpEntity<?>} object
+ to access to the Servlet reponse HTTP headers and contents. The entity body will
+ be converted to the response stream using
+ HttpMessageConverters. See .
+
+
Any other return type is considered to be a single model
attribute to be exposed to the view, using the attribute name
@@ -1159,7 +1175,7 @@ public class RelativePathUriTemplateController {
Binding request parameters to method parameters with
- @RequestParam
+ @RequestParamUse the @RequestParam annotation to bind
request parameters to a method parameter in your controller.
@@ -1280,12 +1296,12 @@ public void handle(@RequestBody String body, Writer writer) throws IOException {
- Mapping the response body with the @ResponseBody
+ Mapping the response body with the @ResponseBody
annotationThe @ResponseBody annotation is
similar to @RequestBody. This
- annotation can be put on a method and
+ annotation can be put on a method and
indicates that the return type should be written straight to the HTTP
response body (and not placed in a Model, or interpreted as a view
name). For example:
@@ -1306,12 +1322,45 @@ public String helloWorld() {
linkend="rest-message-conversion">Message Converters.
+
+ Using HttpEntity<?>
+
+ The HttpEntity is similar to
+ @RequestBody and
+ @ResponseBody. Besides getting
+ access to the request and response body, the HttpEntity
+ also allows access to the request and response headers, like so:
+
+ @RequestMapping("/something")
+public HttpEntity<String> handle(HttpEntity<byte[]> requestEntity) throws UnsupportedEncodingException {
+ String requestHeader = requestEntity.getHeaders().getFirst("MyRequestHeader"));
+ byte[] requestBody = requestEntity.getBody();
+ // do something with request header and body
+
+ HttpHeaders responseHeaders = new HttpHeaders();
+ responseHeaders.set("MyResponseHeader", "MyValue");
+ return new HttpEntity<String>("Hello World", responseHeaders);
+}
+
+ The above example gets the value of the "MyRequestHeader" request
+ header, and reads the body as a byte array. It adds the "MyResponseHeader"
+ to the response, and writes Hello World to the response
+ stream.
+
+ As with @RequestBody and
+ @ResponseBody, Spring
+ uses HttpMessageConverter to convert
+ from and to the request and response streams. For more
+ information on these converters, see the previous section and Message Converters.
+
+
Providing a link to data from the model with
@ModelAttribute@ModelAttribute has two usage scenarios
- in controllers. When you map it to a
+ in controllers. When you place it on a
method parameter, @ModelAttribute maps a model
attribute to the specific, annotated method parameter (see the
processSubmit() method below). This is how the