--- old/src/java.desktop/share/classes/javax/print/attribute/standard/PrinterStateReasons.java 2017-08-11 15:13:09.000000000 -0700 +++ new/src/java.desktop/share/classes/javax/print/attribute/standard/PrinterStateReasons.java 2017-08-11 15:13:09.000000000 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -22,69 +22,72 @@ * or visit www.oracle.com if you need additional information or have any * questions. */ + package javax.print.attribute.standard; import java.util.AbstractSet; +import java.util.HashMap; import java.util.Iterator; import java.util.Map; import java.util.NoSuchElementException; -import java.util.HashMap; import java.util.Set; import javax.print.attribute.Attribute; import javax.print.attribute.PrintServiceAttribute; /** - * Class PrinterStateReasons is a printing attribute class, a set of - * enumeration values, that provides additional information about the - * printer's current state, i.e., information that augments the value of the - * printer's {@link PrinterState PrinterState} attribute. - *

- * Instances of {@link PrinterStateReason PrinterStateReason} do not appear in - * a Print Service's attribute set directly. Rather, a PrinterStateReasons + * Class {@code PrinterStateReasons} is a printing attribute class, a set of + * enumeration values, that provides additional information about the printer's + * current state, i.e., information that augments the value of the printer's + * {@link PrinterState PrinterState} attribute. + *

+ * Instances of {@link PrinterStateReason PrinterStateReason} do not appear in a + * Print Service's attribute set directly. Rather, a {@code PrinterStateReasons} * attribute appears in the Print Service's attribute set. The - * PrinterStateReasons attribute contains zero, one, or more than one {@link - * PrinterStateReason PrinterStateReason} objects which pertain to the Print - * Service's status, and each {@link PrinterStateReason PrinterStateReason} - * object is associated with a {@link Severity Severity} level of REPORT - * (least severe), WARNING, or ERROR (most severe). The printer adds a {@link - * PrinterStateReason PrinterStateReason} object to the Print Service's - * PrinterStateReasons attribute when the corresponding condition becomes true - * of the printer, and the printer removes the {@link PrinterStateReason - * PrinterStateReason} object again when the corresponding condition becomes - * false, regardless of whether the Print Service's overall - * {@link PrinterState PrinterState} also changed. - *

- * Class PrinterStateReasons inherits its implementation from class {@link - * java.util.HashMap java.util.HashMap}. Each entry in the map consists of a + * {@code PrinterStateReasons} attribute contains zero, one, or more than one + * {@link PrinterStateReason PrinterStateReason} objects which pertain to the + * Print Service's status, and each + * {@link PrinterStateReason PrinterStateReason} object is associated with a + * {@link Severity Severity} level of {@code REPORT} (least severe), + * {@code WARNING}, or {@code ERROR} (most severe). The printer adds a + * {@link PrinterStateReason PrinterStateReason} object to the Print Service's + * {@code PrinterStateReasons} attribute when the corresponding condition + * becomes true of the printer, and the printer removes the + * {@link PrinterStateReason PrinterStateReason} object again when the + * corresponding condition becomes false, regardless of whether the Print + * Service's overall {@link PrinterState PrinterState} also changed. + *

+ * Class PrinterStateReasons inherits its implementation from class + * {@link HashMap java.util.HashMap}. Each entry in the map consists of a * {@link PrinterStateReason PrinterStateReason} object (key) mapping to a * {@link Severity Severity} object (value): - *

+ *

* Unlike most printing attributes which are immutable once constructed, class - * PrinterStateReasons is designed to be mutable; you can add {@link - * PrinterStateReason PrinterStateReason} objects to an existing - * PrinterStateReasons object and remove them again. However, like class - * {@link java.util.HashMap java.util.HashMap}, class PrinterStateReasons is - * not multiple thread safe. If a PrinterStateReasons object will be used by + * {@code PrinterStateReasons} is designed to be mutable; you can add + * {@link PrinterStateReason PrinterStateReason} objects to an existing + * {@code PrinterStateReasons} object and remove them again. However, like class + * {@link HashMap java.util.HashMap}, class {@code PrinterStateReasons} is not + * multiple thread safe. If a {@code PrinterStateReasons} object will be used by * multiple threads, be sure to synchronize its operations (e.g., using a * synchronized map view obtained from class {@link java.util.Collections * java.util.Collections}). - *

- * IPP Compatibility: The string values returned by each individual + *

+ * IPP Compatibility: The string values returned by each individual * {@link PrinterStateReason PrinterStateReason} object's and the associated - * {@link Severity Severity} object's {@code toString()} methods, - * concatenated - * together with a hyphen ({@code "-"}) in between, gives the IPP keyword - * value. The category name returned by {@code getName()} gives the IPP - * attribute name. + * {@link Severity Severity} object's {@code toString()} methods, concatenated + * together with a hyphen ({@code "-"}) in between, gives the IPP keyword value. + * The category name returned by {@code getName()} gives the IPP attribute name. * - * @author Alan Kaminsky + * @author Alan Kaminsky */ public final class PrinterStateReasons extends HashMap implements PrintServiceAttribute { + /** + * Use serialVersionUID from JDK 1.4 for interoperability. + */ private static final long serialVersionUID = -3731791085163619457L; /** @@ -96,13 +99,11 @@ } /** - * super a new, empty printer state reasons attribute; the underlying + * Construct a new, empty printer state reasons attribute; the underlying * hash map has the given initial capacity and the default load factor. * - * @param initialCapacity Initial capacity. - * - * @throws IllegalArgumentException if the initial capacity is less - * than zero. + * @param initialCapacity initial capacity + * @throws IllegalArgumentException if the initial capacity is negative */ public PrinterStateReasons(int initialCapacity) { super (initialCapacity); @@ -112,11 +113,9 @@ * Construct a new, empty printer state reasons attribute; the underlying * hash map has the given initial capacity and load factor. * - * @param initialCapacity Initial capacity. - * @param loadFactor Load factor. - * - * @throws IllegalArgumentException if the initial capacity is less - * than zero. + * @param initialCapacity initial capacity + * @param loadFactor load factor + * @throws IllegalArgumentException if the initial capacity is negative */ public PrinterStateReasons(int initialCapacity, float loadFactor) { super (initialCapacity, loadFactor); @@ -127,19 +126,15 @@ * {@link PrinterStateReason PrinterStateReason}-to-{@link Severity * Severity} mappings as the given map. The underlying hash map's initial * capacity and load factor are as specified in the superclass constructor - * {@link java.util.HashMap#HashMap(java.util.Map) - * HashMap(Map)}. + * {@link HashMap#HashMap(Map) HashMap(Map)}. * - * @param map Map to copy. - * - * @exception NullPointerException - * (unchecked exception) Thrown if {@code map} is null or if any - * key or value in {@code map} is null. - * @throws ClassCastException - * (unchecked exception) Thrown if any key in {@code map} is not - * an instance of class {@link PrinterStateReason PrinterStateReason} or - * if any value in {@code map} is not an instance of class - * {@link Severity Severity}. + * @param map map to copy + * @throws NullPointerException if {@code map} is {@code null} or if any key + * or value in {@code map} is {@code null} + * @throws ClassCastException if any key in {@code map} is not an instance + * of class {@link PrinterStateReason PrinterStateReason} or if any + * value in {@code map} is not an instance of class + * {@link Severity Severity} */ public PrinterStateReasons(Map map) { this(); @@ -149,27 +144,23 @@ /** * Adds the given printer state reason to this printer state reasons - * attribute, associating it with the given severity level. If this - * printer state reasons attribute previously contained a mapping for the - * given printer state reason, the old value is replaced. - * - * @param reason Printer state reason. This must be an instance of - * class {@link PrinterStateReason PrinterStateReason}. - * @param severity Severity of the printer state reason. This must be - * an instance of class {@link Severity Severity}. - * - * @return Previous severity associated with the given printer state - * reason, or {@code null} if the given printer state reason was - * not present. - * - * @throws NullPointerException - * (unchecked exception) Thrown if {@code reason} is null or - * {@code severity} is null. - * @throws ClassCastException - * (unchecked exception) Thrown if {@code reason} is not an - * instance of class {@link PrinterStateReason PrinterStateReason} or if - * {@code severity} is not an instance of class {@link Severity - * Severity}. + * attribute, associating it with the given severity level. If this printer + * state reasons attribute previously contained a mapping for the given + * printer state reason, the old value is replaced. + * + * @param reason printer state reason. This must be an instance of class + * {@link PrinterStateReason PrinterStateReason} + * @param severity severity of the printer state reason. This must be an + * instance of class {@link Severity Severity} + * @return previous severity associated with the given printer state reason, + * or {@code null} if the given printer state reason was not + * present + * @throws NullPointerException if {@code reason} is {@code null} or + * {@code severity} is {@code null} + * @throws ClassCastException if {@code reason} is not an instance of class + * {@link PrinterStateReason PrinterStateReason} or if + * {@code severity} is not an instance of class + * {@link Severity Severity} * @since 1.5 */ public Severity put(PrinterStateReason reason, Severity severity) { @@ -185,12 +176,12 @@ /** * Get the printing attribute class which is to be used as the "category" * for this printing attribute value. - *

- * For class PrinterStateReasons, the - * category is class PrinterStateReasons itself. + *

+ * For class {@code PrinterStateReasons}, the category is class + * {@code PrinterStateReasons} itself. * - * @return Printing attribute class (category), an instance of class - * {@link java.lang.Class java.lang.Class}. + * @return printing attribute class (category), an instance of class + * {@link Class java.lang.Class} */ public final Class getCategory() { return PrinterStateReasons.class; @@ -199,11 +190,11 @@ /** * Get the name of the category of which this attribute value is an * instance. - *

- * For class PrinterStateReasons, the - * category name is {@code "printer-state-reasons"}. + *

+ * For class {@code PrinterStateReasons}, the category name is + * {@code "printer-state-reasons"}. * - * @return Attribute category name. + * @return attribute category name */ public final String getName() { return "printer-state-reasons"; @@ -211,24 +202,21 @@ /** * Obtain an unmodifiable set view of the individual printer state reason - * attributes at the given severity level in this PrinterStateReasons - * attribute. Each element in the set view is a {@link PrinterStateReason - * PrinterStateReason} object. The only elements in the set view are the - * {@link PrinterStateReason PrinterStateReason} objects that map to the - * given severity value. The set view is backed by this - * PrinterStateReasons attribute, so changes to this PrinterStateReasons - * attribute are reflected in the set view. - * The set view does not support element insertion or - * removal. The set view's iterator does not support element removal. - * - * @param severity Severity level. - * - * @return Set view of the individual {@link PrinterStateReason - * PrinterStateReason} attributes at the given {@link Severity - * Severity} level. - * - * @exception NullPointerException - * (unchecked exception) Thrown if {@code severity} is null. + * attributes at the given severity level in this + * {@code PrinterStateReasons} attribute. Each element in the set view is a + * {@link PrinterStateReason PrinterStateReason} object. The only elements + * in the set view are the {@link PrinterStateReason PrinterStateReason} + * objects that map to the given severity value. The set view is backed by + * this {@code PrinterStateReasons} attribute, so changes to this + * {@code PrinterStateReasons} attribute are reflected in the set view. The + * set view does not support element insertion or removal. The set view's + * iterator does not support element removal. + * + * @param severity severity level + * @return set view of the individual + * {@link PrinterStateReason PrinterStateReason} attributes at the + * given {@link Severity Severity} level + * @throws NullPointerException if {@code severity} is {@code null} */ public Set printerStateReasonSet(Severity severity) { if (severity == null) { @@ -305,5 +293,4 @@ throw new UnsupportedOperationException(); } } - }