MockHttpServletRequestBuilder (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.test.web.servlet.request

## Class MockHttpServletRequestBuilder

- java.lang.Object
- - org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder

- All Implemented Interfaces:
    Mergeable, RequestBuilder
  Direct Known Subclasses:
    MockMultipartHttpServletRequestBuilder

      public class MockHttpServletRequestBuilder
      extends Object
      implements RequestBuilder, Mergeable

  Default builder for `MockHttpServletRequest` required as input to perform request in `MockMvc`.

  Application tests will typically access this builder through the static factory methods in `MockMvcBuilders`.

  Since:
    3.2
  Author:
    Rossen Stoyanchev, Arjen Poutsma

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `MockHttpServletRequestBuilder` | `accept(MediaType... mediaTypes)` Set the 'Accept' header to the given media type(s).
    `MockHttpServletRequest` | `buildRequest(ServletContext servletContext)` Build a `MockHttpServletRequest`.
    `MockHttpServletRequestBuilder` | `characterEncoding(String encoding)` Set the character encoding of the request.
    `MockHttpServletRequestBuilder` | `content(byte[] content)` Set the request body.
    `MockHttpServletRequestBuilder` | `content(String content)` Set the request body as a UTF-8 String.
    `MockHttpServletRequestBuilder` | `contentType(MediaType mediaType)` Set the 'Content-Type' header of the request.
    `MockHttpServletRequestBuilder` | `contextPath(String contextPath)` Specify the portion of the requestURI that represents the context path.
    `MockHttpServletRequestBuilder` | `cookie(Cookie... cookies)` Add the given cookies to the request.
    `protected MockHttpServletRequest` | `createServletRequest(ServletContext servletContext)` Creates a new `MockHttpServletRequest` based on the given `ServletContext`.
    `MockHttpServletRequestBuilder` | `flashAttr(String name, Object value)` Set an "input" flash attribute.
    `MockHttpServletRequestBuilder` | `flashAttrs(Map<String,Object> flashAttributes)` Set flash attributes.
    `MockHttpServletRequestBuilder` | `header(String name, Object... values)` Add a header to the request.
    `MockHttpServletRequestBuilder` | `headers(HttpHeaders httpHeaders)` Add all headers to the request.
    `boolean` | `isMergeEnabled()` Is merging enabled for this particular instance?
    `MockHttpServletRequestBuilder` | `locale(Locale locale)` Set the locale of the request.
    `Object` | `merge(Object parent)` Merges the properties of the "parent" RequestBuilder accepting values only if not already set in "this" instance.
    `MockHttpServletRequestBuilder` | `param(String name, String... values)` Add a request parameter to the `MockHttpServletRequest`.
    `MockHttpServletRequestBuilder` | `pathInfo(String pathInfo)` Specify the portion of the requestURI that represents the pathInfo.
    `MockHttpServletRequestBuilder` | `principal(Principal principal)` Set the principal of the request.
    `MockHttpServletRequestBuilder` | `requestAttr(String name, Object value)` Set a request attribute.
    `MockHttpServletRequestBuilder` | `secure(boolean secure)` Set the secure property of the `ServletRequest` indicating use of a secure channel, such as HTTPS.
    `MockHttpServletRequestBuilder` | `servletPath(String servletPath)` Specify the portion of the requestURI that represents the path to which the Servlet is mapped.
    `MockHttpServletRequestBuilder` | `session(MockHttpSession session)` Set the HTTP session to use, possibly re-used across requests.
    `MockHttpServletRequestBuilder` | `sessionAttr(String name, Object value)` Set a session attribute.
    `MockHttpServletRequestBuilder` | `sessionAttrs(Map<String,Object> sessionAttributes)` Set session attributes.
    `MockHttpServletRequestBuilder` | `with(RequestPostProcessor postProcessor)` An extension point for further initialization of `MockHttpServletRequest` in ways not built directly into the `MockHttpServletRequestBuilder`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### param

          public MockHttpServletRequestBuilder param(String name,
                                            String... values)

      Add a request parameter to the `MockHttpServletRequest`. If called more than once, the new values are added.
      Parameters:
        `name` - the parameter name
        `values` - one or more values

    - #### header

          public MockHttpServletRequestBuilder header(String name,
                                             Object... values)

      Add a header to the request. Values are always added.
      Parameters:
        `name` - the header name
        `values` - one or more header values

    - #### headers

          public MockHttpServletRequestBuilder headers(HttpHeaders httpHeaders)

      Add all headers to the request. Values are always added.
      Parameters:
        `httpHeaders` - the headers and values to add

    - #### contentType

          public MockHttpServletRequestBuilder contentType(MediaType mediaType)

      Set the 'Content-Type' header of the request.
      Parameters:
        `mediaType` - the content type

    - #### accept

          public MockHttpServletRequestBuilder accept(MediaType... mediaTypes)

      Set the 'Accept' header to the given media type(s).
      Parameters:
        `mediaTypes` - one or more media types

    - #### content

          public MockHttpServletRequestBuilder content(byte[] content)

      Set the request body.
      Parameters:
        `content` - the body content

    - #### content

          public MockHttpServletRequestBuilder content(String content)

      Set the request body as a UTF-8 String.
      Parameters:
        `content` - the body content

    - #### cookie

          public MockHttpServletRequestBuilder cookie(Cookie... cookies)

      Add the given cookies to the request. Cookies are always added.
      Parameters:
        `cookies` - the cookies to add

    - #### locale

          public MockHttpServletRequestBuilder locale(Locale locale)

      Set the locale of the request.
      Parameters:
        `locale` - the locale

    - #### characterEncoding

          public MockHttpServletRequestBuilder characterEncoding(String encoding)

      Set the character encoding of the request.
      Parameters:
        `encoding` - the character encoding

    - #### requestAttr

          public MockHttpServletRequestBuilder requestAttr(String name,
                                                  Object value)

      Set a request attribute.
      Parameters:
        `name` - the attribute name
        `value` - the attribute value

    - #### sessionAttr

          public MockHttpServletRequestBuilder sessionAttr(String name,
                                                  Object value)

      Set a session attribute.
      Parameters:
        `name` - the session attribute name
        `value` - the session attribute value

    - #### sessionAttrs

          public MockHttpServletRequestBuilder sessionAttrs(Map<String,Object> sessionAttributes)

      Set session attributes.
      Parameters:
        `sessionAttributes` - the session attributes

    - #### flashAttr

          public MockHttpServletRequestBuilder flashAttr(String name,
                                                Object value)

      Set an "input" flash attribute.
      Parameters:
        `name` - the flash attribute name
        `value` - the flash attribute value

    - #### flashAttrs

          public MockHttpServletRequestBuilder flashAttrs(Map<String,Object> flashAttributes)

      Set flash attributes.
      Parameters:
        `flashAttributes` - the flash attributes

    - #### session

          public MockHttpServletRequestBuilder session(MockHttpSession session)

      Set the HTTP session to use, possibly re-used across requests.

      Individual attributes provided via `sessionAttr(String, Object)` override the content of the session provided here.

      Parameters:
        `session` - the HTTP session

    - #### principal

          public MockHttpServletRequestBuilder principal(Principal principal)

      Set the principal of the request.
      Parameters:
        `principal` - the principal

    - #### contextPath

          public MockHttpServletRequestBuilder contextPath(String contextPath)

      Specify the portion of the requestURI that represents the context path. The context path, if specified, must match to the start of the request URI.

      In most cases, tests can be written by omitting the context path from the requestURI. This is because most applications don't actually depend on the name under which they're deployed. If specified here, the context path must start with a "/" and must not end with a "/".

      See Also:
        HttpServletRequest.getContextPath()

    - #### servletPath

          public MockHttpServletRequestBuilder servletPath(String servletPath)

      Specify the portion of the requestURI that represents the path to which the Servlet is mapped. This is typically a portion of the requestURI after the context path.

      In most cases, tests can be written by omitting the servlet path from the requestURI. This is because most applications don't actually depend on the prefix to which a servlet is mapped. For example if a Servlet is mapped to `"/main/*"`, tests can be written with the requestURI `"/accounts/1"` as opposed to `"/main/accounts/1"`. If specified here, the servletPath must start with a "/" and must not end with a "/".

      See Also:
        HttpServletRequest.getServletPath()

    - #### pathInfo

          public MockHttpServletRequestBuilder pathInfo(String pathInfo)

      Specify the portion of the requestURI that represents the pathInfo.

      If left unspecified (recommended), the pathInfo will be automatically derived by removing the contextPath and the servletPath from the requestURI and using any remaining part. If specified here, the pathInfo must start with a "/".

      If specified, the pathInfo will be used as is.

      See Also:
        HttpServletRequest.getServletPath()

    - #### secure

          public MockHttpServletRequestBuilder secure(boolean secure)

      Set the secure property of the `ServletRequest` indicating use of a secure channel, such as HTTPS.
      Parameters:
        `secure` - whether the request is using a secure channel

    - #### with

          public MockHttpServletRequestBuilder with(RequestPostProcessor postProcessor)

      An extension point for further initialization of `MockHttpServletRequest` in ways not built directly into the `MockHttpServletRequestBuilder`. Implementation of this interface can have builder-style methods themselves and be made accessible through static factory methods.
      Parameters:
        `postProcessor` - a post-processor to add

    - #### isMergeEnabled

          public boolean isMergeEnabled()

      Is merging enabled for this particular instance?
      Specified by:
        `isMergeEnabled` in interface `Mergeable`
      Returns:
        always returns `true`.

    - #### merge

          public Object merge(Object parent)

      Merges the properties of the "parent" RequestBuilder accepting values only if not already set in "this" instance.
      Specified by:
        `merge` in interface `Mergeable`
      Parameters:
        `parent` - the parent `RequestBuilder` to inherit properties from
      Returns:
        the result of the merge

    - #### buildRequest

          public final MockHttpServletRequest buildRequest(ServletContext servletContext)

      Build a `MockHttpServletRequest`.
      Specified by:
        `buildRequest` in interface `RequestBuilder`
      Parameters:
        `servletContext` - the `ServletContext` to use to create the request
      Returns:
        the request

    - #### createServletRequest

          protected MockHttpServletRequest createServletRequest(ServletContext servletContext)

      Creates a new `MockHttpServletRequest` based on the given `ServletContext`. Can be overridden in sub-classes.