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

org.springframework.web.servlet.mvc.condition

## Class ProducesRequestCondition

- java.lang.Object
- - org.springframework.web.servlet.mvc.condition.AbstractRequestCondition<ProducesRequestCondition>
  - - org.springframework.web.servlet.mvc.condition.ProducesRequestCondition

- All Implemented Interfaces:
    RequestCondition<ProducesRequestCondition>

      public final class ProducesRequestCondition
      extends AbstractRequestCondition<ProducesRequestCondition>

  A logical disjunction (' || ') request condition to match a request's 'Accept' header to a list of media type expressions. Two kinds of media type expressions are supported, which are described in `RequestMapping.produces()` and `RequestMapping.headers()` where the header name is 'Accept'. Regardless of which syntax is used, the semantics are the same.
  Since:
    3.1
  Author:
    Arjen Poutsma, Rossen Stoyanchev

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ProducesRequestCondition(String... produces)` Creates a new instance from "produces" expressions.
    `ProducesRequestCondition(String[] produces, String[] headers)` Creates a new instance with "produces" and "header" expressions.
    `ProducesRequestCondition(String[] produces, String[] headers, ContentNegotiationManager manager)` Same as `ProducesRequestCondition(String[], String[])` but also accepting a `ContentNegotiationManager`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ProducesRequestCondition` | `combine(ProducesRequestCondition other)` Returns the "other" instance if it has any expressions; returns "this" instance otherwise.
    `int` | `compareTo(ProducesRequestCondition other, HttpServletRequest request)` Compares this and another "produces" condition as follows: Sort 'Accept' header media types by quality value via `MediaType.sortByQualityValue(List)` and iterate the list.
    `protected List<org.springframework.web.servlet.mvc.condition.ProducesRequestCondition.ProduceMediaTypeExpression>` | `getContent()` Return the discrete items a request condition is composed of.
    `Set<MediaTypeExpression>` | `getExpressions()` Return the contained "produces" expressions.
    `ProducesRequestCondition` | `getMatchingCondition(HttpServletRequest request)` Checks if any of the contained media type expressions match the given request 'Content-Type' header and returns an instance that is guaranteed to contain matching expressions only.
    `Set<MediaType>` | `getProducibleMediaTypes()` Return the contained producible media types excluding negated expressions.
    `protected String` | `getToStringInfix()` The notation to use when printing discrete items of content.
    `boolean` | `isEmpty()` Whether the condition has any media type expressions.

    - ### Methods inherited from class org.springframework.web.servlet.mvc.condition.AbstractRequestCondition

      `equals, hashCode, toString`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ProducesRequestCondition

          public ProducesRequestCondition(String... produces)

      Creates a new instance from "produces" expressions. If 0 expressions are provided in total, this condition will match to any request.
      Parameters:
        `produces` - expressions with syntax defined by `RequestMapping.produces()`

    - #### ProducesRequestCondition

          public ProducesRequestCondition(String[] produces,
                                  String[] headers)

      Creates a new instance with "produces" and "header" expressions. "Header" expressions where the header name is not 'Accept' or have no header value defined are ignored. If 0 expressions are provided in total, this condition will match to any request.
      Parameters:
        `produces` - expressions with syntax defined by `RequestMapping.produces()`
        `headers` - expressions with syntax defined by `RequestMapping.headers()`

    - #### ProducesRequestCondition

          public ProducesRequestCondition(String[] produces,
                                  String[] headers,
                                  ContentNegotiationManager manager)

      Same as `ProducesRequestCondition(String[], String[])` but also accepting a `ContentNegotiationManager`.
      Parameters:
        `produces` - expressions with syntax defined by `RequestMapping.produces()`
        `headers` - expressions with syntax defined by `RequestMapping.headers()`
        `manager` - used to determine requested media types

  - ### Method Detail

    - #### getExpressions

          public Set<MediaTypeExpression> getExpressions()

      Return the contained "produces" expressions.

    - #### getProducibleMediaTypes

          public Set<MediaType> getProducibleMediaTypes()

      Return the contained producible media types excluding negated expressions.

    - #### isEmpty

          public boolean isEmpty()

      Whether the condition has any media type expressions.

    - #### getContent

          protected List<org.springframework.web.servlet.mvc.condition.ProducesRequestCondition.ProduceMediaTypeExpression> getContent()

      Description copied from class: `AbstractRequestCondition`
      Return the discrete items a request condition is composed of. For example URL patterns, HTTP request methods, param expressions, etc.
      Specified by:
        `getContent` in class `AbstractRequestCondition<ProducesRequestCondition>`
      Returns:
        a collection of objects, never `null`

    - #### getToStringInfix

          protected String getToStringInfix()

      Description copied from class: `AbstractRequestCondition`
      The notation to use when printing discrete items of content. For example " || " for URL patterns or " && " for param expressions.
      Specified by:
        `getToStringInfix` in class `AbstractRequestCondition<ProducesRequestCondition>`

    - #### combine

          public ProducesRequestCondition combine(ProducesRequestCondition other)

      Returns the "other" instance if it has any expressions; returns "this" instance otherwise. Practically that means a method-level "produces" overrides a type-level "produces" condition.
      Parameters:
        `other` - the condition to combine with.
      Returns:
        a request condition instance that is the result of combining the two condition instances.

    - #### getMatchingCondition

          public ProducesRequestCondition getMatchingCondition(HttpServletRequest request)

      Checks if any of the contained media type expressions match the given request 'Content-Type' header and returns an instance that is guaranteed to contain matching expressions only. The match is performed via `MediaType.isCompatibleWith(MediaType)`.
      Parameters:
        `request` - the current request
      Returns:
        the same instance if there are no expressions; or a new condition with matching expressions; or `null` if no expressions match.

    - #### compareTo

          public int compareTo(ProducesRequestCondition other,
                      HttpServletRequest request)

      Compares this and another "produces" condition as follows:
      1. Sort 'Accept' header media types by quality value via `MediaType.sortByQualityValue(List)` and iterate the list.
      2. Get the first index of matching media types in each "produces" condition first matching with `MediaType.equals(Object)` and then with `MediaType.includes(MediaType)`.
      3. If a lower index is found, the condition at that index wins.
      4. If both indexes are equal, the media types at the index are compared further with `MediaType.SPECIFICITY_COMPARATOR`.

      It is assumed that both instances have been obtained via `getMatchingCondition(HttpServletRequest)` and each instance contains the matching producible media type expression only or is otherwise empty.