2362N/A * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * Interface AttributeSet specifies the interface for a set of printing 0N/A * attributes. A printing attribute is an object whose class implements 0N/A * interface {@link Attribute Attribute}. 0N/A * An attribute set contains a group of <I>attribute values,</I> 0N/A * where duplicate values are not allowed in the set. 0N/A * Furthermore, each value in an attribute set is 0N/A * a member of some <I>category,</I> and at most one value in any particular 0N/A * category is allowed in the set. For an attribute set, the values are {@link 0N/A * Attribute Attribute} objects, and the categories are {@link java.lang.Class 0N/A * Class} objects. An attribute's category is the class (or interface) at the 0N/A * root of the class hierarchy for that kind of attribute. Note that an 0N/A * attribute object's category may be a superclass of the attribute object's 0N/A * class rather than the attribute object's class itself. An attribute 0N/A * category is determined by calling the {@link Attribute#getCategory() 0N/A * <CODE>getCategory()</CODE>} method defined in interface {@link Attribute 0N/A * The interfaces of an AttributeSet resemble those of the Java Collections 0N/A * API's java.util.Map interface, but is more restrictive in the types 0N/A * it will accept, and combines keys and values into an Attribute. 0N/A * Attribute sets are used in several places in the Print Service API. In 0N/A * each context, only certain kinds of attributes are allowed to appear in the 0N/A * attribute set, as determined by the tagging interfaces which the attribute 0N/A * class implements -- {@link DocAttribute DocAttribute}, {@link 0N/A * PrintRequestAttribute PrintRequestAttribute}, {@link PrintJobAttribute 0N/A * PrintJobAttribute}, and {@link PrintServiceAttribute 0N/A * PrintServiceAttribute}. 0N/A * There are four specializations of an attribute set that are restricted to 0N/A * contain just one of the four kinds of attribute -- {@link DocAttributeSet 0N/A * DocAttributeSet}, {@link PrintRequestAttributeSet 0N/A * PrintRequestAttributeSet}, 0N/A * {@link PrintJobAttributeSet PrintJobAttributeSet}, and {@link 0N/A * PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note that 0N/A * many attribute classes implement more than one tagging interface and so may 0N/A * appear in more than one context. 0N/A * A {@link DocAttributeSet DocAttributeSet}, containing {@link DocAttribute 0N/A * DocAttribute}s, specifies the characteristics of an individual doc and the 0N/A * print job settings to be applied to an individual doc. 0N/A * A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing 0N/A * {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the 0N/A * to be applied to a whole print job and to all the docs in the print job. 0N/A * A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing {@link 0N/A * PrintJobAttribute PrintJobAttribute}s, reports the status of a print job. 0N/A * A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing 0N/A * {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of 0N/A * a Print Service instance. 0N/A * In some contexts, the client is only allowed to examine an attribute set's 0N/A * contents but not change them (the set is read-only). In other places, the 0N/A * client is allowed both to examine and to change an attribute set's contents 0N/A * (the set is read-write). For a read-only attribute set, calling a mutating 0N/A * operation throws an UnmodifiableSetException. 0N/A * The Print Service API provides one implementation of interface 0N/A * AttributeSet, class {@link HashAttributeSet HashAttributeSet}. 0N/A * A client can use class {@link 0N/A * HashAttributeSet HashAttributeSet} or provide its own implementation of 0N/A * interface AttributeSet. The Print Service API also provides 0N/A * implementations of interface AttributeSet's subinterfaces -- classes {@link 0N/A * HashDocAttributeSet HashDocAttributeSet}, 0N/A * {@link HashPrintRequestAttributeSet 0N/A * HashPrintRequestAttributeSet}, {@link HashPrintJobAttributeSet 0N/A * HashPrintJobAttributeSet}, and {@link HashPrintServiceAttributeSet 0N/A * HashPrintServiceAttributeSet}. 0N/A * @author Alan Kaminsky 0N/A * Returns the attribute value which this attribute set contains in the 0N/A * given attribute category. Returns <tt>null</tt> if this attribute set 0N/A * does not contain any attribute value in the given attribute category. 0N/A * @param category Attribute category whose associated attribute value 0N/A * is to be returned. It must be a 0N/A * {@link java.lang.Class Class} 0N/A * that implements interface {@link Attribute 0N/A * @return The attribute value in the given attribute category contained 0N/A * in this attribute set, or <tt>null</tt> if this attribute set 0N/A * does not contain any attribute value in the given attribute 0N/A * @throws NullPointerException 0N/A * (unchecked exception) Thrown if the <CODE>category</CODE> is null. 0N/A * @throws ClassCastException 0N/A * (unchecked exception) Thrown if the <CODE>category</CODE> is not a 0N/A * {@link java.lang.Class Class} that implements interface {@link 0N/A * Attribute Attribute}. 0N/A * Adds the specified attribute to this attribute set if it is not 0N/A * already present, first removing any existing value in the same 0N/A * attribute category as the specified attribute value. 0N/A * @param attribute Attribute value to be added to this attribute set. 0N/A * @return <tt>true</tt> if this attribute set changed as a result of the 0N/A * call, i.e., the given attribute value was not already a member 0N/A * of this attribute set. 0N/A * @throws NullPointerException 0N/A * (unchecked exception) Thrown if the <CODE>attribute</CODE> is null. 0N/A * @throws UnmodifiableSetException 0N/A * (unchecked exception) Thrown if this attribute set does not support 0N/A * the <CODE>add()</CODE> operation. 0N/A * Removes any attribute for this category from this attribute set if 0N/A * present. If <CODE>category</CODE> is null, then 0N/A * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 0N/A * @param category Attribute category to be removed from this 0N/A * @return <tt>true</tt> if this attribute set changed as a result of the 0N/A * call, i.e., the given attribute value had been a member of this 0N/A * @throws UnmodifiableSetException 0N/A * (unchecked exception) Thrown if this attribute set does not support 0N/A * the <CODE>remove()</CODE> operation. 0N/A * Removes the specified attribute from this attribute set if 0N/A * present. If <CODE>attribute</CODE> is null, then 0N/A * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 0N/A * @param attribute Attribute value to be removed from this attribute set. 0N/A * @return <tt>true</tt> if this attribute set changed as a result of the 0N/A * call, i.e., the given attribute value had been a member of this 0N/A * @throws UnmodifiableSetException 0N/A * (unchecked exception) Thrown if this attribute set does not support 0N/A * the <CODE>remove()</CODE> operation. 0N/A * Returns <tt>true</tt> if this attribute set contains an 0N/A * attribute for the specified category. 0N/A * @param category whose presence in this attribute set is 0N/A * @return <tt>true</tt> if this attribute set contains an attribute 0N/A * value for the specified category. 0N/A * Returns <tt>true</tt> if this attribute set contains the given 0N/A * @param attribute Attribute value whose presence in this 0N/A * attribute set is to be tested. 0N/A * @return <tt>true</tt> if this attribute set contains the given 0N/A * Adds all of the elements in the specified set to this attribute. 0N/A * The outcome is the same as if the = 0N/A * {@link #add(Attribute) <CODE>add(Attribute)</CODE>} 0N/A * operation had been applied to this attribute set successively with each 0N/A * element from the specified set. 0N/A * The behavior of the <CODE>addAll(AttributeSet)</CODE> 0N/A * operation is unspecified if the specified set is modified while 0N/A * the operation is in progress. 0N/A * If the <CODE>addAll(AttributeSet)</CODE> operation throws an exception, 0N/A * the effect on this attribute set's state is implementation dependent; 0N/A * elements from the specified set before the point of the exception may 0N/A * or may not have been added to this attribute set. 0N/A * @param attributes whose elements are to be added to this attribute 0N/A * @return <tt>true</tt> if this attribute set changed as a result of the 0N/A * @throws UnmodifiableSetException 0N/A * (Unchecked exception) Thrown if this attribute set does not support 0N/A * the <tt>addAll(AttributeSet)</tt> method. 0N/A * @throws NullPointerException 0N/A * (Unchecked exception) Thrown if some element in the specified 0N/A * @see #add(Attribute) 0N/A * Returns the number of attributes in this attribute set. If this 0N/A * attribute set contains more than <tt>Integer.MAX_VALUE</tt> elements, 0N/A * returns <tt>Integer.MAX_VALUE</tt>. 0N/A * @return The number of attributes in this attribute set. 0N/A * Returns an array of the attributes contained in this set. 0N/A * @return the Attributes contained in this set as an array, zero length 0N/A * if the AttributeSet is empty. 0N/A * Removes all attributes from this attribute set. 0N/A * @throws UnmodifiableSetException 0N/A * (unchecked exception) Thrown if this attribute set does not support 0N/A * the <CODE>clear()</CODE> operation. 0N/A * Returns true if this attribute set contains no attributes. 0N/A * @return true if this attribute set contains no attributes. 0N/A * Compares the specified object with this attribute set for equality. 0N/A * Returns <tt>true</tt> if the given object is also an attribute set and 0N/A * the two attribute sets contain the same attribute category-attribute 0N/A * value mappings. This ensures that the 0N/A * <tt>equals()</tt> method works properly across different 0N/A * implementations of the AttributeSet interface. 0N/A * @param object to be compared for equality with this attribute set. 0N/A * @return <tt>true</tt> if the specified object is equal to this 0N/A * Returns the hash code value for this attribute set. The hash code of an 0N/A * attribute set is defined to be the sum of the hash codes of each entry 0N/A * in the AttributeSet. 0N/A * This ensures that <tt>t1.equals(t2)</tt> implies that 0N/A * <tt>t1.hashCode()==t2.hashCode()</tt> for any two attribute sets 0N/A * <tt>t1</tt> and <tt>t2</tt>, as required by the general contract of 0N/A * {@link java.lang.Object#hashCode() <CODE>Object.hashCode()</CODE>}. 0N/A * @return The hash code value for this attribute set.