Package com.google.common.net

Class MediaType

  • @Beta
@GwtCompatible
public final class MediaType
extends java.lang.Object
    Represents an Internet Media Type (also known as a MIME Type or Content Type). This class also supports the concept of media ranges defined by HTTP/1.1. As such, the * character is treated as a wildcard and is used to represent any acceptable type or subtype value. A media type may not have wildcard type with a declared subtype. The * character has no special meaning as part of a parameter. All values for type, subtype, parameter attributes or parameter values must be valid according to RFCs 2045 and 2046.

    All portions of the media type that are case-insensitive (type, subtype, parameter attributes) are normalized to lowercase. The value of the charset parameter is normalized to lowercase, but all others are left as-is.

    Note that this specifically does not represent the value of the MIME Content-Type header and as such has no support for header-specific considerations such as line folding and comments.

    For media types that take a charset the predefined constants default to UTF-8 and have a "_UTF_8" suffix. To get a version without a character set, use withoutParameters().

    Since:
    12.0

    • Constructor Detail

      • MediaType

        private MediaType​(java.lang.String type,
                  java.lang.String subtype,
                  ImmutableListMultimap<java.lang.String,​java.lang.String> parameters)

    • Method Detail

      • createConstant

        private static MediaType createConstant​(java.lang.String type,
                                        java.lang.String subtype)

      • createConstantUtf8

        private static MediaType createConstantUtf8​(java.lang.String type,
                                            java.lang.String subtype)

      • type

        public java.lang.String type()
        Returns the top-level media type. For example, "text" in "text/plain".

      • subtype

        public java.lang.String subtype()
        Returns the media subtype. For example, "plain" in "text/plain".

      • parameters

        public ImmutableListMultimap<java.lang.String,​java.lang.String> parameters()
        Returns a multimap containing the parameters of this media type.

      • parametersAsMap

        private java.util.Map<java.lang.String,​ImmutableMultiset<java.lang.String>> parametersAsMap()

      • charset

        public Optional<java.nio.charset.Charset> charset()
        Returns an optional charset for the value of the charset parameter if it is specified.
        Throws:
        java.lang.IllegalStateException - if multiple charset values have been set for this media type
        java.nio.charset.IllegalCharsetNameException - if a charset value is present, but illegal
        java.nio.charset.UnsupportedCharsetException - if a charset value is present, but no support is available in this instance of the Java virtual machine

      • withoutParameters

        public MediaType withoutParameters()
        Returns a new instance with the same type and subtype as this instance, but without any parameters.

      • withParameters

        public MediaType withParameters​(Multimap<java.lang.String,​java.lang.String> parameters)
        Replaces all parameters with the given parameters.
        Throws:
        java.lang.IllegalArgumentException - if any parameter or value is invalid

      • withParameters

        public MediaType withParameters​(java.lang.String attribute,
                                java.lang.Iterable<java.lang.String> values)
        Replaces all parameters with the given attribute with parameters using the given values. If there are no values, any existing parameters with the given attribute are removed.
        Throws:
        java.lang.IllegalArgumentException - if either attribute or values is invalid
        Since:
        24.0

      • withParameter

        public MediaType withParameter​(java.lang.String attribute,
                               java.lang.String value)
        Replaces all parameters with the given attribute with a single parameter with the given value. If multiple parameters with the same attributes are necessary use withParameters(String, Iterable). Prefer withCharset(java.nio.charset.Charset) for setting the charset parameter when using a Charset object.
        Throws:
        java.lang.IllegalArgumentException - if either attribute or value is invalid

      • withCharset

        public MediaType withCharset​(java.nio.charset.Charset charset)
        Returns a new instance with the same type and subtype as this instance, with the charset parameter set to the name of the given charset. Only one charset parameter will be present on the new instance regardless of the number set on this one.

        If a charset must be specified that is not supported on this JVM (and thus is not representable as a Charset instance, use withParameter(java.lang.String, java.lang.String).

      • hasWildcard

        public boolean hasWildcard()
        Returns true if either the type or subtype is the wildcard.

      • is

        public boolean is​(MediaType mediaTypeRange)
        Returns true if this instance falls within the range (as defined by the HTTP Accept header) given by the argument according to three criteria:
        1. The type of the argument is the wildcard or equal to the type of this instance.
        2. The subtype of the argument is the wildcard or equal to the subtype of this instance.
        3. All of the parameters present in the argument are present in this instance.

        For example: 

        
 PLAIN_TEXT_UTF_8.is(PLAIN_TEXT_UTF_8) // true
 PLAIN_TEXT_UTF_8.is(HTML_UTF_8) // false
 PLAIN_TEXT_UTF_8.is(ANY_TYPE) // true
 PLAIN_TEXT_UTF_8.is(ANY_TEXT_TYPE) // true
 PLAIN_TEXT_UTF_8.is(ANY_IMAGE_TYPE) // false
 PLAIN_TEXT_UTF_8.is(ANY_TEXT_TYPE.withCharset(UTF_8)) // true
 PLAIN_TEXT_UTF_8.withoutParameters().is(ANY_TEXT_TYPE.withCharset(UTF_8)) // false
 PLAIN_TEXT_UTF_8.is(ANY_TEXT_TYPE.withCharset(UTF_16)) // false

        Note that while it is possible to have the same parameter declared multiple times within a media type this method does not consider the number of occurrences of a parameter. For example, "text/plain; charset=UTF-8" satisfies "text/plain; charset=UTF-8; charset=UTF-8".

      • create

        public static MediaType create​(java.lang.String type,
                               java.lang.String subtype)
        Creates a new media type with the given type and subtype.
        Throws:
        java.lang.IllegalArgumentException - if type or subtype is invalid or if a wildcard is used for the type, but not the subtype.

      • create

        private static MediaType create​(java.lang.String type,
                                java.lang.String subtype,
                                Multimap<java.lang.String,​java.lang.String> parameters)

      • createApplicationType

        static MediaType createApplicationType​(java.lang.String subtype)
        Creates a media type with the "application" type and the given subtype.
        Throws:
        java.lang.IllegalArgumentException - if subtype is invalid

      • createAudioType

        static MediaType createAudioType​(java.lang.String subtype)
        Creates a media type with the "audio" type and the given subtype.
        Throws:
        java.lang.IllegalArgumentException - if subtype is invalid

      • createImageType

        static MediaType createImageType​(java.lang.String subtype)
        Creates a media type with the "image" type and the given subtype.
        Throws:
        java.lang.IllegalArgumentException - if subtype is invalid

      • createTextType

        static MediaType createTextType​(java.lang.String subtype)
        Creates a media type with the "text" type and the given subtype.
        Throws:
        java.lang.IllegalArgumentException - if subtype is invalid

      • createVideoType

        static MediaType createVideoType​(java.lang.String subtype)
        Creates a media type with the "video" type and the given subtype.
        Throws:
        java.lang.IllegalArgumentException - if subtype is invalid

      • normalizeToken

        private static java.lang.String normalizeToken​(java.lang.String token)

      • normalizeParameterValue

        private static java.lang.String normalizeParameterValue​(java.lang.String attribute,
                                                        java.lang.String value)

      • parse

        public static MediaType parse​(java.lang.String input)
        Parses a media type from its string representation.
        Throws:
        java.lang.IllegalArgumentException - if the input is not parsable

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Returns the string representation of this media type in the format described in RFC 2045.
        Overrides:
        toString in class java.lang.Object

      • computeToString

        private java.lang.String computeToString()

      • escapeAndQuote

        private static java.lang.String escapeAndQuote​(java.lang.String value)