| /* |
| * 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 |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package javax.print.attribute; |
| |
| /** |
| * Interface {@code AttributeSet} specifies the interface for a set of printing |
| * attributes. A printing attribute is an object whose class implements |
| * interface {@link Attribute Attribute}. |
| * <p> |
| * An attribute set contains a group of <i>attribute values,</i> where duplicate |
| * values are not allowed in the set. Furthermore, each value in an attribute |
| * set is a member of some <i>category,</i> 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}. |
| * <p> |
| * 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}. |
| * <p> |
| * 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}. |
| * 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. |
| * <ul> |
| * <li>A {@link DocAttributeSet DocAttributeSet}, containing |
| * {@link DocAttribute DocAttribute}s, specifies the characteristics of an |
| * individual doc and the print job settings to be applied to an individual |
| * doc. |
| * <li>A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing |
| * {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the |
| * settings to be applied to a whole print job and to all the docs in the |
| * print job. |
| * <li>A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing |
| * {@link PrintJobAttribute PrintJobAttribute}s, reports the status of a print |
| * job. |
| * <li>A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing |
| * {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of |
| * a Print Service instance. |
| * </ul> |
| * In some contexts, the client is only allowed to examine an attribute set's |
| * contents but not change them (the set is read-only). In other places, the |
| * client is allowed both to examine and to change an attribute set's contents |
| * (the set is read-write). For a read-only attribute set, calling a mutating |
| * operation throws an {@code UnmodifiableSetException}. |
| * <p> |
| * The Print Service API provides one implementation of interface |
| * {@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 |
| */ |
| 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. |
| * |
| * @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 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 {@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 |
| * call, i.e., the given attribute value had been a member of this |
| * 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 {@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 |
| * call, i.e., the given attribute value had been a member of this |
| * 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. |
| * |
| * @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 |
| * @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)} |
| * 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. |
| * <p> |
| * 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}. |
| * |
| * @return the number of attributes in this attribute set |
| */ |
| public int size(); |
| |
| /** |
| * Returns an array of the attributes contained in this set. |
| * |
| * @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 if this attribute set does not support |
| * the {@code clear()} operation |
| */ |
| public void clear(); |
| |
| /** |
| * Returns {@code 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 {@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 {@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 Object#hashCode() Object.hashCode()}. |
| * |
| * @return the hash code value for this attribute set |
| */ |
| public int hashCode(); |
| } |