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

org.springframework.http

## Class MediaType

- java.lang.Object
- - org.springframework.http.MediaType

- All Implemented Interfaces:
    Comparable<MediaType>

      public class MediaType
      extends Object
      implements Comparable<MediaType>

  Represents an Internet Media Type, as defined in the HTTP specification.

  Consists of a type and a subtype. Also has functionality to parse media types from a string using `parseMediaType(String)`, or multiple comma-separated media types using `parseMediaTypes(String)`.

  Since:
    3.0
  Author:
    Arjen Poutsma, Juergen Hoeller, Rossen Stoyanchev
  See Also:
    HTTP 1.1, section 3.7

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static MediaType` | `ALL` Public constant media type that includes all media ranges (i.e.
    `static String` | `ALL_VALUE` A String equivalent of `ALL`.
    `static MediaType` | `APPLICATION_ATOM_XML` Public constant media type for `application/atom+xml`.
    `static String` | `APPLICATION_ATOM_XML_VALUE` A String equivalent of `APPLICATION_ATOM_XML`.
    `static MediaType` | `APPLICATION_FORM_URLENCODED` Public constant media type for `application/x-www-form-urlencoded`.
    `static String` | `APPLICATION_FORM_URLENCODED_VALUE` A String equivalent of `APPLICATION_FORM_URLENCODED`.
    `static MediaType` | `APPLICATION_JSON` Public constant media type for `application/json`.
    `static String` | `APPLICATION_JSON_VALUE` A String equivalent of `APPLICATION_JSON`.
    `static MediaType` | `APPLICATION_OCTET_STREAM` Public constant media type for `application/octet-stream`.
    `static String` | `APPLICATION_OCTET_STREAM_VALUE` A String equivalent of `APPLICATION_OCTET_STREAM`.
    `static MediaType` | `APPLICATION_XHTML_XML` Public constant media type for `application/xhtml+xml`.
    `static String` | `APPLICATION_XHTML_XML_VALUE` A String equivalent of `APPLICATION_XHTML_XML`.
    `static MediaType` | `APPLICATION_XML` Public constant media type for `application/xml`.
    `static String` | `APPLICATION_XML_VALUE` A String equivalent of `APPLICATION_XML`.
    `static MediaType` | `IMAGE_GIF` Public constant media type for `image/gif`.
    `static String` | `IMAGE_GIF_VALUE` A String equivalent of `IMAGE_GIF`.
    `static MediaType` | `IMAGE_JPEG` Public constant media type for `image/jpeg`.
    `static String` | `IMAGE_JPEG_VALUE` A String equivalent of `IMAGE_JPEG`.
    `static MediaType` | `IMAGE_PNG` Public constant media type for `image/png`.
    `static String` | `IMAGE_PNG_VALUE` A String equivalent of `IMAGE_PNG`.
    `static MediaType` | `MULTIPART_FORM_DATA` Public constant media type for `multipart/form-data`.
    `static String` | `MULTIPART_FORM_DATA_VALUE` A String equivalent of `MULTIPART_FORM_DATA`.
    `static Comparator<MediaType>` | `QUALITY_VALUE_COMPARATOR` Comparator used by `sortByQualityValue(List)`.
    `static Comparator<MediaType>` | `SPECIFICITY_COMPARATOR` Comparator used by `sortBySpecificity(List)`.
    `static MediaType` | `TEXT_HTML` Public constant media type for `text/html`.
    `static String` | `TEXT_HTML_VALUE` A String equivalent of `TEXT_HTML`.
    `static MediaType` | `TEXT_PLAIN` Public constant media type for `text/plain`.
    `static String` | `TEXT_PLAIN_VALUE` A String equivalent of `TEXT_PLAIN`.
    `static MediaType` | `TEXT_XML` Public constant media type for `text/xml`.
    `static String` | `TEXT_XML_VALUE` A String equivalent of `TEXT_XML`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MediaType(MediaType other, Map<String,String> parameters)` Copy-constructor that copies the type and subtype of the given `MediaType`, and allows for different parameter.
    `MediaType(String type)` Create a new `MediaType` for the given primary type.
    `MediaType(String type, String subtype)` Create a new `MediaType` for the given primary type and subtype.
    `MediaType(String type, String subtype, Charset charSet)` Create a new `MediaType` for the given type, subtype, and character set.
    `MediaType(String type, String subtype, double qualityValue)` Create a new `MediaType` for the given type, subtype, and quality value.
    `MediaType(String type, String subtype, Map<String,String> parameters)` Create a new `MediaType` for the given type, subtype, and parameters.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(MediaType other)` Compares this `MediaType` to another alphabetically.
    `MediaType` | `copyQualityValue(MediaType mediaType)` Return a replica of this instance with the quality value of the given MediaType.
    `boolean` | `equals(Object other)`
    `Charset` | `getCharSet()` Return the character set, as indicated by a `charset` parameter, if any.
    `String` | `getParameter(String name)` Return a generic parameter value, given a parameter name.
    `Map<String,String>` | `getParameters()` Return all generic parameter values.
    `double` | `getQualityValue()` Return the quality value, as indicated by a `q` parameter, if any.
    `String` | `getSubtype()` Return the subtype.
    `String` | `getType()` Return the primary type.
    `int` | `hashCode()`
    `boolean` | `includes(MediaType other)` Indicate whether this `MediaType` includes the given media type.
    `boolean` | `isCompatibleWith(MediaType other)` Indicate whether this `MediaType` is compatible with the given media type.
    `boolean` | `isConcrete()` Indicates whether this media type is concrete, i.e.
    `boolean` | `isWildcardSubtype()` Indicates whether the subtype is the wildcard character `&#42;` or the wildcard character followed by a sufiix (e.g.
    `boolean` | `isWildcardType()` Indicates whether the type is the wildcard character `&#42;` or not.
    `static MediaType` | `parseMediaType(String mediaType)` Parse the given String into a single `MediaType`.
    `static List<MediaType>` | `parseMediaTypes(String mediaTypes)` Parse the given, comma-separated string into a list of `MediaType` objects.
    `MediaType` | `removeQualityValue()` Return a replica of this instance with its quality value removed.
    `static void` | `sortByQualityValue(List<MediaType> mediaTypes)` Sorts the given list of `MediaType` objects by quality value.
    `static void` | `sortBySpecificity(List<MediaType> mediaTypes)` Sorts the given list of `MediaType` objects by specificity.
    `static void` | `sortBySpecificityAndQuality(List<MediaType> mediaTypes)` Sorts the given list of `MediaType` objects by specificity as the primary criteria and quality value the secondary.
    `String` | `toString()`
    `static String` | `toString(Collection<MediaType> mediaTypes)` Return a string representation of the given list of `MediaType` objects.
    `static MediaType` | `valueOf(String value)` Parse the given String value into a `MediaType` object, with this method name following the 'valueOf' naming convention (as supported by `ConversionService`.

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

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

- - ### Field Detail

    - #### ALL

          public static final MediaType ALL

      Public constant media type that includes all media ranges (i.e. `&#42;/&#42;`).

    - #### ALL_VALUE

          public static final String ALL_VALUE

      A String equivalent of `ALL`.
      See Also:
        Constant Field Values

    - #### APPLICATION_ATOM_XML

          public static final MediaType APPLICATION_ATOM_XML

      Public constant media type for `application/atom+xml`.

    - #### APPLICATION_ATOM_XML_VALUE

          public static final String APPLICATION_ATOM_XML_VALUE

      A String equivalent of `APPLICATION_ATOM_XML`.
      See Also:
        Constant Field Values

    - #### APPLICATION_FORM_URLENCODED

          public static final MediaType APPLICATION_FORM_URLENCODED

      Public constant media type for `application/x-www-form-urlencoded`.

    - #### APPLICATION_FORM_URLENCODED_VALUE

          public static final String APPLICATION_FORM_URLENCODED_VALUE

      A String equivalent of `APPLICATION_FORM_URLENCODED`.
      See Also:
        Constant Field Values

    - #### APPLICATION_JSON

          public static final MediaType APPLICATION_JSON

      Public constant media type for `application/json`.

    - #### APPLICATION_JSON_VALUE

          public static final String APPLICATION_JSON_VALUE

      A String equivalent of `APPLICATION_JSON`.
      See Also:
        Constant Field Values

    - #### APPLICATION_OCTET_STREAM

          public static final MediaType APPLICATION_OCTET_STREAM

      Public constant media type for `application/octet-stream`.

    - #### APPLICATION_OCTET_STREAM_VALUE

          public static final String APPLICATION_OCTET_STREAM_VALUE

      A String equivalent of `APPLICATION_OCTET_STREAM`.
      See Also:
        Constant Field Values

    - #### APPLICATION_XHTML_XML

          public static final MediaType APPLICATION_XHTML_XML

      Public constant media type for `application/xhtml+xml`.

    - #### APPLICATION_XHTML_XML_VALUE

          public static final String APPLICATION_XHTML_XML_VALUE

      A String equivalent of `APPLICATION_XHTML_XML`.
      See Also:
        Constant Field Values

    - #### APPLICATION_XML

          public static final MediaType APPLICATION_XML

      Public constant media type for `application/xml`.

    - #### APPLICATION_XML_VALUE

          public static final String APPLICATION_XML_VALUE

      A String equivalent of `APPLICATION_XML`.
      See Also:
        Constant Field Values

    - #### IMAGE_GIF

          public static final MediaType IMAGE_GIF

      Public constant media type for `image/gif`.

    - #### IMAGE_GIF_VALUE

          public static final String IMAGE_GIF_VALUE

      A String equivalent of `IMAGE_GIF`.
      See Also:
        Constant Field Values

    - #### IMAGE_JPEG

          public static final MediaType IMAGE_JPEG

      Public constant media type for `image/jpeg`.

    - #### IMAGE_JPEG_VALUE

          public static final String IMAGE_JPEG_VALUE

      A String equivalent of `IMAGE_JPEG`.
      See Also:
        Constant Field Values

    - #### IMAGE_PNG

          public static final MediaType IMAGE_PNG

      Public constant media type for `image/png`.

    - #### IMAGE_PNG_VALUE

          public static final String IMAGE_PNG_VALUE

      A String equivalent of `IMAGE_PNG`.
      See Also:
        Constant Field Values

    - #### MULTIPART_FORM_DATA

          public static final MediaType MULTIPART_FORM_DATA

      Public constant media type for `multipart/form-data`.

    - #### MULTIPART_FORM_DATA_VALUE

          public static final String MULTIPART_FORM_DATA_VALUE

      A String equivalent of `MULTIPART_FORM_DATA`.
      See Also:
        Constant Field Values

    - #### TEXT_HTML

          public static final MediaType TEXT_HTML

      Public constant media type for `text/html`.

    - #### TEXT_HTML_VALUE

          public static final String TEXT_HTML_VALUE

      A String equivalent of `TEXT_HTML`.
      See Also:
        Constant Field Values

    - #### TEXT_PLAIN

          public static final MediaType TEXT_PLAIN

      Public constant media type for `text/plain`.

    - #### TEXT_PLAIN_VALUE

          public static final String TEXT_PLAIN_VALUE

      A String equivalent of `TEXT_PLAIN`.
      See Also:
        Constant Field Values

    - #### TEXT_XML

          public static final MediaType TEXT_XML

      Public constant media type for `text/xml`.

    - #### TEXT_XML_VALUE

          public static final String TEXT_XML_VALUE

      A String equivalent of `TEXT_XML`.
      See Also:
        Constant Field Values

    - #### SPECIFICITY_COMPARATOR

          public static final Comparator<MediaType> SPECIFICITY_COMPARATOR

      Comparator used by `sortBySpecificity(List)`.

    - #### QUALITY_VALUE_COMPARATOR

          public static final Comparator<MediaType> QUALITY_VALUE_COMPARATOR

      Comparator used by `sortByQualityValue(List)`.

  - ### Constructor Detail

    - #### MediaType

          public MediaType(String type)

      Create a new `MediaType` for the given primary type.

      The subtype is set to `&#42;`, parameters empty.

      Parameters:
        `type` - the primary type
      Throws:
        `IllegalArgumentException` - if any of the parameters contain illegal characters

    - #### MediaType

          public MediaType(String type,
                   String subtype)

      Create a new `MediaType` for the given primary type and subtype.

      The parameters are empty.

      Parameters:
        `type` - the primary type
        `subtype` - the subtype
      Throws:
        `IllegalArgumentException` - if any of the parameters contain illegal characters

    - #### MediaType

          public MediaType(String type,
                   String subtype,
                   Charset charSet)

      Create a new `MediaType` for the given type, subtype, and character set.
      Parameters:
        `type` - the primary type
        `subtype` - the subtype
        `charSet` - the character set
      Throws:
        `IllegalArgumentException` - if any of the parameters contain illegal characters

    - #### MediaType

          public MediaType(String type,
                   String subtype,
                   double qualityValue)

      Create a new `MediaType` for the given type, subtype, and quality value.
      Parameters:
        `type` - the primary type
        `subtype` - the subtype
        `qualityValue` - the quality value
      Throws:
        `IllegalArgumentException` - if any of the parameters contain illegal characters

    - #### MediaType

          public MediaType(MediaType other,
                   Map<String,String> parameters)

      Copy-constructor that copies the type and subtype of the given `MediaType`, and allows for different parameter.
      Parameters:
        `other` - the other media type
        `parameters` - the parameters, may be `null`
      Throws:
        `IllegalArgumentException` - if any of the parameters contain illegal characters

    - #### MediaType

          public MediaType(String type,
                   String subtype,
                   Map<String,String> parameters)

      Create a new `MediaType` for the given type, subtype, and parameters.
      Parameters:
        `type` - the primary type
        `subtype` - the subtype
        `parameters` - the parameters, may be `null`
      Throws:
        `IllegalArgumentException` - if any of the parameters contain illegal characters

  - ### Method Detail

    - #### getType

          public String getType()

      Return the primary type.

    - #### isWildcardType

          public boolean isWildcardType()

      Indicates whether the type is the wildcard character `&#42;` or not.

    - #### getSubtype

          public String getSubtype()

      Return the subtype.

    - #### isWildcardSubtype

          public boolean isWildcardSubtype()

      Indicates whether the subtype is the wildcard character `&#42;` or the wildcard character followed by a sufiix (e.g. `&#42;+xml`), or not.
      Returns:
        whether the subtype is `&#42;`

    - #### isConcrete

          public boolean isConcrete()

      Indicates whether this media type is concrete, i.e. whether neither the type or subtype is a wildcard character `&#42;`.
      Returns:
        whether this media type is concrete

    - #### getCharSet

          public Charset getCharSet()

      Return the character set, as indicated by a `charset` parameter, if any.
      Returns:
        the character set; or `null` if not available

    - #### getQualityValue

          public double getQualityValue()

      Return the quality value, as indicated by a `q` parameter, if any. Defaults to `1.0`.
      Returns:
        the quality factory

    - #### getParameter

          public String getParameter(String name)

      Return a generic parameter value, given a parameter name.
      Parameters:
        `name` - the parameter name
      Returns:
        the parameter value; or `null` if not present

    - #### getParameters

          public Map<String,String> getParameters()

      Return all generic parameter values.
      Returns:
        a read-only map, possibly empty, never `null`

    - #### includes

          public boolean includes(MediaType other)

      Indicate whether this `MediaType` includes the given media type.

      For instance, `text/*` includes `text/plain` and `text/html`, and `application/*+xml` includes `application/soap+xml`, etc. This method is not symmetric.

      Parameters:
        `other` - the reference media type with which to compare
      Returns:
        `true` if this media type includes the given media type; `false` otherwise

    - #### isCompatibleWith

          public boolean isCompatibleWith(MediaType other)

      Indicate whether this `MediaType` is compatible with the given media type.

      For instance, `text/*` is compatible with `text/plain`, `text/html`, and vice versa. In effect, this method is similar to `includes(MediaType)`, except that it is symmetric.

      Parameters:
        `other` - the reference media type with which to compare
      Returns:
        `true` if this media type is compatible with the given media type; `false` otherwise

    - #### copyQualityValue

          public MediaType copyQualityValue(MediaType mediaType)

      Return a replica of this instance with the quality value of the given MediaType.
      Returns:
        the same instance if the given MediaType doesn't have a quality value, or a new one otherwise

    - #### removeQualityValue

          public MediaType removeQualityValue()

      Return a replica of this instance with its quality value removed.
      Returns:
        the same instance if the media type doesn't contain a quality value, or a new one otherwise

    - #### compareTo

          public int compareTo(MediaType other)

      Compares this `MediaType` to another alphabetically.
      Specified by:
        `compareTo` in interface `Comparable<MediaType>`
      Parameters:
        `other` - media type to compare to
      See Also:
        `sortBySpecificity(List)`

    - #### equals

          public boolean equals(Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### valueOf

          public static MediaType valueOf(String value)

      Parse the given String value into a `MediaType` object, with this method name following the 'valueOf' naming convention (as supported by `ConversionService`.
      See Also:
        `parseMediaType(String)`

    - #### parseMediaType

          public static MediaType parseMediaType(String mediaType)

      Parse the given String into a single `MediaType`.
      Parameters:
        `mediaType` - the string to parse
      Returns:
        the media type
      Throws:
        `IllegalArgumentException` - if the string cannot be parsed

    - #### parseMediaTypes

          public static List<MediaType> parseMediaTypes(String mediaTypes)

      Parse the given, comma-separated string into a list of `MediaType` objects.

      This method can be used to parse an Accept or Content-Type header.

      Parameters:
        `mediaTypes` - the string to parse
      Returns:
        the list of media types
      Throws:
        `IllegalArgumentException` - if the string cannot be parsed

    - #### toString

          public static String toString(Collection<MediaType> mediaTypes)

      Return a string representation of the given list of `MediaType` objects.

      This method can be used to for an `Accept` or `Content-Type` header.

      Parameters:
        `mediaTypes` - the string to parse
      Returns:
        the list of media types
      Throws:
        `IllegalArgumentException` - if the String cannot be parsed

    - #### sortBySpecificity

          public static void sortBySpecificity(List<MediaType> mediaTypes)

      Sorts the given list of `MediaType` objects by specificity.

      Given two media types:

      1. if either media type has a wildcard type, then the media type without the wildcard is ordered before the other.
      2. if the two media types have different types, then they are considered equal and remain their current order.
      3. if either media type has a wildcard subtype, then the media type without the wildcard is sorted before the other.
      4. if the two media types have different subtypes, then they are considered equal and remain their current order.
      5. if the two media types have different quality value, then the media type with the highest quality value is ordered before the other.
      6. if the two media types have a different amount of parameters, then the media type with the most parameters is ordered before the other.

      For example:

      > audio/basic < audio/* < */*

      > audio/* < audio/*;q=0.7; audio/*;q=0.3

      > audio/basic;level=1 < audio/basic

      > audio/basic == text/html

      > audio/basic == audio/wave

      Parameters:
        `mediaTypes` - the list of media types to be sorted
      See Also:
        HTTP 1.1, section 14.1

    - #### sortByQualityValue

          public static void sortByQualityValue(List<MediaType> mediaTypes)

      Sorts the given list of `MediaType` objects by quality value.

      Given two media types:

      1. if the two media types have different quality value, then the media type with the highest quality value is ordered before the other.
      2. if either media type has a wildcard type, then the media type without the wildcard is ordered before the other.
      3. if the two media types have different types, then they are considered equal and remain their current order.
      4. if either media type has a wildcard subtype, then the media type without the wildcard is sorted before the other.
      5. if the two media types have different subtypes, then they are considered equal and remain their current order.
      6. if the two media types have a different amount of parameters, then the media type with the most parameters is ordered before the other.
      Parameters:
        `mediaTypes` - the list of media types to be sorted
      See Also:
        `getQualityValue()`

    - #### sortBySpecificityAndQuality

          public static void sortBySpecificityAndQuality(List<MediaType> mediaTypes)

      Sorts the given list of `MediaType` objects by specificity as the primary criteria and quality value the secondary.
      See Also:
        `sortBySpecificity(List)`, `sortByQualityValue(List)`