root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Documented HttpEntity

This commit is contained in:
Arjen Poutsma 2010-03-29 11:12:45 +00:00
parent c18137d40a
commit 122e4346bb
2 changed files with 71 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
org.springframework.web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java
View File

@ -91,10 +91,15 @@ import java.lang.annotation.Target;
* {@link org.springframework.http.HttpHeaders HttpHeaders} method parameter to
* gain access to all request headers.
* <li>{@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}.
* <li>{@link org.springframework.http.HttpEntity HttpEntity&lt;?&gt;} 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}.
* <li>{@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).
* <li>{@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}.
* <li>A {@link org.springframework.http.HttpEntity HttpEntity&lt;?&gt;} 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}.
* <li><code>void</code> 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}

61
spring-framework-reference/src/mvc.xml
View File

@ -1023,20 +1023,28 @@ public class RelativePathUriTemplateController {
</listitem>
<listitem>
<para><classname>@RequestHeader</classname> annotated parameters
<para><interfacename>@RequestHeader</interfacename> annotated parameters
for access to specific Servlet request HTTP headers. Parameter
values are converted to the declared method argument
type.</para>
</listitem>
<listitem>
<para><classname>@RequestBody</classname> annotated parameters
<para><interfacename>@RequestBody</interfacename> annotated parameters
for access to the HTTP request body. Parameter values are
converted to the declared method argument type using
<interfacename>HttpMessageConverter</interfacename>s. See <xref
linkend="mvc-ann-requestbody" />.</para>
</listitem>
<listitem>
<para><classname>HttpEntity&lt;?&gt;</classname> parameters
for access to the Servlet request HTTP headers and contents. The request stream will be
converted to the entity body using
<interfacename>HttpMessageConverter</interfacename>s. See <xref
linkend="mvc-ann-httpentity" />.</para>
</listitem>
<listitem>
<para><interfacename>java.util.Map</interfacename> /
<interfacename>org.springframework.ui.Model</interfacename> /
@ -1145,6 +1153,14 @@ public class RelativePathUriTemplateController {
linkend="mvc-ann-responsebody" />.</para>
</listitem>
<listitem>
<para>A <classname>HttpEntity&lt;?&gt;</classname>} object
to access to the Servlet reponse HTTP headers and contents. The entity body will
be converted to the response stream using
<interfacename>HttpMessageConverter</interfacename>s. See <xref
linkend="mvc-ann-httpentity" />.</para>
</listitem>
<listitem>
<para>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 {
<section id="mvc-ann-requestparam">
<title>Binding request parameters to method parameters with
<classname>@RequestParam</classname></title>
<interfacename>@RequestParam</interfacename></title>
<para>Use the <classname>@RequestParam</classname> annotation to bind
request parameters to a method parameter in your controller.</para>
@ -1280,12 +1296,12 @@ public void handle(@RequestBody String body, Writer writer) throws IOException {
</section>
<section id="mvc-ann-responsebody">
<title>Mapping the response body with the @ResponseBody
<title>Mapping the response body with the <interfacename>@ResponseBody</interfacename>
annotation</title>
<para>The <interfacename>@ResponseBody</interfacename> annotation is
similar to <interfacename>@RequestBody</interfacename>. This
annotation can be put on a method <!--Revise *can be put on*. You do *what* with this annotation in regard to 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:</para>
@ -1306,12 +1322,45 @@ public String helloWorld() {
linkend="rest-message-conversion">Message Converters</link>.</para>
</section>
<section id="mvc-ann-httpentity">
<title>Using <classname>HttpEntity&lt;?&gt;</classname></title>
<para>The <classname>HttpEntity</classname> is similar to
<interfacename>@RequestBody</interfacename> and
<interfacename>@ResponseBody</interfacename>. Besides getting
access to the request and response body, the <classname>HttpEntity</classname>
also allows access to the request and response headers, like so:</para>
<programlisting language="java">@RequestMapping("/something")
public HttpEntity&lt;String&gt; handle(HttpEntity&lt;byte[]&gt; 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&lt;String&gt;("Hello World", responseHeaders);
}</programlisting>
<para>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 <literal>Hello World</literal> to the response
stream.</para>
<para>As with <interfacename>@RequestBody</interfacename> and
<interfacename>@ResponseBody</interfacename>, Spring
uses <interfacename>HttpMessageConverter</interfacename> to convert
from and to the request and response streams. For more
information on these converters, see the previous section and <link
linkend="rest-message-conversion">Message Converters</link>.</para>
</section>
<section id="mvc-ann-modelattrib">
<title>Providing a link to data from the model with
<classname>@ModelAttribute</classname></title>
<para><classname>@ModelAttribute</classname> has two usage scenarios
in controllers. When you map it to <!--is this correct, *map it to*? If not, what do you mean by *is placed on*?-->a
in controllers. When you place it on a
method parameter, <classname>@ModelAttribute</classname> maps a model
attribute to the specific, annotated method parameter (see the
<literal>processSubmit()</literal> method below). This is how the