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