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

Polishing the reference manual. 

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@2158 50f2f4bb-b051-0410-bef5-90022cba6387
This commit is contained in:
Sam Brannen 2009-10-19 18:26:02 +00:00
parent 46e8560cfc
commit 2130540ffb
1 changed files with 86 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -326,8 +326,8 @@
&lt;/web-app&gt;</programlisting>
<para>With the above servlet configuration in place, <!--Is this something you need to do (in above example)? -->you
will need to have a file called <literal>/WEB-INF/<emphasis
role="bold">golfing</emphasis>-servlet.xml</literal> in your application;
will need to have a file called <literal>/WEB-INF/</literal><emphasis
role="bold">golfing</emphasis><literal>-servlet.xml</literal> in your application;
this file will contain all of your Spring Web MVC-specific components
(beans). You can change the exact location of this configuration file
through a servlet initialization parameter (see below for details).
@ -586,7 +586,7 @@
<emphasis>PetClinic</emphasis> sample, a web application that leverages
the annotation support described in this section, in the context of
simple form processing. The <emphasis>PetClinic</emphasis> application
resides in the <literal>samples/petclinic</literal> directory.</para>
resides in the <literal>org.springframework.samples.petclinic</literal> module.</para>
<!-- MLP Note removed reference to imagedb -->
</tip>
@ -598,7 +598,7 @@ public class HelloWorldController {
@RequestMapping("/helloWorld")
public ModelAndView helloWorld() {
ModelAndView mac = new ModelAndView();
ModelAndView mav = new ModelAndView();
mav.setViewName("helloWorld");
mav.addObject("message", "Hello World!");
return mav;
@ -624,7 +624,7 @@ public class HelloWorldController {
indicates that a particular class serves the role of a
<emphasis>controller</emphasis>. Spring does not require you to extend
any controller base class or reference the Servlet API. However, you can
still reference Servlet-specific features if you need to do so.</para>
still reference Servlet-specific features if you need to.</para>
<para>The <interfacename>@Controller</interfacename> annotation acts as
a stereotype for the annotated class, indicating its role. The
@ -668,21 +668,20 @@ public class HelloWorldController {
<para>You use the <interfacename>@RequestMapping</interfacename>
annotation to map URLs such as <filename>/appointments</filename> onto
an entire class or a particular handler method. You can use it to
annotate both a class and a method. Typically the class-level annotation
an entire class or a particular handler method. Typically the class-level annotation
maps a specific request path (or path pattern) onto a form controller,
with additional method-level annotations narrowing the primary mapping
for a specific HTTP method request method ("GET"/"POST") or specific
HTTP request parameters.</para>
<para>The following example shows a controller from the PetClinic sample
application that uses this annotation:</para>
<para>The following example shows a controller in a JSF application
that uses this annotation:</para>
<programlisting language="java">@Controller
<emphasis role="bold">@RequestMapping("/appointments")</emphasis>
public class AppointmentsController {
private AppointmentBook appointmentBook;
private final AppointmentBook appointmentBook;
@Autowired
public AppointmentsController(AppointmentBook appointmentBook) {
@ -791,11 +790,11 @@ public class ClinicController {
variables.</para>
</sidebar>
<para>You use the <interfacename>@PathVariable</interfacename> method
<para>Use the <interfacename>@PathVariable</interfacename> method
parameter annotation to indicate that a method parameter should be
bound to the value of a URI template variable.</para>
<para>The following code snippet shows the use of a single
<para>The following code snippet shows the usage of a single
<interfacename>@PathVariable</interfacename> in a controller
method:</para>
@ -820,16 +819,15 @@ public String findOwner(<emphasis role="bold">@PathVariable</emphasis> String ow
names can only be done if your code is compiled with debugging
enabled. If you do have not debugging enabled, you must specify the
name of the URI Template variable name in the @PathVariable annotation
in order to bind the resovled value of the variable name to a
in order to bind the resolved value of the variable name to a
method parameter. For example:</para>
<programlisting language="java">@RequestMapping(value="/owners/{ownerId}", method=RequestMethod.GET)
public String findOwner(<emphasis role="bold">@PathVariable</emphasis>("ownerId") String ownerId, Model model) {
// implementation omitted
}
</programlisting>
}</programlisting>
<para>
so you can also use a controller method with the following
You can also use a controller method with the following
signature:</para>
<programlisting language="java">@RequestMapping(value="/owners/{ownerId}", method=RequestMethod.GET)
@ -850,7 +848,7 @@ public String findPet(<emphasis role="bold">@PathVariable</emphasis> String owne
}
</programlisting>
<para>The following code snippet shows the use of path variables on a
<para>The following code snippet shows the usage of path variables on a
relative path, so that the <methodname>findPet()</methodname> method
will be invoked for <filename>/owners/42/pets/21</filename>, for
instance.</para>
@ -870,7 +868,7 @@ public class RelativePathUriTemplateController {
<para>Method parameters that are decorated with the
<interfacename>@PathVariable</interfacename> annotation can be of
<emphasis role="bold">any simple type </emphasis>such as int, long,
Date... Spring automatically converts to the appropriate type and
Date, etc. Spring automatically converts to the appropriate type and
throws a <classname>TypeMismatchException</classname> if the type is
not correct. You can further customize this conversion process by
customizing the data binder. See <xref
@ -924,7 +922,9 @@ public class RelativePathUriTemplateController {
<emphasis>not</emphasis> supposed to be present in the request.</para>
<para>Similarly, path mappings can be narrowed down through header
conditions: <programlisting language="java">@Controller
conditions:</para>
<programlisting language="java">@Controller
@RequestMapping("/owners/{ownerId}")
public class RelativePathUriTemplateController {
@ -933,10 +933,11 @@ public class RelativePathUriTemplateController {
public void addPet(Pet pet, @PathVariable String ownerId) {
// implementation omitted
}
}
</programlisting> In the above example, the <methodname>addPet</methodname> is
only invoked when the content-type is in the <literal>text/*</literal>
range, for example, <literal>text/xml</literal>.</para>
}</programlisting>
<para>In the above example, the <methodname>addPet()</methodname> method is
only invoked when the <literal>content-type</literal> matches the <literal>text/*</literal>
pattern, for example, <literal>text/xml</literal>.</para>
</section>
<section id="mvc-ann-requestmapping-arguments">
@ -945,13 +946,14 @@ public class RelativePathUriTemplateController {
<para>Handler methods that are annotated with
<classname>@RequestMapping</classname> can have very flexible
signatures. They may have arguments of the following types, in
arbitrary order. (except for validation results, which need to follow
right after the corresponding command object, if desired<!--Reword preceding sentence to clarify, make it a complete sentence and no parentheses: first it says validation results *must*--><!--immediately follow command object, but then it says *if desired*. Clarify what must happen if what is desired. And are validation --><!-- results a type of argument? Relate to the sentence that precedes it.-->):
arbitrary order (except for validation results, which need to follow
right after the corresponding command object, if desired):
<!--Reword preceding sentence to clarify, make it a complete sentence and no parentheses: first it says validation results *must*--><!--immediately follow command object, but then it says *if desired*. Clarify what must happen if what is desired. And are validation --><!-- results a type of argument? Relate to the sentence that precedes it.-->
<itemizedlist>
<listitem>
<para>Request and/or response objects (Servlet API). Choose any
specific request/response type, for example,
<interfacename>ServletRequest</interfacename> /
<para>Request or response objects (Servlet API). Choose any
specific request or response type, for example
<interfacename>ServletRequest</interfacename> or
<interfacename>HttpServletRequest</interfacename>.</para>
</listitem>
@ -964,7 +966,7 @@ public class RelativePathUriTemplateController {
<note>
<para>Session access may not be thread-safe, in particular in
a Servlet environment: Consider switching the
a Servlet environment. Consider setting the
<classname>AnnotationMethodHandlerAdapter</classname>'s
"synchronizeOnSession" flag to "true" if multiple requests are
allowed to access a session concurrently.</para>
@ -1024,7 +1026,7 @@ public class RelativePathUriTemplateController {
<listitem>
<para><classname>@RequestBody</classname> annotated parameters
for access to the request HTTP body. Parameter values are
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>
@ -1047,7 +1049,7 @@ public class RelativePathUriTemplateController {
<literal>webBindingInitializer</literal> property on
<classname>AnnotationMethodHandlerAdapter</classname>. Such
command objects along with their validation results will be
exposed as model attributes by default., using the non-qualified
exposed as model attributes by default, using the non-qualified
command class name in property notation. <!--Who or what uses the non-qualified class name in property notation? Is this something you have to set up?-->For
example, "orderAddress" for type "mypackage.OrderAddress".
Specify a parameter-level <classname>ModelAttribute</classname>
@ -1059,7 +1061,7 @@ public class RelativePathUriTemplateController {
/
<classname>org.springframework.validation.BindingResult</classname>
validation results for a preceding command or form object (the
immediately preceding argument).</para>
immediately preceding method argument).</para>
</listitem>
<listitem>
@ -1109,7 +1111,7 @@ public class RelativePathUriTemplateController {
<listitem>
<para>A <classname>String</classname> value that is interpreted
as the view name, with the model implicitly determined through
as the logical view name, with the model implicitly determined through
command objects and <literal>@ModelAttribute</literal> annotated
reference data accessor methods. The handler method may also
programmatically enrich the model by declaring a
@ -1139,7 +1141,7 @@ public class RelativePathUriTemplateController {
</listitem>
<listitem>
<para>Any other return type is considered as single model
<para>Any other return type is considered to be a single model
attribute to be exposed to the view, using the attribute name
specified through <literal>@ModelAttribute</literal> at the
method level (or the default attribute name based on the return
@ -1181,7 +1183,7 @@ public class EditPetForm {
<interfacename>@RequestParam</interfacename>'s
<literal>required</literal> attribute to <literal>false</literal>
(e.g., <literal>@RequestParam(value="id",
required="false")</literal>).</para>
required=false)</literal>).</para>
</section>
<section id="mvc-ann-requestbody">
@ -1197,7 +1199,7 @@ public void handle(@RequestBody String body, Writer writer) throws IOException {
writer.write(body);
}</programlisting>
<para>You convert the request body to the method argument by using a
<para>You convert the request body to the method argument by using an
<interfacename>HttpMessageConverter</interfacename>.
<interfacename>HttpMessageConverter</interfacename> is responsible for
converting from the HTTP request message to an object and converting
@ -1289,11 +1291,11 @@ public String helloWorld() {
return "Hello World";
}</programlisting>
<para>The example will result in the text <literal>Hello
<para>The above example will result in the text <literal>Hello
World</literal> being written to the HTTP response stream.</para>
<para>As with <interfacename>@RequestBody</interfacename>, Spring converts
the returned object to a response body by using a
the returned object to a response body by using an
<interfacename>HttpMessageConverter</interfacename>. For more
information on these converters, see the previous section and <link
linkend="rest-message-conversion">Message Converters</link>.</para>
@ -1311,10 +1313,10 @@ public String helloWorld() {
controller gets a reference to the object holding the data entered in
the form.</para>
<para>You can also use the <classname>@ModelAttribute </classname>at
<para>You can also use <classname>@ModelAttribute</classname> at
the method level to provide <emphasis>reference data</emphasis> for
the model (see the <literal>populatePetTypes()</literal> method, as in
the following example. For this usage the method signature can contain
the model (see the <literal>populatePetTypes()</literal> method in
the following example). For this usage the method signature can contain
the same types as documented previously for the
<classname>@RequestMapping</classname> annotation.</para>
@ -1346,7 +1348,8 @@ public class EditPetForm {
@RequestMapping(method = RequestMethod.POST)
public String processSubmit(
<emphasis role="bold">@ModelAttribute("pet") Pet pet</emphasis>, BindingResult result, SessionStatus status) {
<emphasis role="bold">@ModelAttribute("pet") Pet pet</emphasis>,
BindingResult result, SessionStatus status) {
new PetValidator().validate(pet, result);
if (result.hasErrors()) {
@ -1368,20 +1371,20 @@ public class EditPetForm {
<para>The type-level <classname>@SessionAttributes</classname>
annotation declares session attributes used by a specific handler.
This will typically list the names of model attributes which should be
This will typically list the names of model attributes or types of
model attributes which should be
transparently stored in the session or some conversational storage,
serving as form-backing beans between subsequent requests.</para>
<para>The following code snippet shows the usage of this
annotation:</para>
annotation, specifying the model attribute name:</para>
<programlisting language="java">@Controller
@RequestMapping("/editPet.do")
<emphasis role="bold">@SessionAttributes("pet")</emphasis>
public class EditPetForm {
<lineannotation>// ...</lineannotation>
}
</programlisting>
}</programlisting>
</section>
<section id="mvc-ann-cookievalue">
@ -2934,20 +2937,20 @@ public class SimpleController {
<itemizedlist>
<listitem>
<para><classname>AdminController</classname> maps to the
<literal>/admin<emphasis role="bold">/*</emphasis></literal> request
<literal>/admin</literal><emphasis role="bold">/*</emphasis> request
URL</para>
</listitem>
<listitem>
<para><classname>CatalogController</classname> maps to the
<literal>/catalog<emphasis role="bold">/*</emphasis></literal>
<literal>/catalog</literal><emphasis role="bold">/*</emphasis>
request URL</para>
</listitem>
</itemizedlist>
<para>If you follow the convention of naming your
<interfacename>Controller</interfacename> implementations as
<literal>xxx<emphasis role="bold">Controller</emphasis></literal>, the
<literal>xxx</literal><emphasis role="bold">Controller</emphasis>, the
<classname>ControllerClassNameHandlerMapping</classname> saves you the
tedium of defining and maintaining a potentially
<emphasis>looooong</emphasis>