Package com.globalmentor.net

Class ContentType

  • public class ContentType
extends java.lang.Object
    An encapsulation of an Internet media content type as originally defined in RFC 2046: MIME Part 2: Media Types; and most recently in RFC 6838: Media Type Specifications and Registration Procedures.

    The content type and names of parameters are compared in a case-insensitive manner as per RFC 2046.

    Neither javax.activation.MimeType nor javax.mail.internet.ContentType correctly implements Object.equals(Object) and therefore cannot reliably be used in sets and maps. Furthermore, javax.mail.internet.ContentType as of JDK 6 is not included in default JDK distributions. javax.activation.MimeType was recently added to JDK distributions, so in an earlier implementation this class provided appropriate factory methods, to provide special javax.activation.MimeType instances that provide correct equality checking. Because the javax.activation package is not included in the Android Development Kit, however, and seeing that neither javax.activation.MimeType nor javax.mail.internet.ContentType are in common use, the current implementation provides a fully independent version.

    TODO This implementation does not support quoted values containing the 59 character.

    Author:
    Garret Wilson
    See Also:
    RFC 2046, RFC 6838, XHTML Media Types

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ContentType.Parameter
      A content type parameter name/value pair.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected static <CS extends java.lang.CharSequence>
      CS      		 checkToken​(CS charSequence)
      Checks to ensure that the given character sequence is a content type token, that is, consisting only of non-control ASCII characters with no special characters or spaces.
      static ContentType create​(java.lang.CharSequence charSequence)
      Deprecated.
      in favor of of(CharSequence); to be removed in next major version.
      static ContentType create​(java.lang.String primaryType, java.lang.String subType, ContentType.Parameter... parameters)
      Deprecated.
      in favor of of(String, String, Parameter...); to be removed in next major version.
      static java.lang.String createSubTypeSuffix​(java.lang.String... suffixes)
      Creates a content type suffix by prepending '+' to each suffix and concatenating the suffixes.
      boolean equals​(java.lang.Object object)
      ContentType getBaseContentType()
      Determines the base content type, with no parameters, of the content type.
      java.lang.String getBaseType()
      Deprecated.
      java.lang.String getParameter​(java.lang.String name)
      Retrieve the parameter value associated with the given parameter name.
      java.util.Set<ContentType.Parameter> getParameters()  
      java.lang.String getPrimaryType()  
      java.lang.String getSubType()  
      boolean hasBaseType​(ContentType contentType)
      Checks to see if the given content type has the same primary type and subtype as this content type.
      boolean hasBaseType​(java.lang.String primaryType, java.lang.String subType)
      Matches a content type against a primary type and subtype with no wildcard support.
      int hashCode()
      boolean hasSubTypeSuffix​(java.lang.String... suffixes)
      Determines if the subtype of the content type has the given suffix.
      static boolean isToken​(java.lang.CharSequence charSequence)
      Determines if the given character sequence is a content type token, that is, consisting only of non-control ASCII characters with no special characters or spaces.
      boolean match​(java.lang.Class<?> objectClass)
      Matches a content type against the "application" primary type and "x-java-object" subtype, with a "class" parameter indicating the given object class.
      boolean match​(java.lang.String primaryType, java.lang.String subType)
      Matches a content type against a primary type and subtype.
      boolean match​(java.lang.String primaryType, java.lang.String subType, java.lang.Class<?> objectClass)
      Matches a content type against a primary type and subtype, with a class parameter indicating the given object class.
      static ContentType of​(java.lang.CharSequence charSequence)
      Parses a content type object from a string.
      static ContentType of​(java.lang.String primaryType, java.lang.String subType, ContentType.Parameter... parameters)
      Creates a content type object from primary type, a subtype, and optional parameters.
      static ContentType of​(java.lang.String primaryType, java.lang.String subType, java.util.Set<ContentType.Parameter> parameters)
      Creates a content type object from primary type, a subtype, and optional parameters.
      java.lang.String toString()
      java.lang.String toString​(boolean formatted)
      Returns a possibly formatted string version of the given content type.
      static java.lang.String toString​(java.lang.String primaryType, java.lang.String subType, ContentType.Parameter... parameters)
      Constructs a string representing a content type.
      static java.lang.String toString​(java.lang.String primaryType, java.lang.String subType, java.util.Set<ContentType.Parameter> parameters)
      Constructs a string representing a content type in canonical form.
      static java.lang.String toString​(java.lang.String primaryType, java.lang.String subType, java.util.Set<ContentType.Parameter> parameters, boolean formatted)
      Constructs a string representing a content type.
      ContentType withParameter​(ContentType.Parameter newParameter)
      Returns a content type with the given parameter.
      ContentType withParameter​(java.lang.String name, java.lang.String value)
      Returns a content type with the given parameter.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • TYPE_DIVIDER

        public static final char TYPE_DIVIDER
        The divider character for media type strings.
        See Also:
        Constant Field Values

      • PARAMETER_DELIMITER_CHAR

        public static final char PARAMETER_DELIMITER_CHAR
        The delimiter character separating parameters from the base content type and from each other.
        See Also:
        Constant Field Values

      • PARAMETER_ASSIGNMENT_CHAR

        public static final char PARAMETER_ASSIGNMENT_CHAR
        The character used to assign parameter values.
        See Also:
        Constant Field Values

      • STRING_QUOTE_CHAR

        public static final char STRING_QUOTE_CHAR
        The character for quoting a string, such as a parameter value with special characters.
        See Also:
        Constant Field Values

      • TYPE_WILDCARD_CHAR

        public static final char TYPE_WILDCARD_CHAR
        The wildcard character.
        See Also:
        Constant Field Values

      • WILDCARD_SUBTYPE

        public static final java.lang.String WILDCARD_SUBTYPE
        The wildcard subtype, matching any subtype.

      • SPECIAL_CHARACTERS

        public static final Characters SPECIAL_CHARACTERS
        The tspecials characters of RFC 2046, which require a string to be quoted in a parameter value.

      • ILLEGAL_TOKEN_CHARACTERS

        public static final Characters ILLEGAL_TOKEN_CHARACTERS
        The characters of RFC 2046 which are considered illegal in tokens; control characters and non-ASCII characters are not included.

      • PARAMETERS_PATTERN

        public static final java.util.regex.Pattern PARAMETERS_PATTERN
        A pattern for checking the basic form of parameters. The pattern may be repeated and the two matching groups are the name and value. This pattern does not take into account all aspects of a regular expression, e.g. special characters.

      • PARAMETERS_PATTERN_NAME_GROUP

        public static final int PARAMETERS_PATTERN_NAME_GROUP
        The parameters pattern matching group for the parameter name.
        See Also:
        PARAMETERS_PATTERN, Constant Field Values

      • PARAMETERS_PATTERN_VALUE_GROUP

        public static final int PARAMETERS_PATTERN_VALUE_GROUP
        The parameters pattern matching group for the parameter name.
        See Also:
        PARAMETERS_PATTERN, Constant Field Values

      • PATTERN

        public static final java.util.regex.Pattern PATTERN
        A pattern for checking the basic form of regular expressions. This pattern does not take into account all aspects of a regular expression, e.g. special characters. The parameters group will be null if there are no parameters at all.

      • PATTERN_PRIMARY_TYPE_GROUP

        public static final int PATTERN_PRIMARY_TYPE_GROUP
        The pattern matching group for the primary type.
        See Also:
        PATTERN, Constant Field Values

      • PATTERN_SUBTYPE_GROUP

        public static final int PATTERN_SUBTYPE_GROUP
        The pattern matching group for the subtype.
        See Also:
        PATTERN, Constant Field Values

      • PATTERN_PARAMETERS_GROUP

        public static final int PATTERN_PARAMETERS_GROUP
        The pattern matching group for all the parameters, with delimiters.
        See Also:
        PATTERN, Constant Field Values

      • TEXT_PRIMARY_TYPE

        public static final java.lang.String TEXT_PRIMARY_TYPE
        See Also:
        Constant Field Values

      • IMAGE_PRIMARY_TYPE

        public static final java.lang.String IMAGE_PRIMARY_TYPE
        See Also:
        Constant Field Values

      • AUDIO_PRIMARY_TYPE

        public static final java.lang.String AUDIO_PRIMARY_TYPE
        See Also:
        Constant Field Values

      • VIDEO_PRIMARY_TYPE

        public static final java.lang.String VIDEO_PRIMARY_TYPE
        See Also:
        Constant Field Values

      • APPLICATION_PRIMARY_TYPE

        public static final java.lang.String APPLICATION_PRIMARY_TYPE
        See Also:
        Constant Field Values

      • MULTIPART_PRIMARY_TYPE

        public static final java.lang.String MULTIPART_PRIMARY_TYPE
        See Also:
        Constant Field Values

      • MESSAGE_PRIMARY_TYPE

        public static final java.lang.String MESSAGE_PRIMARY_TYPE
        See Also:
        Constant Field Values

      • CONTENT_PRIMARY_TYPE

        public static final java.lang.String CONTENT_PRIMARY_TYPE
        The pseudo top-level type used by Java URLConnection to indicate unknown content by content/unknown.
        See Also:
        Constant Field Values

      • SUBTYPE_EXTENSION_PREFIX

        public static final java.lang.String SUBTYPE_EXTENSION_PREFIX
        The separator character that begins a non-standard extension type.
        See Also:
        Constant Field Values

      • SUBTYPE_SUFFIX_DELIMITER_CHAR

        public static final char SUBTYPE_SUFFIX_DELIMITER_CHAR
        The separator character that delimits a subtype suffix.
        See Also:
        Constant Field Values

      • CHARSET_PARAMETER

        public static final java.lang.String CHARSET_PARAMETER
        The character set parameters.
        See Also:
        Constant Field Values

      • UNKNOWN_SUBTYPE

        public static final java.lang.String UNKNOWN_SUBTYPE
        The pseudo subtype used by Java URLConnection to indicate unknown content by content/unknown.
        See Also:
        Constant Field Values

      • OCTET_STREAM_SUBTYPE

        public static final java.lang.String OCTET_STREAM_SUBTYPE
        A stream of bytes.
        See Also:
        Constant Field Values

      • X_JAVA_OBJECT

        public static final java.lang.String X_JAVA_OBJECT
        A Java object.
        See Also:
        Constant Field Values

      • APPLICATION_OCTET_STREAM_CONTENT_TYPE

        public static final ContentType APPLICATION_OCTET_STREAM_CONTENT_TYPE
        The shared application/octet-stream content type.

    • Method Detail

      • isToken

        public static final boolean isToken​(java.lang.CharSequence charSequence)
        Determines if the given character sequence is a content type token, that is, consisting only of non-control ASCII characters with no special characters or spaces.
        Parameters:
        charSequence - The character sequence to check.
        Returns:
        true if the given characters sequence contains only ASCII characters with no control characters, special characters, or spaces.
        Throws:
        java.lang.NullPointerException - if the given character sequence is null.
        See Also:
        ILLEGAL_TOKEN_CHARACTERS

      • checkToken

        protected static final <CS extends java.lang.CharSequence> CS checkToken​(CS charSequence)
        Checks to ensure that the given character sequence is a content type token, that is, consisting only of non-control ASCII characters with no special characters or spaces.
        Type Parameters:
        CS - The type of the char sequence.
        Parameters:
        charSequence - The character sequence to check.
        Returns:
        The given character sequence.
        Throws:
        java.lang.NullPointerException - if the given character sequence is null.
        ArgumentSyntaxException - if the given character sequence is not a content type token.
        See Also:
        isToken(CharSequence)

      • getPrimaryType

        public java.lang.String getPrimaryType()
        Returns:
        The primary type of the content type.

      • getSubType

        public java.lang.String getSubType()
        Returns:
        The subtype of the content type.

      • getParameters

        public java.util.Set<ContentType.Parameter> getParameters()
        Returns:
        The set of parameters, which may be empty, but will never be null.

      • create

        @Deprecated
