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

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

@ -29,7 +29,7 @@
<para>Some methods in the core classes of Spring Web MVC are marked
<literal>final</literal>. As a developer you cannot override these
methods to supply your own behavior. This has not been done arbitrarily, but
specifically with this principal in mind.</para>
specifically with this principal in mind.</para>
<para>For an explanation of this principle, refer to <emphasis>Expert
Spring Web MVC and Web Flow</emphasis> by Seth Ladd and others;
@ -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).
@ -451,14 +451,14 @@
in the process to resolve the locale to use when processing the
request (rendering the view, preparing data, and so on). If you do not
need locale resolving, you do not need it.</para>
<!--Reword 'if you don't need local resolving, you dont need to use it '. Are you saying locale resolving is optional? If you don't configure it, will this step occur?-->
<!--Reword 'if you don't need local resolving, you dont need to use it '. Are you saying locale resolving is optional? If you don't configure it, will this step occur?-->
</listitem>
<listitem>
<para>The theme resolver is bound to the request to let elements such
as views determine which theme to use. If you do not use themes, you
can ignore it.</para>
<!-- MLP perhaps say that there are not side effect to this binding.etc... Clarify *ignore it*. Does this step still occur if you don't use themes? --><!--And what if you DO use themes, what do you do and when? Same question re locale resolving.-->
<!-- MLP perhaps say that there are not side effect to this binding.etc... Clarify *ignore it*. Does this step still occur if you don't use themes? --><!--And what if you DO use themes, what do you do and when? Same question re locale resolving.-->
</listitem>
<listitem>
@ -482,7 +482,7 @@
returned, (may be due to a preprocessor or postprocessor
intercepting the request, perhaps for security reasons), no view is
rendered, because the request could already have been fulfilled.</para>
<!--fulfilled how and by what?-->
<!--fulfilled how and by what?-->
</listitem>
</orderedlist>
@ -546,7 +546,7 @@
(using a comma as a delimiter) to support multiple contexts. In
case of multiple context locations with beans that are defined
twice, the latest location takes precedence.</entry>
<!-- MLP review -->
<!-- MLP review -->
</row>
<row>
@ -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
@ -638,7 +638,7 @@ public class HelloWorldController {
for autodetection, aligned with Spring general support for detecting
component classes in the classpath and auto-registering bean definitions
for them.</para>
<!-- MLP Bev.changed to 'also supports autodetection -->
<!-- MLP Bev.changed to 'also supports autodetection -->
<para>To enable autodetection of such annotated controllers, you add
component scanning to your configuration. Use the
<emphasis>spring-context</emphasis> schema as shown in the following XML
@ -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>
@ -815,21 +814,20 @@ public String findOwner(<emphasis role="bold">@PathVariable</emphasis> String ow
is bound to the method parameter <literal>String
ownerId</literal>.</para>
<!-- MLP: Bev Review -->
<!-- MLP: Bev Review -->
<para>The matching of method parameter names to URI Template variable
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
method parameter. For example:</para>
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>
<para>
so you can also use a controller method with the following
}</programlisting>
<para>
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>
@ -1337,27 +1339,28 @@ public String helloWorld() {
@SessionAttributes("pet")
public class EditPetForm {
<lineannotation>// ...</lineannotation>
<lineannotation>// ...</lineannotation>
<emphasis role="bold">@ModelAttribute("types")</emphasis>
public Collection&lt;PetType&gt; populatePetTypes() {
return this.clinic.getPetTypes();
}
<emphasis role="bold">@ModelAttribute("types")</emphasis>
public Collection&lt;PetType&gt; populatePetTypes() {
return this.clinic.getPetTypes();
}
@RequestMapping(method = RequestMethod.POST)
public String processSubmit(
<emphasis role="bold">@ModelAttribute("pet") Pet pet</emphasis>, BindingResult result, SessionStatus status) {
@RequestMapping(method = RequestMethod.POST)
public String processSubmit(
<emphasis role="bold">@ModelAttribute("pet") Pet pet</emphasis>,
BindingResult result, SessionStatus status) {
new PetValidator().validate(pet, result);
if (result.hasErrors()) {
return "petForm";
}
else {
this.clinic.storePet(pet);
status.setComplete();
return "redirect:owner.do?ownerId=" + pet.getOwner().getId();
}
}
new PetValidator().validate(pet, result);
if (result.hasErrors()) {
return "petForm";
}
else {
this.clinic.storePet(pet);
status.setComplete();
return "redirect:owner.do?ownerId=" + pet.getOwner().getId();
}
}
}</programlisting>
</section>
@ -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">
@ -2197,15 +2200,15 @@ public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter {
<programlisting language="java">@Controller
public class ContentController {
private List&lt;SampleContent&gt; contentList = new ArrayList&lt;SampleContent&gt;();
private List&lt;SampleContent&gt; contentList = new ArrayList&lt;SampleContent&gt;();
@RequestMapping(value="/content", method=RequestMethod.GET)
public ModelAndView getContent() {
ModelAndView mav = new ModelAndView();
mav.setViewName("content");
mav.addObject("sampleContentList", contentList);
return mav;
}
@RequestMapping(value="/content", method=RequestMethod.GET)
public ModelAndView getContent() {
ModelAndView mav = new ModelAndView();
mav.setViewName("content");
mav.addObject("sampleContentList", contentList);
return mav;
}
}</programlisting>
</section>
@ -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>