org.springframework.http.MediaType Maven / Gradle / Ivy
/*
* Copyright 2002-2011 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.http;
import java.nio.charset.Charset;
import java.util.ArrayList;
import java.util.BitSet;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.TreeSet;
import org.springframework.util.Assert;
import org.springframework.util.CollectionUtils;
import org.springframework.util.LinkedCaseInsensitiveMap;
import org.springframework.util.StringUtils;
/**
* Represents an Internet Media Type, as defined in the HTTP specification.
*
* Consists of a {@linkplain #getType() type} and a {@linkplain #getSubtype() subtype}.
* Also has functionality to parse media types from a string using {@link #parseMediaType(String)},
* or multiple comma-separated media types using {@link #parseMediaTypes(String)}.
*
* @author Arjen Poutsma
* @author Juergen Hoeller
* @since 3.0
* @see HTTP 1.1, section 3.7
*/
public class MediaType implements Comparable {
/**
* Public constant media type that includes all media ranges (i.e. */*).
*/
public static final MediaType ALL;
/**
* Public constant media type for {@code application/atom+xml}.
*/
public final static MediaType APPLICATION_ATOM_XML;
/**
* Public constant media type for {@code application/x-www-form-urlencoded}.
* */
public final static MediaType APPLICATION_FORM_URLENCODED;
/**
* Public constant media type for {@code application/json}.
* */
public final static MediaType APPLICATION_JSON;
/**
* Public constant media type for {@code application/octet-stream}.
* */
public final static MediaType APPLICATION_OCTET_STREAM;
/**
* Public constant media type for {@code application/xhtml+xml}.
* */
public final static MediaType APPLICATION_XHTML_XML;
/**
* Public constant media type for {@code application/xml}.
*/
public final static MediaType APPLICATION_XML;
/**
* Public constant media type for {@code image/gif}.
*/
public final static MediaType IMAGE_GIF;
/**
* Public constant media type for {@code image/jpeg}.
*/
public final static MediaType IMAGE_JPEG;
/**
* Public constant media type for {@code image/png}.
*/
public final static MediaType IMAGE_PNG;
/**
* Public constant media type for {@code multipart/form-data}.
* */
public final static MediaType MULTIPART_FORM_DATA;
/**
* Public constant media type for {@code text/html}.
* */
public final static MediaType TEXT_HTML;
/**
* Public constant media type for {@code text/plain}.
* */
public final static MediaType TEXT_PLAIN;
/**
* Public constant media type for {@code text/xml}.
* */
public final static MediaType TEXT_XML;
private static final BitSet TOKEN;
private static final String WILDCARD_TYPE = "*";
private static final String PARAM_QUALITY_FACTOR = "q";
private static final String PARAM_CHARSET = "charset";
private final String type;
private final String subtype;
private final Map parameters;
static {
// variable names refer to RFC 2616, section 2.2
BitSet ctl = new BitSet(128);
for (int i=0; i <= 31; i++) {
ctl.set(i);
}
ctl.set(127);
BitSet separators = new BitSet(128);
separators.set('(');
separators.set(')');
separators.set('<');
separators.set('>');
separators.set('@');
separators.set(',');
separators.set(';');
separators.set(':');
separators.set('\\');
separators.set('\"');
separators.set('/');
separators.set('[');
separators.set(']');
separators.set('?');
separators.set('=');
separators.set('{');
separators.set('}');
separators.set(' ');
separators.set('\t');
TOKEN = new BitSet(128);
TOKEN.set(0, 128);
TOKEN.andNot(ctl);
TOKEN.andNot(separators);
ALL = new MediaType("*", "*");
APPLICATION_ATOM_XML = new MediaType("application","atom+xml");
APPLICATION_FORM_URLENCODED = new MediaType("application","x-www-form-urlencoded");
APPLICATION_JSON = new MediaType("application","json");
APPLICATION_OCTET_STREAM = new MediaType("application","octet-stream");
APPLICATION_XHTML_XML = new MediaType("application","xhtml+xml");
APPLICATION_XML = new MediaType("application","xml");
IMAGE_GIF = new MediaType("image", "gif");
IMAGE_JPEG = new MediaType("image", "jpeg");
IMAGE_PNG = new MediaType("image", "png");
MULTIPART_FORM_DATA = new MediaType("multipart","form-data");
TEXT_HTML = new MediaType("text","html");
TEXT_PLAIN = new MediaType("text","plain");
TEXT_XML = new MediaType("text","xml");
}
/**
* Create a new {@code MediaType} for the given primary type.
* The {@linkplain #getSubtype() subtype} is set to *, parameters empty.
* @param type the primary type
* @throws IllegalArgumentException if any of the parameters contain illegal characters
*/
public MediaType(String type) {
this(type, WILDCARD_TYPE);
}
/**
* Create a new {@code MediaType} for the given primary type and subtype.
*
The parameters are empty.
* @param type the primary type
* @param subtype the subtype
* @throws IllegalArgumentException if any of the parameters contain illegal characters
*/
public MediaType(String type, String subtype) {
this(type, subtype, Collections.emptyMap());
}
/**
* Create a new {@code MediaType} for the given type, subtype, and character set.
* @param type the primary type
* @param subtype the subtype
* @param charSet the character set
* @throws IllegalArgumentException if any of the parameters contain illegal characters
*/
public MediaType(String type, String subtype, Charset charSet) {
this(type, subtype, Collections.singletonMap(PARAM_CHARSET, charSet.name()));
}
/**
* Create a new {@code MediaType} for the given type, subtype, and quality value.
*
* @param type the primary type
* @param subtype the subtype
* @param qualityValue the quality value
* @throws IllegalArgumentException if any of the parameters contain illegal characters
*/
public MediaType(String type, String subtype, double qualityValue) {
this(type, subtype, Collections.singletonMap(PARAM_QUALITY_FACTOR, Double.toString(qualityValue)));
}
/**
* Copy-constructor that copies the type and subtype of the given {@code MediaType},
* and allows for different parameter.
* @param other the other media type
* @param parameters the parameters, may be null
* @throws IllegalArgumentException if any of the parameters contain illegal characters
*/
public MediaType(MediaType other, Map parameters) {
this(other.getType(), other.getSubtype(), parameters);
}
/**
* Create a new {@code MediaType} for the given type, subtype, and parameters.
* @param type the primary type
* @param subtype the subtype
* @param parameters the parameters, may be null
* @throws IllegalArgumentException if any of the parameters contain illegal characters
*/
public MediaType(String type, String subtype, Map parameters) {
Assert.hasLength(type, "'type' must not be empty");
Assert.hasLength(subtype, "'subtype' must not be empty");
checkToken(type);
checkToken(subtype);
this.type = type.toLowerCase(Locale.ENGLISH);
this.subtype = subtype.toLowerCase(Locale.ENGLISH);
if (!CollectionUtils.isEmpty(parameters)) {
Map m = new LinkedCaseInsensitiveMap(parameters.size(), Locale.ENGLISH);
for (Map.Entry entry : parameters.entrySet()) {
String attribute = entry.getKey();
String value = entry.getValue();
checkParameters(attribute, value);
m.put(attribute, unquote(value));
}
this.parameters = Collections.unmodifiableMap(m);
}
else {
this.parameters = Collections.emptyMap();
}
}
/**
* Checks the given token string for illegal characters, as defined in RFC 2616, section 2.2.
* @throws IllegalArgumentException in case of illegal characters
* @see HTTP 1.1, section 2.2
*/
private void checkToken(String s) {
for (int i=0; i < s.length(); i++ ) {
char ch = s.charAt(i);
if (!TOKEN.get(ch)) {
throw new IllegalArgumentException("Invalid token character '" + ch + "' in token \"" + s + "\"");
}
}
}
private void checkParameters(String attribute, String value) {
Assert.hasLength(attribute, "parameter attribute must not be empty");
Assert.hasLength(value, "parameter value must not be empty");
checkToken(attribute);
if (PARAM_QUALITY_FACTOR.equals(attribute)) {
value = unquote(value);
double d = Double.parseDouble(value);
Assert.isTrue(d >= 0D && d <= 1D,
"Invalid quality value \"" + value + "\": should be between 0.0 and 1.0");
}
else if (PARAM_CHARSET.equals(attribute)) {
value = unquote(value);
Charset.forName(value);
}
else if (!isQuotedString(value)) {
checkToken(value);
}
}
private boolean isQuotedString(String s) {
return s.length() > 1 && s.startsWith("\"") && s.endsWith("\"") ;
}
private String unquote(String s) {
if (s == null) {
return null;
}
return isQuotedString(s) ? s.substring(1, s.length() - 1) : s;
}
/**
* Return the primary type.
*/
public String getType() {
return this.type;
}
/**
* Indicates whether the {@linkplain #getType() type} is the wildcard character * or not.
*/
public boolean isWildcardType() {
return WILDCARD_TYPE.equals(type);
}
/**
* Return the subtype.
*/
public String getSubtype() {
return this.subtype;
}
/**
* Indicates whether the {@linkplain #getSubtype() subtype} is the wildcard character * or not.
* @return whether the subtype is *
*/
public boolean isWildcardSubtype() {
return WILDCARD_TYPE.equals(subtype);
}
/**
* Indicates whether this media type is concrete, i.e. whether neither the type or subtype is a wildcard
* character *.
* @return whether this media type is concrete
*/
public boolean isConcrete() {
return !isWildcardType() && !isWildcardSubtype();
}
/**
* Return the character set, as indicated by a charset parameter, if any.
* @return the character set; or null if not available
*/
public Charset getCharSet() {
String charSet = getParameter(PARAM_CHARSET);
return (charSet != null ? Charset.forName(charSet) : null);
}
/**
* Return the quality value, as indicated by a q parameter, if any.
* Defaults to 1.0.
* @return the quality factory
*/
public double getQualityValue() {
String qualityFactory = getParameter(PARAM_QUALITY_FACTOR);
return (qualityFactory != null ? Double.parseDouble(qualityFactory) : 1D);
}
/**
* Return a generic parameter value, given a parameter name.
* @param name the parameter name
* @return the parameter value; or null if not present
*/
public String getParameter(String name) {
return this.parameters.get(name);
}
/**
* Indicate whether this {@code MediaType} includes the given media type.
* For instance, {@code text/*} includes {@code text/plain} and {@code text/html}, and {@code application/*+xml}
* includes {@code application/soap+xml}, etc. This method is not symmetric.
* @param other the reference media type with which to compare
* @return true if this media type includes the given media type; false otherwise
*/
public boolean includes(MediaType other) {
if (other == null) {
return false;
}
if (this.isWildcardType()) {
// */* includes anything
return true;
}
else if (this.type.equals(other.type)) {
if (this.subtype.equals(other.subtype) || this.isWildcardSubtype()) {
return true;
}
// application/*+xml includes application/soap+xml
int thisPlusIdx = this.subtype.indexOf('+');
int otherPlusIdx = other.subtype.indexOf('+');
if (thisPlusIdx != -1 && otherPlusIdx != -1) {
String thisSubtypeNoSuffix = this.subtype.substring(0, thisPlusIdx);
String thisSubtypeSuffix = this.subtype.substring(thisPlusIdx + 1);
String otherSubtypeSuffix = other.subtype.substring(otherPlusIdx + 1);
if (thisSubtypeSuffix.equals(otherSubtypeSuffix) && WILDCARD_TYPE.equals(thisSubtypeNoSuffix)) {
return true;
}
}
}
return false;
}
/**
* Indicate whether this {@code MediaType} is compatible with the given media type.
*
For instance, {@code text/*} is compatible with {@code text/plain}, {@code text/html}, and vice versa.
* In effect, this method is similar to {@link #includes(MediaType)}, except that it is symmetric.
* @param other the reference media type with which to compare
* @return true if this media type is compatible with the given media type; false otherwise
*/
public boolean isCompatibleWith(MediaType other) {
if (other == null) {
return false;
}
if (isWildcardType() || other.isWildcardType()) {
return true;
}
else if (this.type.equals(other.type)) {
if (this.subtype.equals(other.subtype) || this.isWildcardSubtype() || other.isWildcardSubtype()) {
return true;
}
// application/*+xml is compatible with application/soap+xml, and vice-versa
int thisPlusIdx = this.subtype.indexOf('+');
int otherPlusIdx = other.subtype.indexOf('+');
if (thisPlusIdx != -1 && otherPlusIdx != -1) {
String thisSubtypeNoSuffix = this.subtype.substring(0, thisPlusIdx);
String otherSubtypeNoSuffix = other.subtype.substring(0, otherPlusIdx);
String thisSubtypeSuffix = this.subtype.substring(thisPlusIdx + 1);
String otherSubtypeSuffix = other.subtype.substring(otherPlusIdx + 1);
if (thisSubtypeSuffix.equals(otherSubtypeSuffix) &&
(WILDCARD_TYPE.equals(thisSubtypeNoSuffix) || WILDCARD_TYPE.equals(otherSubtypeNoSuffix))) {
return true;
}
}
}
return false;
}
/**
* Compares this {@code MediaType} to another alphabetically.
* @param other media type to compare to
* @see #sortBySpecificity(List)
*/
public int compareTo(MediaType other) {
int comp = this.type.compareToIgnoreCase(other.type);
if (comp != 0) {
return comp;
}
comp = this.subtype.compareToIgnoreCase(other.subtype);
if (comp != 0) {
return comp;
}
comp = this.parameters.size() - other.parameters.size();
if (comp != 0) {
return comp;
}
TreeSet thisAttributes = new TreeSet(String.CASE_INSENSITIVE_ORDER);
thisAttributes.addAll(this.parameters.keySet());
TreeSet otherAttributes = new TreeSet(String.CASE_INSENSITIVE_ORDER);
otherAttributes.addAll(other.parameters.keySet());
Iterator thisAttributesIterator = thisAttributes.iterator();
Iterator otherAttributesIterator = otherAttributes.iterator();
while (thisAttributesIterator.hasNext()) {
String thisAttribute = thisAttributesIterator.next();
String otherAttribute = otherAttributesIterator.next();
comp = thisAttribute.compareToIgnoreCase(otherAttribute);
if (comp != 0) {
return comp;
}
String thisValue = this.parameters.get(thisAttribute);
String otherValue = other.parameters.get(otherAttribute);
if (otherValue == null) {
otherValue = "";
}
comp = thisValue.compareTo(otherValue);
if (comp != 0) {
return comp;
}
}
return 0;
}
@Override
public boolean equals(Object other) {
if (this == other) {
return true;
}
if (!(other instanceof MediaType)) {
return false;
}
MediaType otherType = (MediaType) other;
return (this.type.equalsIgnoreCase(otherType.type) && this.subtype.equalsIgnoreCase(otherType.subtype) &&
this.parameters.equals(otherType.parameters));
}
@Override
public int hashCode() {
int result = this.type.hashCode();
result = 31 * result + this.subtype.hashCode();
result = 31 * result + this.parameters.hashCode();
return result;
}
@Override
public String toString() {
StringBuilder builder = new StringBuilder();
appendTo(builder);
return builder.toString();
}
private void appendTo(StringBuilder builder) {
builder.append(this.type);
builder.append('/');
builder.append(this.subtype);
appendTo(this.parameters, builder);
}
private void appendTo(Map map, StringBuilder builder) {
for (Map.Entry entry : map.entrySet()) {
builder.append(';');
builder.append(entry.getKey());
builder.append('=');
builder.append(entry.getValue());
}
}
/**
* Parse the given String value into a {@code MediaType} object,
* with this method name following the 'valueOf' naming convention
* (as supported by {@link org.springframework.core.convert.ConversionService}.
* @see #parseMediaType(String)
*/
public static MediaType valueOf(String value) {
return parseMediaType(value);
}
/**
* Parse the given String into a single {@code MediaType}.
* @param mediaType the string to parse
* @return the media type
* @throws IllegalArgumentException if the string cannot be parsed
*/
public static MediaType parseMediaType(String mediaType) {
Assert.hasLength(mediaType, "'mediaType' must not be empty");
String[] parts = StringUtils.tokenizeToStringArray(mediaType, ";");
String fullType = parts[0].trim();
// java.net.HttpURLConnection returns a *; q=.2 Accept header
if (WILDCARD_TYPE.equals(fullType)) {
fullType = "*/*";
}
int subIndex = fullType.indexOf('/');
if (subIndex == -1) {
throw new IllegalArgumentException("\"" + mediaType + "\" does not contain '/'");
}
if (subIndex == fullType.length() - 1) {
throw new IllegalArgumentException("\"" + mediaType + "\" does not contain subtype after '/'");
}
String type = fullType.substring(0, subIndex);
String subtype = fullType.substring(subIndex + 1, fullType.length());
Map parameters = null;
if (parts.length > 1) {
parameters = new LinkedHashMap(parts.length - 1);
for (int i = 1; i < parts.length; i++) {
String parameter = parts[i];
int eqIndex = parameter.indexOf('=');
if (eqIndex != -1) {
String attribute = parameter.substring(0, eqIndex);
String value = parameter.substring(eqIndex + 1, parameter.length());
parameters.put(attribute, value);
}
}
}
return new MediaType(type, subtype, parameters);
}
/**
* Parse the given, comma-separated string into a list of {@code MediaType} objects.
* This method can be used to parse an Accept or Content-Type header.
* @param mediaTypes the string to parse
* @return the list of media types
* @throws IllegalArgumentException if the string cannot be parsed
*/
public static List parseMediaTypes(String mediaTypes) {
if (!StringUtils.hasLength(mediaTypes)) {
return Collections.emptyList();
}
String[] tokens = mediaTypes.split(",\\s*");
List result = new ArrayList(tokens.length);
for (String token : tokens) {
result.add(parseMediaType(token));
}
return result;
}
/**
* Return a string representation of the given list of {@code MediaType} objects.
* This method can be used to for an {@code Accept} or {@code Content-Type} header.
* @param mediaTypes the string to parse
* @return the list of media types
* @throws IllegalArgumentException if the String cannot be parsed
*/
public static String toString(Collection mediaTypes) {
StringBuilder builder = new StringBuilder();
for (Iterator iterator = mediaTypes.iterator(); iterator.hasNext();) {
MediaType mediaType = iterator.next();
mediaType.appendTo(builder);
if (iterator.hasNext()) {
builder.append(", ");
}
}
return builder.toString();
}
/**
* Sorts the given list of {@code MediaType} objects by specificity.
* Given two media types:
*
* - if either media type has a {@linkplain #isWildcardType() wildcard type}, then the media type without the
* wildcard is ordered before the other.
* - if the two media types have different {@linkplain #getType() types}, then they are considered equal and
* remain their current order.
* - if either media type has a {@linkplain #isWildcardSubtype() wildcard subtype}, then the media type without
* the wildcard is sorted before the other.
* - if the two media types have different {@linkplain #getSubtype() subtypes}, then they are considered equal
* and remain their current order.
* - if the two media types have different {@linkplain #getQualityValue() quality value}, then the media type
* with the highest quality value is ordered before the other.
* - if the two media types have a different amount of {@linkplain #getParameter(String) 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
* @param mediaTypes the list of media types to be sorted
* @see HTTP 1.1, section 14.1
*/
public static void sortBySpecificity(List mediaTypes) {
Assert.notNull(mediaTypes, "'mediaTypes' must not be null");
if (mediaTypes.size() > 1) {
Collections.sort(mediaTypes, SPECIFICITY_COMPARATOR);
}
}
/**
* Sorts the given list of {@code MediaType} objects by quality value.
* Given two media types:
*
* - if the two media types have different {@linkplain #getQualityValue() quality value}, then the media type
* with the highest quality value is ordered before the other.
* - if either media type has a {@linkplain #isWildcardType() wildcard type}, then the media type without the
* wildcard is ordered before the other.
* - if the two media types have different {@linkplain #getType() types}, then they are considered equal and
* remain their current order.
* - if either media type has a {@linkplain #isWildcardSubtype() wildcard subtype}, then the media type without
* the wildcard is sorted before the other.
* - if the two media types have different {@linkplain #getSubtype() subtypes}, then they are considered equal
* and remain their current order.
* - if the two media types have a different amount of {@linkplain #getParameter(String) parameters}, then the
* media type with the most parameters is ordered before the other.
*
* @param mediaTypes the list of media types to be sorted
* @see #getQualityValue()
*/
public static void sortByQualityValue(List mediaTypes) {
Assert.notNull(mediaTypes, "'mediaTypes' must not be null");
if (mediaTypes.size() > 1) {
Collections.sort(mediaTypes, QUALITY_VALUE_COMPARATOR);
}
}
/**
* Comparator used by {@link #sortBySpecificity(List)}.
*/
public static final Comparator SPECIFICITY_COMPARATOR = new Comparator() {
public int compare(MediaType mediaType1, MediaType mediaType2) {
if (mediaType1.isWildcardType() && !mediaType2.isWildcardType()) { // */* < audio/*
return 1;
}
else if (mediaType2.isWildcardType() && !mediaType1.isWildcardType()) { // audio/* > */*
return -1;
}
else if (!mediaType1.getType().equals(mediaType2.getType())) { // audio/basic == text/html
return 0;
}
else { // mediaType1.getType().equals(mediaType2.getType())
if (mediaType1.isWildcardSubtype() && !mediaType2.isWildcardSubtype()) { // audio/* < audio/basic
return 1;
}
else if (mediaType2.isWildcardSubtype() && !mediaType1.isWildcardSubtype()) { // audio/basic > audio/*
return -1;
}
else if (!mediaType1.getSubtype().equals(mediaType2.getSubtype())) { // audio/basic == audio/wave
return 0;
}
else { // mediaType2.getSubtype().equals(mediaType2.getSubtype())
double quality1 = mediaType1.getQualityValue();
double quality2 = mediaType2.getQualityValue();
int qualityComparison = Double.compare(quality2, quality1);
if (qualityComparison != 0) {
return qualityComparison; // audio/*;q=0.7 < audio/*;q=0.3
}
else {
int paramsSize1 = mediaType1.parameters.size();
int paramsSize2 = mediaType2.parameters.size();
return (paramsSize2 < paramsSize1 ? -1 : (paramsSize2 == paramsSize1 ? 0 : 1)); // audio/basic;level=1 < audio/basic
}
}
}
}
};
/**
* Comparator used by {@link #sortByQualityValue(List)}.
*/
public static final Comparator QUALITY_VALUE_COMPARATOR = new Comparator() {
public int compare(MediaType mediaType1, MediaType mediaType2) {
double quality1 = mediaType1.getQualityValue();
double quality2 = mediaType2.getQualityValue();
int qualityComparison = Double.compare(quality2, quality1);
if (qualityComparison != 0) {
return qualityComparison; // audio/*;q=0.7 < audio/*;q=0.3
}
else if (mediaType1.isWildcardType() && !mediaType2.isWildcardType()) { // */* < audio/*
return 1;
}
else if (mediaType2.isWildcardType() && !mediaType1.isWildcardType()) { // audio/* > */*
return -1;
}
else if (!mediaType1.getType().equals(mediaType2.getType())) { // audio/basic == text/html
return 0;
}
else { // mediaType1.getType().equals(mediaType2.getType())
if (mediaType1.isWildcardSubtype() && !mediaType2.isWildcardSubtype()) { // audio/* < audio/basic
return 1;
}
else if (mediaType2.isWildcardSubtype() && !mediaType1.isWildcardSubtype()) { // audio/basic > audio/*
return -1;
}
else if (!mediaType1.getSubtype().equals(mediaType2.getSubtype())) { // audio/basic == audio/wave
return 0;
}
else {
int paramsSize1 = mediaType1.parameters.size();
int paramsSize2 = mediaType2.parameters.size();
return (paramsSize2 < paramsSize1 ? -1 : (paramsSize2 == paramsSize1 ? 0 : 1)); // audio/basic;level=1 < audio/basic
}
}
}
};
}