public static ContentType create​(java.lang.CharSequence charSequence)
                          throws ArgumentSyntaxException
        Deprecated.
        in favor of of(CharSequence); to be removed in next major version.
        Parses a content type object from a string.
        Parameters:
        charSequence - The character sequence representation of the content type.
        Returns:
        A new content type object parsed from the string.
        Throws:
        ArgumentSyntaxException - Thrown if the string is not a syntactically correct content type.

      • of

        public static ContentType of​(java.lang.CharSequence charSequence)
                      throws ArgumentSyntaxException
        Parses a content type object from a string.
        Parameters:
        charSequence - The character sequence representation of the content type.
        Returns:
        A new content type object parsed from the string.
        Throws:
        ArgumentSyntaxException - Thrown if the string is not a syntactically correct content type.

      • create

        @Deprecated
public static ContentType create​(java.lang.String primaryType,
                                 java.lang.String subType,
                                 ContentType.Parameter... parameters)
        Deprecated.
        in favor of of(String, String, Parameter...); to be removed in next major version.
        Creates a content type object from primary type, a subtype, and optional parameters.
        Parameters:
        primaryType - The primary type.
        subType - The subtype.
        parameters - Optional name-value pairs representing parameters of the content type.
        Returns:
        A new content type object constructed from the given information.
        Throws:
        ArgumentSyntaxException - if the primary type or subtype does not have the valid syntax.

      • of

        public static ContentType of​(java.lang.String primaryType,
                             java.lang.String subType,
                             ContentType.Parameter... parameters)
        Creates a content type object from primary type, a subtype, and optional parameters.
        Parameters:
        primaryType - The primary type.
        subType - The subtype.
        parameters - Optional name-value pairs representing parameters of the content type.
        Returns:
        A new content type object constructed from the given information.
        Throws:
        ArgumentSyntaxException - if the primary type or subtype does not have the valid syntax.

      • of

        public static ContentType of​(java.lang.String primaryType,
                             java.lang.String subType,
                             java.util.Set<ContentType.Parameter> parameters)
        Creates a content type object from primary type, a subtype, and optional parameters.
        Parameters:
        primaryType - The primary type.
        subType - The subtype.
        parameters - Zero or more name-value pairs representing parameters of the content type.
        Returns:
        A new content type object constructed from the given information.
        Throws:
        java.lang.NullPointerException - if the given parameters set is null.
        ArgumentSyntaxException - if the primary type or subtype does not have the valid syntax.

      • getParameter

        public java.lang.String getParameter​(java.lang.String name)
        Retrieve the parameter value associated with the given parameter name. Names are comparisons are case-insensitive.
        Parameters:
        name - The name of the parameter.
        Returns:
        The (always unquoted) value associated with the given name, or null if there is no parameter with the given name.
        Throws:
        java.lang.NullPointerException - if the given parameter name is null.

      • match

        public boolean match​(java.lang.String primaryType,
                     java.lang.String subType)
        Matches a content type against a primary type and subtype. Comparisons are case-insensitive. This method supports wildcard subtypes.
        Parameters:
        primaryType - The primary type with which to compare the content type.
        subType - The subtype with which to compare the content type.
        Returns:
        true if the content type has the same primary type and subtype as that given.
        See Also:
        WILDCARD_SUBTYPE

      • match

        public boolean match​(java.lang.String primaryType,
                     java.lang.String subType,
                     java.lang.Class<?> objectClass)
        Matches a content type against a primary type and subtype, with a class parameter indicating the given object class. This method supports wildcard subtypes.
        Parameters:
        primaryType - The primary type with which to compare the content type.
        subType - The subtype with which to compare the content type.
        objectClass - The class for which to check in the parameters under the key "class".
        Returns:
        true if the content type has the same primary type and subtype as that given, along with a class parameter.
        See Also:
        WILDCARD_SUBTYPE

      • match

        public boolean match​(java.lang.Class<?> objectClass)
        Matches a content type against the "application" primary type and "x-java-object" subtype, with a "class" parameter indicating the given object class. This method supports wildcard subtypes.
        Parameters:
        objectClass - The class for which to check in the parameters under the key "class".
        Returns:
        true if the content type has the same primary type and subtype as that given, along with a class parameter.
        See Also:
        WILDCARD_SUBTYPE

      • getBaseType

        @Deprecated
