To access parts of a request URL in your handling methods, use the URI templates in the @RequestMapping path value.

http://www.example.com/users/{userid}

http://www.example.com/users/fred

You use the @PathVariable method parameter annotation to indicate that a method parameter should be bound to the value of a URI template variable.

The following code snippet shows the use of a single @PathVariable in a controller method:

@RequestMapping(value="/owners/{ownerId}", method=RequestMethod.GET)
public String findOwner(@PathVariable String ownerId, Model model) {
  Owner owner = ownerService.findOwner(ownerId);  
  model.addAttribute("owner", owner);  
  return "displayOwner"; 
}

The URI Template "/owners/{ownerId}" specifies the variable name ownerId. When the controller handles this request, the value of ownerId is set to the value in the request URI. For example, when a request comes in for /owners/fred, the value fred is bound to the method parameter String ownerId.

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:

@RequestMapping(value="/owners/{ownerId}", method=RequestMethod.GET)
public String findOwner(@PathVariable("ownerId") String ownerId, Model model) {
  // implementation omitted
}

so you can also use a controller method with the following signature:

@RequestMapping(value="/owners/{ownerId}", method=RequestMethod.GET)
public String findOwner(@PathVariable("ownerId") String theOwner, Model model) {
  // implementation omitted
}

You can use multiple @PathVariable annotations to bind to multiple URI Template variables:

@RequestMapping(value="/owners/{ownerId}/pets/{petId}", method=RequestMethod.GET)
public String findPet(@PathVariable String ownerId, @PathVariable String petId, Model model) {
  Owner owner = ownerService.findOwner(ownderId);  
  Pet pet = owner.getPet(petId);  
  model.addAttribute("pet", pet);  
  return "displayPet"; 
}

The following code snippet shows the use of path variables on a relative path, so that the findPet() method will be invoked for /owners/42/pets/21, for instance.

@Controller
@RequestMapping("/owners/{ownerId}")
public class RelativePathUriTemplateController {

  @RequestMapping("/pets/{petId}")
  public void findPet(@PathVariable String ownerId, @PathVariable String petId, Model model) {    
    // implementation omitted
  }
}

	Tip
	Method parameters that are decorated with the @PathVariable annotation can be of any simple type such as int, long, Date... Spring automatically converts to the appropriate type and throws a TypeMismatchException if the type is not correct. You can further customize this conversion process by customizing the data binder. See Section 15.3.2.11, “Customizing WebDataBinder initialization”.

In addition to URI templates, the @RequestMapping annotation also supports Ant-style path patterns (for example, /myPath/*.do). A combination of URI templates and Ant-style globs is also supported (for example, /owners/*/pets/{petId}).

The handler method names are taken into account for narrowing if no path was specified explicitly, according to the specified org.springframework.web.servlet.mvc.multiaction.MethodNameResolver (by default an org.springframework.web.servlet.mvc.multiaction.InternalPathMethodNameResolver). This only applies if annotation mappings do not specify a path mapping explicitly. In other words, the method name is only used for narrowing among a set of matching methods; it does not constitute a primary path mapping itself.

If you have a single default method (without explicit path mapping), then all requests without a more specific mapped method found are dispatched to it. If you have multiple such default methods, then the method name is taken into account for choosing between them.

You can narrow path mappings through parameter conditions: a sequence of "myParam=myValue" style expressions, with a request only mapped if each such parameter is found to have the given value. For example:

@Controller
@RequestMapping("/owners/{ownerId}")
public class RelativePathUriTemplateController {

  @RequestMapping(value = "/pets/{petId}", params="myParam=myValue")
  public void findPet(@PathVariable String ownerId, @PathVariable String petId, Model model) {    
    // implementation omitted
  }
}

"myParam" style expressions are also supported, with such parameters having to be present in the request (allowed to have any value). Finally, "!myParam" style expressions indicate that the specified parameter is not supposed to be present in the request.

Similarly, path mappings can be narrowed down through header conditions:

@Controller
@RequestMapping("/owners/{ownerId}")
public class RelativePathUriTemplateController {

@RequestMapping(value = "/pets", method = RequestMethod.POST, headers="content-type=text/*")
  public void addPet(Pet pet, @PathVariable String ownerId) {    
    // implementation omitted
  }
}

