Polishing

spring-core/src/main/java/org/springframework/util/MimeType.java

@@ -31,15 +31,15 @@ import java.util.TreeSet;
 import org.springframework.lang.Nullable;
 
 /**
- * Represents a MIME Type, as originally defined in RFC 2046 and subsequently used in
- * other Internet protocols including HTTP.
+ * Represents a MIME Type, as originally defined in RFC 2046 and subsequently
+ * used in other Internet protocols including HTTP.
  *
  * <p>This class, however, does not contain support for the q-parameters used
- * in HTTP content negotiation. Those can be found in the sub-class
+ * in HTTP content negotiation. Those can be found in the subclass
  * {@code org.springframework.http.MediaType} in the {@code spring-web} module.
  *
  * <p>Consists of a {@linkplain #getType() type} and a {@linkplain #getSubtype() subtype}.
- * Also has functionality to parse media types from a string using
+ * Also has functionality to parse MIME Type values from a {@code String} using
  * {@link #valueOf(String)}. For more parsing options see {@link MimeTypeUtils}.
  *
  * @author Arjen Poutsma
@@ -139,7 +139,7 @@ public class MimeType implements Comparable<MimeType>, Serializable {
 	/**
 	 * Copy-constructor that copies the type, subtype, parameters of the given {@code MimeType},
 	 * and allows to set the specified character set.
-	 * @param other the other media type
+	 * @param other the other MimeType
 	 * @param charset the character set
 	 * @throws IllegalArgumentException if any of the parameters contains illegal characters
 	 * @since 4.3
@@ -151,8 +151,8 @@ public class MimeType implements Comparable<MimeType>, Serializable {
 	/**
 	 * Copy-constructor that copies the type and subtype of the given {@code MimeType},
 	 * and allows for different parameter.
-	 * @param other the other media type
-	 * @param parameters the parameters, may be {@code null}
+	 * @param other the other MimeType
+	 * @param parameters the parameters (may be {@code null})
 	 * @throws IllegalArgumentException if any of the parameters contains illegal characters
 	 */
 	public MimeType(MimeType other, @Nullable Map<String, String> parameters) {
@@ -163,7 +163,7 @@ public class MimeType implements Comparable<MimeType>, Serializable {
 	 * Create a new {@code MimeType} for the given type, subtype, and parameters.
 	 * @param type the primary type
 	 * @param subtype the subtype
-	 * @param parameters the parameters, may be {@code null}
+	 * @param parameters the parameters (may be {@code null})
 	 * @throws IllegalArgumentException if any of the parameters contains illegal characters
 	 */
 	public MimeType(String type, String subtype, @Nullable Map<String, String> parameters) {
@@ -246,9 +246,9 @@ public class MimeType implements Comparable<MimeType>, Serializable {
 	}
 
 	/**
-	 * Indicates whether this media type is concrete, i.e. whether neither the type
+	 * Indicates whether this MIME Type is concrete, i.e. whether neither the type
 	 * nor the subtype is a wildcard character <code>&#42;</code>.
-	 * @return whether this media type is concrete
+	 * @return whether this MIME Type is concrete
 	 */
 	public boolean isConcrete() {
 		return !isWildcardType() && !isWildcardSubtype();
@@ -298,12 +298,12 @@ public class MimeType implements Comparable<MimeType>, Serializable {
 	}
 
 	/**
-	 * Indicate whether this {@code MediaType} includes the given media type.
+	 * Indicate whether this MIME Type includes the given MIME Type.
 	 * <p>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 <b>not</b> symmetric.
-	 * @param other the reference media type with which to compare
-	 * @return {@code true} if this media type includes the given media type;
+	 * and {@code application/*+xml} includes {@code application/soap+xml}, etc.
+	 * This method is <b>not</b> symmetric.
+	 * @param other the reference MIME Type with which to compare
+	 * @return {@code true} if this MIME Type includes the given MIME Type;
 	 * {@code false} otherwise
 	 */
 	public boolean includes(@Nullable MimeType other) {
@@ -342,12 +342,12 @@ public class MimeType implements Comparable<MimeType>, Serializable {
 	}
 
 	/**
-	 * Indicate whether this {@code MediaType} is compatible with the given media type.
+	 * Indicate whether this MIME Type is compatible with the given MIME Type.
 	 * <p>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}, except that it <b>is</b> symmetric.
-	 * @param other the reference media type with which to compare
-	 * @return {@code true} if this media type is compatible with the given media type;
+	 * @param other the reference MIME Type with which to compare
+	 * @return {@code true} if this MIME Type is compatible with the given MIME Type;
 	 * {@code false} otherwise
 	 */
 	public boolean isCompatibleWith(@Nullable MimeType other) {
@@ -458,8 +458,8 @@ public class MimeType implements Comparable<MimeType>, Serializable {
 	}
 
 	/**
-	 * Compares this {@code MediaType} to another alphabetically.
-	 * @param other media type to compare to
+	 * Compares this MIME Type to another alphabetically.
+	 * @param other the MIME Type to compare to
 	 * @see MimeTypeUtils#sortBySpecificity(List)
 	 */
 	@Override

spring-web/src/main/java/org/springframework/http/MediaType.java

@@ -36,8 +36,8 @@ import org.springframework.util.MimeTypeUtils;
 import org.springframework.util.StringUtils;
 
 /**
- * A sub-class of {@link MimeType} that adds support for quality parameters as defined
- * in the HTTP specification.
+ * A subclass of {@link MimeType} that adds support for quality parameters
+ * as defined in the HTTP specification.
  *
  * @author Arjen Poutsma
  * @author Juergen Hoeller
@@ -427,21 +427,25 @@ public class MediaType extends MimeType implements Serializable {
 	}
 
 	/**
-	 * Return the quality value, as indicated by a {@code q} parameter, if any.
+	 * Return the quality factor, as indicated by a {@code q} parameter, if any.
 	 * Defaults to {@code 1.0}.
-	 * @return the quality factory
+	 * @return the quality factor as double value
 	 */
 	public double getQualityValue() {
-		String qualityFactory = getParameter(PARAM_QUALITY_FACTOR);
-		return (qualityFactory != null ? Double.parseDouble(unquote(qualityFactory)) : 1D);
+		String qualityFactor = getParameter(PARAM_QUALITY_FACTOR);
+		return (qualityFactor != null ? Double.parseDouble(unquote(qualityFactor)) : 1D);
 	}
 
 	/**
 	 * Indicate whether this {@code MediaType} includes the given media type.
-	 * <p>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 <b>not</b> symmetric.
+	 * <p>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 <b>not</b> symmetric.
+	 * <p>Simply calls {@link #includes(MimeType)} but declared with a
+	 * {@code MediaType} parameter for binary backwards compatibility.
 	 * @param other the reference media type with which to compare
-	 * @return {@code true} if this media type includes the given media type; {@code false} otherwise
+	 * @return {@code true} if this media type includes the given media type;
+	 * {@code false} otherwise
 	 */
 	public boolean includes(@Nullable MediaType other) {
 		return super.includes(other);
@@ -449,18 +453,23 @@ public class MediaType extends MimeType implements Serializable {
 
 	/**
 	 * Indicate whether this {@code MediaType} is compatible with the given media type.
-	 * <p>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 <b>is</b> symmetric.
+	 * <p>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}, except that it <b>is</b> symmetric.
+	 * <p>Simply calls {@link #isCompatibleWith(MimeType)} but declared with a
+	 * {@code MediaType} parameter for binary backwards compatibility.
 	 * @param other the reference media type with which to compare
-	 * @return {@code true} if this media type is compatible with the given media type; {@code false} otherwise
+	 * @return {@code true} if this media type is compatible with the given media type;
+	 * {@code false} otherwise
 	 */
 	public boolean isCompatibleWith(@Nullable MediaType other) {
 		return super.isCompatibleWith(other);
 	}
 
 	/**
-	 * Return a replica of this instance with the quality value of the given MediaType.
-	 * @return the same instance if the given MediaType doesn't have a quality value, or a new one otherwise
+	 * Return a replica of this instance with the quality value of the given {@code MediaType}.
+	 * @return the same instance if the given MediaType doesn't have a quality value,
+	 * or a new one otherwise
 	 */
 	public MediaType copyQualityValue(MediaType mediaType) {
 		if (!mediaType.getParameters().containsKey(PARAM_QUALITY_FACTOR)) {
@@ -473,7 +482,8 @@ public class MediaType extends MimeType implements Serializable {
 
 	/**
 	 * Return a replica of this instance with its quality value removed.
-	 * @return the same instance if the media type doesn't contain a quality value, or a new one otherwise
+	 * @return the same instance if the media type doesn't contain a quality value,
+	 * or a new one otherwise
 	 */
 	public MediaType removeQualityValue() {
 		if (!getParameters().containsKey(PARAM_QUALITY_FACTOR)) {
@@ -677,30 +687,29 @@ public class MediaType extends MimeType implements Serializable {
 		if (qualityComparison != 0) {
 			return qualityComparison;  // audio/*;q=0.7 < audio/*;q=0.3
 		}
-		else if (mediaType1.isWildcardType() && !mediaType2.isWildcardType()) { // */* < audio/*
+		else if (mediaType1.isWildcardType() && !mediaType2.isWildcardType()) {  // */* < audio/*
 			return 1;
 		}
-		else if (mediaType2.isWildcardType() && !mediaType1.isWildcardType()) { // audio/* > */*
+		else if (mediaType2.isWildcardType() && !mediaType1.isWildcardType()) {  // audio/* > */*
 			return -1;
 		}
-		else if (!mediaType1.getType().equals(mediaType2.getType())) { // audio/basic == text/html
+		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
+		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/*
+			else if (mediaType2.isWildcardSubtype() && !mediaType1.isWildcardSubtype()) {  // audio/basic > audio/*
 				return -1;
 			}
-			else if (!mediaType1.getSubtype().equals(mediaType2.getSubtype())) { // audio/basic == audio/wave
+			else if (!mediaType1.getSubtype().equals(mediaType2.getSubtype())) {  // audio/basic == audio/wave
 				return 0;
 			}
 			else {
 				int paramsSize1 = mediaType1.getParameters().size();
 				int paramsSize2 = mediaType2.getParameters().size();
-				// audio/basic;level=1 < audio/basic
-				return (paramsSize2 < paramsSize1 ? -1 : (paramsSize2 == paramsSize1 ? 0 : 1));
+				return Integer.compare(paramsSize2, paramsSize1);  // audio/basic;level=1 < audio/basic
 			}
 		}
 	};