- * An attribute set contains a group of attribute values, - * where duplicate values are not allowed in the set. - * Furthermore, each value in an attribute set is - * a member of some category, and at most one value in any particular - * category is allowed in the set. For an attribute set, the values are {@link - * Attribute Attribute} objects, and the categories are {@link java.lang.Class - * Class} objects. An attribute's category is the class (or interface) at the - * root of the class hierarchy for that kind of attribute. Note that an - * attribute object's category may be a superclass of the attribute object's - * class rather than the attribute object's class itself. An attribute - * object's - * category is determined by calling the {@link Attribute#getCategory() - * getCategory()} method defined in interface {@link Attribute - * Attribute}. - *
- * The interfaces of an AttributeSet resemble those of the Java Collections - * API's java.util.Map interface, but is more restrictive in the types - * it will accept, and combines keys and values into an Attribute. - *
- * Attribute sets are used in several places in the Print Service API. In - * each context, only certain kinds of attributes are allowed to appear in the + *
+ * An attribute set contains a group of attribute values, where duplicate + * values are not allowed in the set. Furthermore, each value in an attribute + * set is a member of some category, and at most one value in any + * particular category is allowed in the set. For an attribute set, the values + * are {@link Attribute Attribute} objects, and the categories are + * {@link Class Class} objects. An attribute's category is the class (or + * interface) at the root of the class hierarchy for that kind of attribute. + * Note that an attribute object's category may be a superclass of the attribute + * object's class rather than the attribute object's class itself. An attribute + * object's category is determined by calling the + * {@link Attribute#getCategory() getCategory()} method defined in interface + * {@link Attribute Attribute}. + *
+ * The interfaces of an {@code AttributeSet} resemble those of the Java + * Collections API's {@code java.util.Map} interface, but is more restrictive in + * the types it will accept, and combines keys and values into an + * {@code Attribute}. + *
+ * Attribute sets are used in several places in the Print Service API. In each + * context, only certain kinds of attributes are allowed to appear in the * attribute set, as determined by the tagging interfaces which the attribute - * class implements -- {@link DocAttribute DocAttribute}, {@link - * PrintRequestAttribute PrintRequestAttribute}, {@link PrintJobAttribute - * PrintJobAttribute}, and {@link PrintServiceAttribute - * PrintServiceAttribute}. + * class implements -- {@link DocAttribute DocAttribute}, + * {@link PrintRequestAttribute PrintRequestAttribute}, + * {@link PrintJobAttribute PrintJobAttribute}, and + * {@link PrintServiceAttribute PrintServiceAttribute}. * There are four specializations of an attribute set that are restricted to - * contain just one of the four kinds of attribute -- {@link DocAttributeSet - * DocAttributeSet}, {@link PrintRequestAttributeSet - * PrintRequestAttributeSet}, - * {@link PrintJobAttributeSet PrintJobAttributeSet}, and {@link - * PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note that - * many attribute classes implement more than one tagging interface and so may - * appear in more than one context. - *
+ * contain just one of the four kinds of attribute -- + * {@link DocAttributeSet DocAttributeSet}, + * {@link PrintRequestAttributeSet PrintRequestAttributeSet}, + * {@link PrintJobAttributeSet PrintJobAttributeSet}, and + * {@link PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note + * that many attribute classes implement more than one tagging interface and so + * may appear in more than one context. + *
+ * operation throws an {@code UnmodifiableSetException}. + *
* The Print Service API provides one implementation of interface - * AttributeSet, class {@link HashAttributeSet HashAttributeSet}. - * A client can use class {@link - * HashAttributeSet HashAttributeSet} or provide its own implementation of - * interface AttributeSet. The Print Service API also provides - * implementations of interface AttributeSet's subinterfaces -- classes {@link - * HashDocAttributeSet HashDocAttributeSet}, - * {@link HashPrintRequestAttributeSet - * HashPrintRequestAttributeSet}, {@link HashPrintJobAttributeSet - * HashPrintJobAttributeSet}, and {@link HashPrintServiceAttributeSet - * HashPrintServiceAttributeSet}. + * {@code AttributeSet}, class {@link HashAttributeSet HashAttributeSet}. A + * client can use class {@link HashAttributeSet HashAttributeSet} or provide its + * own implementation of interface {@code AttributeSet}. The Print Service API + * also provides implementations of interface {@code AttributeSet}'s + * subinterfaces -- classes + * {@link HashDocAttributeSet HashDocAttributeSet}, + * {@link HashPrintRequestAttributeSet HashPrintRequestAttributeSet}, + * {@link HashPrintJobAttributeSet HashPrintJobAttributeSet}, and + * {@link HashPrintServiceAttributeSet HashPrintServiceAttributeSet}. * - * @author Alan Kaminsky + * @author Alan Kaminsky */ public interface AttributeSet { - /** * Returns the attribute value which this attribute set contains in the - * given attribute category. Returns {@code null} if this attribute set - * does not contain any attribute value in the given attribute category. + * given attribute category. Returns {@code null} if this attribute set does + * not contain any attribute value in the given attribute category. * - * @param category Attribute category whose associated attribute value - * is to be returned. It must be a - * {@link java.lang.Class Class} - * that implements interface {@link Attribute - * Attribute}. - * - * @return The attribute value in the given attribute category contained - * in this attribute set, or {@code null} if this attribute set - * does not contain any attribute value in the given attribute - * category. - * - * @throws NullPointerException - * (unchecked exception) Thrown if the {@code category} is null. - * @throws ClassCastException - * (unchecked exception) Thrown if the {@code category} is not a - * {@link java.lang.Class Class} that implements interface {@link - * Attribute Attribute}. + * @param category attribute category whose associated attribute value is + * to be returned. It must be a {@link Class Class} that implements + * interface {@link Attribute Attribute}. + * @return the attribute value in the given attribute category contained in + * this attribute set, or {@code null} if this attribute set does + * not contain any attribute value in the given attribute category + * @throws NullPointerException if the {@code category} is {@code null} + * @throws ClassCastException if the {@code category} is not a + * {@link Class Class} that implements interface + * {@link Attribute Attribute} */ public Attribute get(Class category); /** - * Adds the specified attribute to this attribute set if it is not - * already present, first removing any existing value in the same - * attribute category as the specified attribute value. - * - * @param attribute Attribute value to be added to this attribute set. - * - * @return {@code true} if this attribute set changed as a result of the - * call, i.e., the given attribute value was not already a member - * of this attribute set. - * - * @throws NullPointerException - * (unchecked exception) Thrown if the {@code attribute} is null. - * @throws UnmodifiableSetException - * (unchecked exception) Thrown if this attribute set does not support - * the {@code add()} operation. + * Adds the specified attribute to this attribute set if it is not already + * present, first removing any existing value in the same attribute category + * as the specified attribute value. + * + * @param attribute attribute value to be added to this attribute set + * @return {@code true} if this attribute set changed as a result of the + * call, i.e., the given attribute value was not already a member of + * this attribute set + * @throws NullPointerException if the {@code attribute} is {@code null} + * @throws UnmodifiableSetException if this attribute set does not support + * the {@code add()} operation */ public boolean add(Attribute attribute); - /** * Removes any attribute for this category from this attribute set if - * present. If {@code category} is null, then - * {@code remove()} does nothing and returns {@code false}. + * present. If {@code category} is {@code null}, then {@code remove()} does + * nothing and returns {@code false}. * - * @param category Attribute category to be removed from this - * attribute set. - * - * @return {@code true} if this attribute set changed as a result of the + * @param category attribute category to be removed from this attribute set + * @return {@code true} if this attribute set changed as a result of the * call, i.e., the given attribute value had been a member of this - * attribute set. - * - * @throws UnmodifiableSetException - * (unchecked exception) Thrown if this attribute set does not support - * the {@code remove()} operation. + * attribute set + * @throws UnmodifiableSetException if this attribute set does not support + * the {@code remove()} operation */ public boolean remove(Class category); /** - * Removes the specified attribute from this attribute set if - * present. If {@code attribute} is null, then - * {@code remove()} does nothing and returns {@code false}. + * Removes the specified attribute from this attribute set if present. If + * {@code attribute} is {@code null}, then {@code remove()} does nothing and + * returns {@code false}. * - * @param attribute Attribute value to be removed from this attribute set. - * - * @return {@code true} if this attribute set changed as a result of the + * @param attribute attribute value to be removed from this attribute set + * @return {@code true} if this attribute set changed as a result of the * call, i.e., the given attribute value had been a member of this - * attribute set. - * - * @throws UnmodifiableSetException - * (unchecked exception) Thrown if this attribute set does not support - * the {@code remove()} operation. + * attribute set + * @throws UnmodifiableSetException if this attribute set does not support + * the {@code remove()} operation */ public boolean remove(Attribute attribute); /** - * Returns {@code true} if this attribute set contains an - * attribute for the specified category. + * Returns {@code true} if this attribute set contains an attribute for the + * specified category. * - * @param category whose presence in this attribute set is - * to be tested. - * - * @return {@code true} if this attribute set contains an attribute - * value for the specified category. + * @param category whose presence in this attribute set is to be tested + * @return {@code true} if this attribute set contains an attribute value + * for the specified category */ public boolean containsKey(Class category); /** - * Returns {@code true} if this attribute set contains the given - * attribute value. - * - * @param attribute Attribute value whose presence in this - * attribute set is to be tested. + * Returns {@code true} if this attribute set contains the given attribute + * value. * - * @return {@code true} if this attribute set contains the given - * attribute value. + * @param attribute attribute value whose presence in this attribute set is + * to be tested + * @return {@code true} if this attribute set contains the given attribute + * value */ public boolean containsValue(Attribute attribute); /** - * Adds all of the elements in the specified set to this attribute. - * The outcome is the same as if the = - * {@link #add(Attribute) add(Attribute)} + * Adds all of the elements in the specified set to this attribute. The + * outcome is the same as if the = {@link #add(Attribute) add(Attribute)} * operation had been applied to this attribute set successively with each - * element from the specified set. - * The behavior of the {@code addAll(AttributeSet)} - * operation is unspecified if the specified set is modified while - * the operation is in progress. - *
- * If the {@code addAll(AttributeSet)} operation throws an exception, - * the effect on this attribute set's state is implementation dependent; - * elements from the specified set before the point of the exception may - * or may not have been added to this attribute set. - * - * @param attributes whose elements are to be added to this attribute - * set. - * - * @return {@code true} if this attribute set changed as a result of the - * call. - * - * @throws UnmodifiableSetException - * (Unchecked exception) Thrown if this attribute set does not support - * the {@code addAll(AttributeSet)} method. - * @throws NullPointerException - * (Unchecked exception) Thrown if some element in the specified - * set is null. - * + * element from the specified set. The behavior of the + * {@code addAll(AttributeSet)} operation is unspecified if the specified + * set is modified while the operation is in progress. + *
+ * If the {@code addAll(AttributeSet)} operation throws an exception, the + * effect on this attribute set's state is implementation dependent; + * elements from the specified set before the point of the exception may or + * may not have been added to this attribute set. + * + * @param attributes whose elements are to be added to this attribute set + * @return {@code true} if this attribute set changed as a result of the + * call + * @throws UnmodifiableSetException if this attribute set does not support + * the {@code addAll(AttributeSet)} method + * @throws NullPointerException if some element in the specified set is + * {@code null} * @see #add(Attribute) */ public boolean addAll(AttributeSet attributes); /** - * Returns the number of attributes in this attribute set. If this - * attribute set contains more than {@code Integer.MAX_VALUE} elements, - * returns {@code Integer.MAX_VALUE}. + * Returns the number of attributes in this attribute set. If this attribute + * set contains more than {@code Integer.MAX_VALUE} elements, returns + * {@code Integer.MAX_VALUE}. * - * @return The number of attributes in this attribute set. + * @return the number of attributes in this attribute set */ public int size(); /** * Returns an array of the attributes contained in this set. - * @return the Attributes contained in this set as an array, zero length - * if the AttributeSet is empty. + * + * @return the {@code Attributes} contained in this set as an array, zero + * length if the {@code AttributeSet} is empty */ public Attribute[] toArray(); - /** * Removes all attributes from this attribute set. * - * @throws UnmodifiableSetException - * (unchecked exception) Thrown if this attribute set does not support - * the {@code clear()} operation. + * @throws UnmodifiableSetException if this attribute set does not support + * the {@code clear()} operation */ public void clear(); /** - * Returns true if this attribute set contains no attributes. + * Returns {@code true} if this attribute set contains no attributes. * - * @return true if this attribute set contains no attributes. + * @return {@code true} if this attribute set contains no attributes */ public boolean isEmpty(); /** * Compares the specified object with this attribute set for equality. - * Returns {@code true} if the given object is also an attribute set and - * the two attribute sets contain the same attribute category-attribute - * value mappings. This ensures that the - * {@code equals()} method works properly across different - * implementations of the AttributeSet interface. - * - * @param object to be compared for equality with this attribute set. - * - * @return {@code true} if the specified object is equal to this - * attribute set. + * Returns {@code true} if the given object is also an attribute set and the + * two attribute sets contain the same attribute category-attribute value + * mappings. This ensures that the {@code equals()} method works properly + * across different implementations of the {@code AttributeSet} interface. + * + * @param object to be compared for equality with this attribute set + * @return {@code true} if the specified object is equal to this attribute + * set */ public boolean equals(Object object); /** * Returns the hash code value for this attribute set. The hash code of an - * attribute set is defined to be the sum of the hash codes of each entry - * in the AttributeSet. - * This ensures that {@code t1.equals(t2)} implies that - * {@code t1.hashCode()==t2.hashCode()} for any two attribute sets + * attribute set is defined to be the sum of the hash codes of each entry in + * the {@code AttributeSet}. This ensures that {@code t1.equals(t2)} implies + * that {@code t1.hashCode()==t2.hashCode()} for any two attribute sets * {@code t1} and {@code t2}, as required by the general contract of - * {@link java.lang.Object#hashCode() Object.hashCode()}. + * {@link Object#hashCode() Object.hashCode()}. * - * @return The hash code value for this attribute set. + * @return the hash code value for this attribute set */ public int hashCode(); - }