public java.lang.String getBaseType()
        Deprecated.
        Returns:
        A string representation of the the base content type, that is, the same primary and subtype as the content type, but with no parameters.

      • getBaseContentType

        public ContentType getBaseContentType()
        Determines the base content type, with no parameters, of the content type. Useful for making comparisons or for storing in canonical form in a hash table. If this content type is already a base content type, this content type is returned.
        Returns:
        A content type with the same primary and subtype as the content type, but with no parameters.

      • hasBaseType

        public boolean hasBaseType​(ContentType contentType)
        Checks to see if the given content type has the same primary type and subtype as this content type. This method does not support wildcards.
        Parameters:
        contentType - The content type with which to compare this content type.
        Returns:
        true if the primary types and base types of the two content types are equal.

      • hasBaseType

        public boolean hasBaseType​(java.lang.String primaryType,
                           java.lang.String subType)
        Matches a content type against a primary type and subtype with no wildcard support. Comparisons are case-insensitive.
        Parameters:
        primaryType - The primary type with which to compare the content type.
        subType - The subtype with which to compare the content type.
        Returns:
        true if the content type has the same primary type and subtype as that given.
        Throws:
        java.lang.NullPointerException - if the primary type and/or subtype is null.

      • hasSubTypeSuffix

        public boolean hasSubTypeSuffix​(java.lang.String... suffixes)
        Determines if the subtype of the content type has the given suffix.
        Parameters:
        suffixes - The suffix strings that will be checked, after they are combined into a single suffix, each part prepended with '+'.
        Returns:
        true if the content type's subtype has the given suffixes.

      • withParameter

        public ContentType withParameter​(ContentType.Parameter newParameter)
        Returns a content type with the given parameter. If this content type already has the given parameter, it will be returned. If this content type has a parameter with the same name but with a different value, the parameter will be replaced with the one given. Otherwise, the parameter will be added to the parameters. Parameter name comparisons are case-insensitive.
        Parameters:
        newParameter - The new parameter to add or replace.
        Returns:
        A content type with the given parameter.

      • withParameter

        public ContentType withParameter​(java.lang.String name,
                                 java.lang.String value)
        Returns a content type with the given parameter. If this content type already has the given parameter, it will be returned. If this content type has a parameter with the same name but with a different value, the parameter will be replaced with the one given. Otherwise, the parameter will be added to the parameters. Parameter name comparisons are case-insensitive.
        Parameters:
        name - The parameter name to add or replace.
        value - The parameter value.
        Returns:
        A content type with the given parameter.
        Throws:
        java.lang.NullPointerException - if the given name and/or value is null.
        ArgumentSyntaxException - if the name is not a token; or the value contains a space, non-ASCII, or control character.
        See Also:
        ContentType.Parameter.of(String, String)

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        Implementation Specification:
        This implementation returns the hash code of the primary type, the subtype, and the parameters, in a case insensitive manner for the types and parameter names.
        Returns:
        A hash code value for this object.
        See Also:
        getPrimaryType(), getSubType(), getParameters()

      • equals

        public boolean equals​(java.lang.Object object)
        Overrides:
        equals in class java.lang.Object
        Implementation Specification:
        This implementation considers an object equal if it is another ContentType with the same primary types and subtypes, the same number of parameters, and a matching parameter value for every parameter of this content type. Comparisons are case-insensitive for the types and parameter names.
        Parameters:
        object - The reference object with which to compare.
        See Also:
        getPrimaryType(), getSubType(), getParameters(), toString()

      • toString

        public java.lang.String toString​(boolean formatted)
        Returns a possibly formatted string version of the given content type.
        Parameters:
        formatted - Whether the resulting string should be formatted with extra whitespace for human readability.
        Returns:
        The canonical representation of the content type according to RFC 6838.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        Implementation Specification:
        This implementation returns the canonical representation of the content type according to RFC 6838, with no added whitespace.

      • toString

        public static java.lang.String toString​(java.lang.String primaryType,
                                        java.lang.String subType,
                                        ContentType.Parameter... parameters)
        Constructs a string representing a content type.
        Parameters:
        primaryType - The primary type.
        subType - The subtype.
        parameters - Optional name-value pairs representing parameters of the content type.
        Returns:
        A string representing the type in the form "primaryType/subType[;parameters]".

      • toString

        public static java.lang.String toString​(java.lang.String primaryType,
                                        java.lang.String subType,
                                        java.util.Set<ContentType.Parameter> parameters)
        Constructs a string representing a content type in canonical form.
        Parameters:
        primaryType - The primary type.
        subType - The subtype.
        parameters - Any name-value pairs representing parameters of the content type.
        Returns:
        A string representing the type in the form "primaryType/subType[;parameters]".
        Throws:
        java.lang.NullPointerException - if the given parameters set is null.

      • toString

        public static java.lang.String toString​(java.lang.String primaryType,
                                        java.lang.String subType,
                                        java.util.Set<ContentType.Parameter> parameters,
                                        boolean formatted)
        Constructs a string representing a content type.
        Parameters:
        primaryType - The primary type.
        subType - The subtype.
        parameters - Any name-value pairs representing parameters of the content type.
        formatted - Whether the resulting string should be formatted with extra whitespace for human readability.
        Returns:
        A string representing the type in the form "primaryType/subType[;parameters]".
        Throws:
        java.lang.NullPointerException - if the given parameters set is null.

      • createSubTypeSuffix

        public static java.lang.String createSubTypeSuffix​(java.lang.String... suffixes)
        Creates a content type suffix by prepending '+' to each suffix and concatenating the suffixes.
        Parameters:
        suffixes - The suffix strings to combine into a suffix.
        Returns:
        A suffix composed of the given suffix strings.