In the above example, the addPet is only invoked when the content-type is in the text/* range, for example, text/xml.

Handler methods that are annotated with @RequestMapping 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):

The following return types are supported for handler methods:

Use the @RequestParam annotation to bind request parameters to a method parameter in your controller.

The following code snippet shows the usage:

@Controller
@RequestMapping("/pets")
@SessionAttributes("pet")
public class EditPetForm {

    // ...

    @RequestMapping(method = RequestMethod.GET)
    public String setupForm(@RequestParam("petId") int petId, ModelMap model) {
        Pet pet = this.clinic.loadPet(petId);
        model.addAttribute("pet", pet);
        return "petForm";
    }

    // ...

Parameters using this annotation are required by default, but you can specify that a parameter is optional by setting @RequestParam's required attribute to false (e.g., @RequestParam(value="id", required="false")).

The @RequestBody method parameter annotation indicates that a method parameter should be bound to the value of the HTTP request body. For example:

@RequestMapping(value = "/something", method = RequestMethod.PUT)
public void handle(@RequestBody String body, Writer writer) throws IOException {
  writer.write(body);
}

You convert the request body to the method argument by using a HttpMessageConverter. HttpMessageConverter is responsible for converting from the HTTP request message to an object and converting from an object to the HTTP response body. DispatcherServlet supports annotation based processing using the DefaultAnnotationHandlerMapping and AnnotationMethodHandlerAdapter. In Spring 3.0 the AnnotationMethodHandlerAdapter is extended to support the @RequestBody and has the following HttpMessageConverters registered by default:

For more information on these converters, see Message Converters.

The MarshallingHttpMessageConverter requires a Marshaller and Unmarshaller from the org.springframework.oxm package to be configured on an instance of AnnotationMethodHandlerAdapter in the application context. For example:

<bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
    <property name="messageConverters">
      <util:list id="beanList">
        <ref bean="stringHttpMessageConverter"/>
        <ref bean="marshallingHttpMessageConverter"/>
      </util:list>
    </property
</bean>

<bean id="stringHttpMessageConverter" 
       class="org.springframework.http.converter.StringHttpMessageConverter"/>

<bean id="marshallingHttpMessageConverter" 
      class="org.springframework.http.converter.xml.MarshallingHttpMessageConverter">
  <property name="marshaller" ref="castorMarshaller" />
  <property name="unmarshaller" ref="castorMarshaller" />
</bean>

<bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller"/>

The @ResponseBody annotation is similar to @RequestBody. This 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:

@RequestMapping(value = "/something", method = RequestMethod.PUT)
@ResponseBody
public String helloWorld()  {
  return "Hello World";
}

The example will result in the text Hello World being written to the HTTP response stream.

As with @RequestBody, Spring converts the returned object to a response body by using a HttpMessageConverter. For more information on these converters, see the previous section and Message Converters.

@ModelAttribute has two usage scenarios in controllers. When you map it to a method parameter, @ModelAttribute maps a model attribute to the specific, annotated method parameter (see the processSubmit() method below). This is how the controller gets a reference to the object holding the data entered in the form.

You can also use the @ModelAttribute at the method level to provide reference data for the model (see the populatePetTypes() method, as in the following example. For this usage the method signature can contain the same types as documented previously for the @RequestMapping annotation.

Note

@ModelAttribute annotated methods are executed before the chosen @RequestMapping annotated handler method. They effectively pre-populate the implicit model with specific attributes, often loaded from a database. Such an attribute can then already be accessed through @ModelAttribute annotated handler method parameters in the chosen handler method, potentially with binding and validation applied to it.

The following code snippet shows these two usages of this annotation:

@Controller
@RequestMapping("/owners/{ownerId}/pets/{petId}/edit")
@SessionAttributes("pet")
public class EditPetForm {

	// ...

	@ModelAttribute("types")
	public Collection<PetType> populatePetTypes() {
		return this.clinic.getPetTypes();
	}

	@RequestMapping(method = RequestMethod.POST)
	public String processSubmit(
			@ModelAttribute("pet") Pet pet, 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();
		}
	}

}

The type-level @SessionAttributes annotation declares session attributes used by a specific handler. This will typically list the names of model attributes which should be transparently stored in the session or some conversational storage, serving as form-backing beans between subsequent requests.

The following code snippet shows the usage of this annotation:

@Controller
@RequestMapping("/editPet.do")
@SessionAttributes("pet")
public class EditPetForm {
    // ...
}

The @CookieValue annotation allows a method parameter to be bound to the value of an HTTP cookie.

Let us consider that the following cookie has been received with an http request:

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

The following code sample allows you to easily get the value of the "JSESSIONID"cookie:

@RequestMapping("/displayHeaderInfo.do")
public void displayHeaderInfo(@CookieValue("JSESSIONID") String cookie)  {

  //...

}

This annotation is supported for annotated handler methods in Servlet and Portlet environments.

The @RequestHeader annotation allows a method parameter to be bound to a request header.

Here is a request header sample:

Host                    localhost:8080
Accept                  text/html,application/xhtml+xml,application/xml;q=0.9
Accept-Language         fr,en-gb;q=0.7,en;q=0.3
Accept-Encoding         gzip,deflate
Accept-Charset          ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive              300

The following code sample allows you to easily get the value of the "Accept-Encoding" and "Keep-Alive" headers:

@RequestMapping("/displayHeaderInfo.do")
  public void displayHeaderInfo(@RequestHeader("Accept-Encoding") String encoding,
                                @RequestHeader("Keep-Alive") long keepAlive)  {

  //...

}

This annotation is supported for annotated handler methods in Servlet and Portlet environments.

To customize request parameter binding with PropertyEditors through Spring's WebDataBinder, you can use either @InitBinder-annotated methods within your controller or externalize your configuration by providing a custom WebBindingInitializer.

@Controller
public class MyFormController {

    @InitBinder
    public void initBinder(WebDataBinder binder) {
        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        dateFormat.setLenient(false);
        binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false));
    }

    // ...
}

<bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
    <property name="cacheSeconds" value="0" />
    <property name="webBindingInitializer">
        <bean class="org.springframework.samples.petclinic.web.ClinicBindingInitializer" />
    </property>
</bean>