Package com.globalmentor.net
Class MediaType.Parameter
- Enclosing class:
- MediaType
A media type parameter name/value pair. Neither the name nor the value of a media type parameter can be
null
.- Author:
- Garret Wilson
- Implementation Specification:
- This class normalizes parameter names, which are ASCII case-insensitive, to lowercase; along with the
charset
parameter value. All other parameter values are left as-is. All other parameter values that are case-insensitive should be passed as lowercase to ensure correct equality comparisons., This implementation does not allow control characters. - Implementation Note:
- Compare this implementation to that of Guava's
com.google.common.net.MediaType
which, in addition to normalizing type, subtype, and parameter names to lowercase, also normalizes the value of thecharset
attribute to lowercase. Note also that RFC 7231 § 3.1.1.1. Media Type indicates that a lowercase form ofcharset
value is preferred, e.g.text/html;charset=utf-8
. In addition RFC 2046 § 4.1.2. Charset Parameter indicates that if non-text
types specify acharset
value, "the same syntax and values should be used"., This class considers value quoting a syntax issue of serialization, and thus interprets all values as logical, non-quoted values.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final MediaType.Parameter
The common parametercharset=iso-8859-1
.static final MediaType.Parameter
The common parametercharset=us-ascii
.static final MediaType.Parameter
The common parametercharset=utf-8
. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic <A extends Appendable>
AappendValueTo
(A appendable, CharSequence parameterValue) Appends a string representing a parameter value to an appendable, quoting and escaping it as necessary.static MediaType.Parameter
Static factory method specifying the name and value.static String
parseValue
(CharSequence text) Parses a parameter of a media type from a sequence of characters.Returns a string representation of the value, quoting and escaping it as necessary.Methods inherited from class com.globalmentor.model.NameValuePair
equals, fromMapEntry, getID, getValue, hashCode, toString
Methods inherited from class com.globalmentor.model.DefaultNamed
getName
-
Field Details
-
CHARSET_US_ASCII
The common parametercharset=us-ascii
.- API Note:
- For adding a new charset parameter to an existing media type, it is preferred to call
MediaType.withCharset(Charset)
.
-
CHARSET_ISO_8859_1
The common parametercharset=iso-8859-1
.- API Note:
- For adding a new charset parameter to an existing media type, it is preferred to call
MediaType.withCharset(Charset)
.
-
CHARSET_UTF_8
The common parametercharset=utf-8
.- API Note:
- For adding a new charset parameter to an existing media type, it is preferred to call
MediaType.withCharset(Charset)
.
-
-
Constructor Details
-
Parameter
Deprecated.in favor ofof(String, String)
; to be made non-public in next major version.Constructor specifying the name and value.- Implementation Specification:
- The parameter name is normalized to lowercase. The value of the "charset" parameter is normalized to lowercase.
- Parameters:
name
- The parameter name.value
- The parameter value.- Throws:
NullPointerException
- if the given name and/or value isnull
.IllegalArgumentException
- if the name does not conform to theMediaType.RESTRICTED_NAME_PATTERN
pattern.IllegalArgumentException
- if the parameter value includes control characters other than horizontal tab.
-
-
Method Details
-
of
Static factory method specifying the name and value.- Implementation Specification:
- The parameter name is normalized to lowercase. The value of the "charset" parameter is normalized to lowercase.
- Parameters:
name
- The parameter name.value
- The parameter value.- Returns:
- A media type for the indicated name and value.
- Throws:
NullPointerException
- if the given name and/or value isnull
.IllegalArgumentException
- if the name does not conform to theMediaType.RESTRICTED_NAME_PATTERN
pattern.IllegalArgumentException
- if the parameter value includes control characters.
-
parseValue
Parses a parameter of a media type from a sequence of characters. Quoted/escaped values are supported and decoded, but otherwise no normalization is performed.- Implementation Specification:
- This implementation supports an empty string value only if it is quoted., This implementation allows any character except control characters to be escaped., This implementation does not allow control characters other than horizontal tab.
- Parameters:
text
- The character sequence representing the parameters of the value.- Returns:
- The parsed value.
- Throws:
IllegalArgumentException
- if the string is not syntactically correct parameters, or if a parameter name does not conform to theMediaType.RESTRICTED_NAME_PATTERN
pattern.
-
toValueString
Returns a string representation of the value, quoting and escaping it as necessary.- API Note:
- This method differs from
NameValuePair.getValue()
, which returns the raw value with no quoting or escaping. - Implementation Specification:
- This implementation delegates to
appendValueTo(Appendable, CharSequence)
., This implementation does not allow control characters. - Returns:
- The string version of the value.
-
appendValueTo
public static <A extends Appendable> A appendValueTo(@Nonnull A appendable, @Nonnull CharSequence parameterValue) throws IOException Appends a string representing a parameter value to an appendable, quoting and escaping it as necessary.- Implementation Specification:
- This implementation does not allow control characters other than horizontal tab., This implementation quotes empty strings.
- Type Parameters:
A
- The type of appendable being used.- Parameters:
appendable
- The appendable, such as aStringBuilder
, to which the value should be appended.parameterValue
- The parameter value.- Returns:
- The given appendable.
- Throws:
IllegalArgumentException
- if the parameter value includes control characters.IOException
- If an I/O error occurs appending the value.
-
of(String, String)
; to be made non-public in next major version.