--- old/src/java.desktop/share/classes/javax/print/MimeType.java 2017-07-16 16:17:16.000000000 -0700
+++ new/src/java.desktop/share/classes/javax/print/MimeType.java 2017-07-16 16:17:16.000000000 -0700
@@ -26,7 +26,6 @@
package javax.print;
import java.io.Serializable;
-
import java.util.AbstractMap;
import java.util.AbstractSet;
import java.util.Iterator;
@@ -36,63 +35,63 @@
import java.util.Vector;
/**
- * Class MimeType encapsulates a Multipurpose Internet Mail Extensions (MIME)
- * media type as defined in RFC
- * 2045 and RFC 2046. A
- * MIME type object is part of a {@link DocFlavor DocFlavor} object and
- * specifies the format of the print data.
- *
- * Class MimeType is similar to the like-named
- * class in package {@link java.awt.datatransfer java.awt.datatransfer}. Class
- * java.awt.datatransfer.MimeType is not used in the Jini Print Service API
- * for two reasons:
- *
- * -
- * Since not all Java profiles include the AWT, the Jini Print Service should
- * not depend on an AWT class.
- *
-
- * The implementation of class java.awt.datatransfer.MimeType does not
- * guarantee
- * that equivalent MIME types will have the same serialized representation.
- * Thus, since the Jini Lookup Service (JLUS) matches service attributes based
- * on equality of serialized representations, JLUS searches involving MIME
- * types encapsulated in class java.awt.datatransfer.MimeType may incorrectly
- * fail to match.
- *
- *
+ * Class {@code MimeType} encapsulates a Multipurpose Internet Mail Extensions
+ * (MIME) media type as defined in
+ * RFC 2045 and
+ * RFC 2046. A MIME type
+ * object is part of a {@link DocFlavor DocFlavor} object and specifies the
+ * format of the print data.
+ *
+ * Class {@code MimeType} is similar to the like-named class in package
+ * {@link java.awt.datatransfer java.awt.datatransfer}. Class
+ * {@link java.awt.datatransfer.MimeType} is not used in the Jini Print Service
+ * API for two reasons:
+ *
+ * - Since not all Java profiles include the AWT, the Jini Print Service
+ * should not depend on an AWT class.
+ *
- The implementation of class {@code java.awt.datatransfer.MimeType} does
+ * not guarantee that equivalent MIME types will have the same serialized
+ * representation. Thus, since the Jini Lookup Service (JLUS) matches service
+ * attributes based on equality of serialized representations, JLUS searches
+ * involving MIME types encapsulated in class
+ * {@code java.awt.datatransfer.MimeType} may incorrectly fail to match.
+ *
* Class MimeType's serialized representation is based on the following
* canonical form of a MIME type string. Thus, two MIME types that are not
- * identical but that are equivalent (that have the same canonical form) will
- * be considered equal by the JLUS's matching algorithm.
- *
- * - The media type, media subtype, and parameters are retained, but all
- * comments and whitespace characters are discarded.
- *
- The media type, media subtype, and parameter names are converted to
- * lowercase.
- *
- The parameter values retain their original case, except a charset
- * parameter value for a text media type is converted to lowercase.
- *
- Quote characters surrounding parameter values are removed.
- *
- Quoting backslash characters inside parameter values are removed.
- *
- The parameters are arranged in ascending order of parameter name.
- *
+ * identical but that are equivalent (that have the same canonical form) will be
+ * considered equal by the JLUS's matching algorithm.
+ *
+ * - The media type, media subtype, and parameters are retained, but all
+ * comments and whitespace characters are discarded.
+ *
- The media type, media subtype, and parameter names are converted to
+ * lowercase.
+ *
- The parameter values retain their original case, except a charset
+ * parameter value for a text media type is converted to lowercase.
+ *
- Quote characters surrounding parameter values are removed.
+ *
- Quoting backslash characters inside parameter values are removed.
+ *
- The parameters are arranged in ascending order of parameter name.
+ *
*
- * @author Alan Kaminsky
+ * @author Alan Kaminsky
*/
class MimeType implements Serializable, Cloneable {
+ /**
+ * Use serialVersionUID from JDK 1.4 for interoperability.
+ */
private static final long serialVersionUID = -2785720609362367683L;
/**
- * Array of strings that hold pieces of this MIME type's canonical form.
- * If the MIME type has n parameters, n >= 0, then the
+ * Array of strings that hold pieces of this MIME type's canonical form. If
+ * the MIME type has n parameters, n >= 0, then the
* strings in the array are:
- *
Index 0 -- Media type.
- *
Index 1 -- Media subtype.
- *
Index 2i+2 -- Name of parameter i,
- * i=0,1,...,n-1.
- *
Index 2i+3 -- Value of parameter i,
- * i=0,1,...,n-1.
- *
Parameters are arranged in ascending order of parameter name.
+ *
Index 0 -- Media type.
+ *
Index 1 -- Media subtype.
+ *
Index 2i+2 -- Name of parameter i,
+ * i=0,1,...,n-1.
+ *
Index 2i+3 -- Value of parameter i,
+ * i=0,1,...,n-1.
+ *
Parameters are arranged in ascending order of parameter name.
* @serial
*/
private String[] myPieces;
@@ -116,7 +115,17 @@
* Parameter map entry.
*/
private class ParameterMapEntry implements Map.Entry {
+
+ /**
+ * The index of the entry.
+ */
private int myIndex;
+
+ /**
+ * Constructs a new parameter map entry.
+ *
+ * @param theIndex the index of the entry
+ */
public ParameterMapEntry(int theIndex) {
myIndex = theIndex;
}
@@ -144,6 +153,10 @@
* Parameter map entry set iterator.
*/
private class ParameterMapEntrySetIterator implements Iterator> {
+
+ /**
+ * The current index of the iterator.
+ */
private int myIndex = 2;
public boolean hasNext() {
return myIndex < myPieces.length;
@@ -187,16 +200,13 @@
}
/**
- * Construct a new MIME type object from the given string. The given
- * string is converted into canonical form and stored internally.
- *
- * @param s MIME media type string.
+ * Construct a new MIME type object from the given string. The given string
+ * is converted into canonical form and stored internally.
*
- * @exception NullPointerException
- * (unchecked exception) Thrown if {@code s} is null.
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code s} does not obey the
- * syntax for a MIME media type string.
+ * @param s MIME media type string
+ * @throws NullPointerException if {@code s} is {@code null}
+ * @throws IllegalArgumentException if {@code s} does not obey the syntax
+ * for a MIME media type string
*/
public MimeType(String s) {
parse (s);
@@ -205,6 +215,8 @@
/**
* Returns this MIME type object's MIME type string based on the canonical
* form. Each parameter value is enclosed in quotes.
+ *
+ * @return the mime type
*/
public String getMimeType() {
return getStringValue();
@@ -212,6 +224,8 @@
/**
* Returns this MIME type object's media type.
+ *
+ * @return the media type
*/
public String getMediaType() {
return myPieces[0];
@@ -219,6 +233,8 @@
/**
* Returns this MIME type object's media subtype.
+ *
+ * @return the media subtype
*/
public String getMediaSubtype() {
return myPieces[1];
@@ -226,11 +242,11 @@
/**
* Returns an unmodifiable map view of the parameters in this MIME type
- * object. Each entry in the parameter map view consists of a parameter
- * name String (key) mapping to a parameter value String. If this MIME
- * type object has no parameters, an empty map is returned.
+ * object. Each entry in the parameter map view consists of a parameter name
+ * {@code String} (key) mapping to a parameter value {@code String}. If this
+ * MIME type object has no parameters, an empty map is returned.
*
- * @return Parameter map for this MIME type object.
+ * @return parameter map for this MIME type object
*/
public Map getParameterMap() {
if (myParameterMap == null) {
@@ -242,8 +258,8 @@
/**
* Converts this MIME type object to a string.
*
- * @return MIME type string based on the canonical form. Each parameter
- * value is enclosed in quotes.
+ * @return MIME type string based on the canonical form. Each parameter
+ * value is enclosed in quotes.
*/
public String toString() {
return getStringValue();
@@ -258,19 +274,18 @@
/**
* Determine if this MIME type object is equal to the given object. The two
- * are equal if the given object is not null, is an instance of class
- * net.jini.print.data.MimeType, and has the same canonical form as this
- * MIME type object (that is, has the same type, subtype, and parameters).
- * Thus, if two MIME type objects are the same except for comments, they are
- * considered equal. However, "text/plain" and "text/plain;
- * charset=us-ascii" are not considered equal, even though they represent
- * the same media type (because the default character set for plain text is
- * US-ASCII).
+ * are equal if the given object is not {@code null}, is an instance of
+ * class {@code javax.print.data.MimeType}, and has the same canonical form
+ * as this MIME type object (that is, has the same type, subtype, and
+ * parameters). Thus, if two MIME type objects are the same except for
+ * comments, they are considered equal. However, "text/plain" and
+ * "text/plain; charset=us-ascii" are not considered equal, even though they
+ * represent the same media type (because the default character set for
+ * plain text is US-ASCII).
*
- * @param obj Object to test.
- *
- * @return True if this MIME type object equals {@code obj}, false
- * otherwise.
+ * @param obj {@code object} to test
+ * @return {@code true} if this MIME type object equals {@code obj},
+ * {@code false} otherwise
*/
public boolean equals (Object obj) {
return(obj != null &&
@@ -280,6 +295,8 @@
/**
* Returns this MIME type's string value in canonical form.
+ *
+ * @return the MIME type's string value in canonical form
*/
private String getStringValue() {
if (myStringValue == null) {
@@ -300,8 +317,8 @@
return myStringValue;
}
-// Hidden classes, constants, and operations for parsing a MIME media type
-// string.
+ // Hidden classes, constants, and operations for parsing a MIME media type
+ // string.
// Lexeme types.
private static final int TOKEN_LEXEME = 0;
@@ -310,7 +327,9 @@
private static final int EOF_LEXEME = 3;
private static final int ILLEGAL_LEXEME = 4;
- // Class for a lexical analyzer.
+ /**
+ *Class for a lexical analyzer.
+ */
private static class LexicalAnalyzer {
protected String mySource;
protected int mySourceLength;
@@ -459,18 +478,19 @@
break;
}
}
-
}
-
}
/**
- * Returns a lowercase version of the given string. The lowercase version
- * is constructed by applying Character.toLowerCase() to each character of
- * the given string, which maps characters to lowercase using the rules of
- * Unicode. This mapping is the same regardless of locale, whereas the
- * mapping of String.toLowerCase() may be different depending on the
+ * Returns a lowercase version of the given string. The lowercase version is
+ * constructed by applying {@code Character.toLowerCase()} to each character
+ * of the given string, which maps characters to lowercase using the rules
+ * of Unicode. This mapping is the same regardless of locale, whereas the
+ * mapping of {@code String.toLowerCase()} may be different depending on the
* default locale.
+ *
+ * @param s the string
+ * @return the lowercase version of the string
*/
private static String toUnicodeLowerCase(String s) {
int n = s.length();
@@ -483,6 +503,9 @@
/**
* Returns a version of the given string with backslashes removed.
+ *
+ * @param s the string
+ * @return the string with backslashes removed
*/
private static String removeBackslashes(String s) {
int n = s.length();
@@ -503,6 +526,10 @@
/**
* Returns a version of the string surrounded by quotes and with interior
* quotes preceded by a backslash.
+ *
+ * @param s the string
+ * @return the string surrounded by quotes and with interior quotes preceded
+ * by a backslash
*/
private static String addQuotes(String s) {
int n = s.length();
@@ -524,20 +551,17 @@
/**
* Parses the given string into canonical pieces and stores the pieces in
* {@link #myPieces myPieces}.
- *
+ *
* Special rules applied:
- *
- * - If the media type is text, the value of a charset parameter is
- * converted to lowercase.
- *
- *
- * @param s MIME media type string.
- *
- * @exception NullPointerException
- * (unchecked exception) Thrown if {@code s} is null.
- * @exception IllegalArgumentException
- * (unchecked exception) Thrown if {@code s} does not obey the
- * syntax for a MIME media type string.
+ *
+ * - If the media type is text, the value of a charset parameter is
+ * converted to lowercase.
+ *
+ *
+ * @param s MIME media type string
+ * @throws NullPointerException if {@code s} is {@code null}
+ * @throws IllegalArgumentException if {@code s} does not obey the syntax
+ * for a MIME media type string
*/
private void parse(String s) {
// Initialize.