1 /* 2 * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.print.attribute; 27 28 /** 29 * Interface AttributeSet specifies the interface for a set of printing 30 * attributes. A printing attribute is an object whose class implements 31 * interface {@link Attribute Attribute}. 32 * <P> 33 * An attribute set contains a group of <I>attribute values,</I> 34 * where duplicate values are not allowed in the set. 35 * Furthermore, each value in an attribute set is 36 * a member of some <I>category,</I> and at most one value in any particular 37 * category is allowed in the set. For an attribute set, the values are {@link 38 * Attribute Attribute} objects, and the categories are {@link java.lang.Class 39 * Class} objects. An attribute's category is the class (or interface) at the 40 * root of the class hierarchy for that kind of attribute. Note that an 41 * attribute object's category may be a superclass of the attribute object's 42 * class rather than the attribute object's class itself. An attribute 43 * object's 44 * category is determined by calling the {@link Attribute#getCategory() 45 * getCategory()} method defined in interface {@link Attribute 46 * Attribute}. 47 * <P> 48 * The interfaces of an AttributeSet resemble those of the Java Collections 49 * API's java.util.Map interface, but is more restrictive in the types 50 * it will accept, and combines keys and values into an Attribute. 51 * <P> 52 * Attribute sets are used in several places in the Print Service API. In 53 * each context, only certain kinds of attributes are allowed to appear in the 54 * attribute set, as determined by the tagging interfaces which the attribute 55 * class implements -- {@link DocAttribute DocAttribute}, {@link 56 * PrintRequestAttribute PrintRequestAttribute}, {@link PrintJobAttribute 57 * PrintJobAttribute}, and {@link PrintServiceAttribute 58 * PrintServiceAttribute}. 59 * There are four specializations of an attribute set that are restricted to 60 * contain just one of the four kinds of attribute -- {@link DocAttributeSet 61 * DocAttributeSet}, {@link PrintRequestAttributeSet 62 * PrintRequestAttributeSet}, 63 * {@link PrintJobAttributeSet PrintJobAttributeSet}, and {@link 64 * PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note that 65 * many attribute classes implement more than one tagging interface and so may 66 * appear in more than one context. 67 * <UL> 68 * <LI> 69 * A {@link DocAttributeSet DocAttributeSet}, containing {@link DocAttribute 70 * DocAttribute}s, specifies the characteristics of an individual doc and the 71 * print job settings to be applied to an individual doc. 72 * <P> 73 * <LI> 74 * A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing 75 * {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the 76 * settings 77 * to be applied to a whole print job and to all the docs in the print job. 78 * <P> 79 * <LI> 80 * A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing {@link 81 * PrintJobAttribute PrintJobAttribute}s, reports the status of a print job. 82 * <P> 83 * <LI> 84 * A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing 85 * {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of 86 * a Print Service instance. 87 * </UL> 88 * <P> 89 * In some contexts, the client is only allowed to examine an attribute set's 90 * contents but not change them (the set is read-only). In other places, the 91 * client is allowed both to examine and to change an attribute set's contents 92 * (the set is read-write). For a read-only attribute set, calling a mutating 93 * operation throws an UnmodifiableSetException. 94 * <P> 95 * The Print Service API provides one implementation of interface 96 * AttributeSet, class {@link HashAttributeSet HashAttributeSet}. 97 * A client can use class {@link 98 * HashAttributeSet HashAttributeSet} or provide its own implementation of 99 * interface AttributeSet. The Print Service API also provides 100 * implementations of interface AttributeSet's subinterfaces -- classes {@link 101 * HashDocAttributeSet HashDocAttributeSet}, 102 * {@link HashPrintRequestAttributeSet 103 * HashPrintRequestAttributeSet}, {@link HashPrintJobAttributeSet 104 * HashPrintJobAttributeSet}, and {@link HashPrintServiceAttributeSet 105 * HashPrintServiceAttributeSet}. 106 * <P> 107 * 108 * @author Alan Kaminsky 109 */ 110 public interface AttributeSet { 111 112 113 /** 114 * Returns the attribute value which this attribute set contains in the 115 * given attribute category. Returns <tt>null</tt> if this attribute set 116 * does not contain any attribute value in the given attribute category. 117 * 118 * @param category Attribute category whose associated attribute value 119 * is to be returned. It must be a 120 * {@link java.lang.Class Class} 121 * that implements interface {@link Attribute 122 * Attribute}. 123 * 124 * @return The attribute value in the given attribute category contained 125 * in this attribute set, or <tt>null</tt> if this attribute set 126 * does not contain any attribute value in the given attribute 127 * category. 128 * 129 * @throws NullPointerException 130 * (unchecked exception) Thrown if the <CODE>category</CODE> is null. 131 * @throws ClassCastException 132 * (unchecked exception) Thrown if the <CODE>category</CODE> is not a 133 * {@link java.lang.Class Class} that implements interface {@link 134 * Attribute Attribute}. 135 */ 136 public Attribute get(Class<?> category); 137 138 /** 139 * Adds the specified attribute to this attribute set if it is not 140 * already present, first removing any existing value in the same 141 * attribute category as the specified attribute value. 142 * 143 * @param attribute Attribute value to be added to this attribute set. 144 * 145 * @return <tt>true</tt> if this attribute set changed as a result of the 146 * call, i.e., the given attribute value was not already a member 147 * of this attribute set. 148 * 149 * @throws NullPointerException 150 * (unchecked exception) Thrown if the <CODE>attribute</CODE> is null. 151 * @throws UnmodifiableSetException 152 * (unchecked exception) Thrown if this attribute set does not support 153 * the <CODE>add()</CODE> operation. 154 */ 155 public boolean add(Attribute attribute); 156 157 158 /** 159 * Removes any attribute for this category from this attribute set if 160 * present. If <CODE>category</CODE> is null, then 161 * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 162 * 163 * @param category Attribute category to be removed from this 164 * attribute set. 165 * 166 * @return <tt>true</tt> if this attribute set changed as a result of the 167 * call, i.e., the given attribute value had been a member of this 168 * attribute set. 169 * 170 * @throws UnmodifiableSetException 171 * (unchecked exception) Thrown if this attribute set does not support 172 * the <CODE>remove()</CODE> operation. 173 */ 174 public boolean remove(Class<?> category); 175 176 /** 177 * Removes the specified attribute from this attribute set if 178 * present. If <CODE>attribute</CODE> is null, then 179 * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 180 * 181 * @param attribute Attribute value to be removed from this attribute set. 182 * 183 * @return <tt>true</tt> if this attribute set changed as a result of the 184 * call, i.e., the given attribute value had been a member of this 185 * attribute set. 186 * 187 * @throws UnmodifiableSetException 188 * (unchecked exception) Thrown if this attribute set does not support 189 * the <CODE>remove()</CODE> operation. 190 */ 191 public boolean remove(Attribute attribute); 192 193 /** 194 * Returns <tt>true</tt> if this attribute set contains an 195 * attribute for the specified category. 196 * 197 * @param category whose presence in this attribute set is 198 * to be tested. 199 * 200 * @return <tt>true</tt> if this attribute set contains an attribute 201 * value for the specified category. 202 */ 203 public boolean containsKey(Class<?> category); 204 205 /** 206 * Returns <tt>true</tt> if this attribute set contains the given 207 * attribute value. 208 * 209 * @param attribute Attribute value whose presence in this 210 * attribute set is to be tested. 211 * 212 * @return <tt>true</tt> if this attribute set contains the given 213 * attribute value. 214 */ 215 public boolean containsValue(Attribute attribute); 216 217 /** 218 * Adds all of the elements in the specified set to this attribute. 219 * The outcome is the same as if the = 220 * {@link #add(Attribute) add(Attribute)} 221 * operation had been applied to this attribute set successively with each 222 * element from the specified set. 223 * The behavior of the <CODE>addAll(AttributeSet)</CODE> 224 * operation is unspecified if the specified set is modified while 225 * the operation is in progress. 226 * <P> 227 * If the <CODE>addAll(AttributeSet)</CODE> operation throws an exception, 228 * the effect on this attribute set's state is implementation dependent; 229 * elements from the specified set before the point of the exception may 230 * or may not have been added to this attribute set. 231 * 232 * @param attributes whose elements are to be added to this attribute 233 * set. 234 * 235 * @return <tt>true</tt> if this attribute set changed as a result of the 236 * call. 237 * 238 * @throws UnmodifiableSetException 239 * (Unchecked exception) Thrown if this attribute set does not support 240 * the <tt>addAll(AttributeSet)</tt> method. 241 * @throws NullPointerException 242 * (Unchecked exception) Thrown if some element in the specified 243 * set is null. 244 * 245 * @see #add(Attribute) 246 */ 247 public boolean addAll(AttributeSet attributes); 248 249 /** 250 * Returns the number of attributes in this attribute set. If this 251 * attribute set contains more than <tt>Integer.MAX_VALUE</tt> elements, 252 * returns <tt>Integer.MAX_VALUE</tt>. 253 * 254 * @return The number of attributes in this attribute set. 255 */ 256 public int size(); 257 258 /** 259 * Returns an array of the attributes contained in this set. 260 * @return the Attributes contained in this set as an array, zero length 261 * if the AttributeSet is empty. 262 */ 263 public Attribute[] toArray(); 264 265 266 /** 267 * Removes all attributes from this attribute set. 268 * 269 * @throws UnmodifiableSetException 270 * (unchecked exception) Thrown if this attribute set does not support 271 * the <CODE>clear()</CODE> operation. 272 */ 273 public void clear(); 274 275 /** 276 * Returns true if this attribute set contains no attributes. 277 * 278 * @return true if this attribute set contains no attributes. 279 */ 280 public boolean isEmpty(); 281 282 /** 283 * Compares the specified object with this attribute set for equality. 284 * Returns <tt>true</tt> if the given object is also an attribute set and 285 * the two attribute sets contain the same attribute category-attribute 286 * value mappings. This ensures that the 287 * <tt>equals()</tt> method works properly across different 288 * implementations of the AttributeSet interface. 289 * 290 * @param object to be compared for equality with this attribute set. 291 * 292 * @return <tt>true</tt> if the specified object is equal to this 293 * attribute set. 294 */ 295 public boolean equals(Object object); 296 297 /** 298 * Returns the hash code value for this attribute set. The hash code of an 299 * attribute set is defined to be the sum of the hash codes of each entry 300 * in the AttributeSet. 301 * This ensures that <tt>t1.equals(t2)</tt> implies that 302 * <tt>t1.hashCode()==t2.hashCode()</tt> for any two attribute sets 303 * <tt>t1</tt> and <tt>t2</tt>, as required by the general contract of 304 * {@link java.lang.Object#hashCode() Object.hashCode()}. 305 * 306 * @return The hash code value for this attribute set. 307 */ 308 public int hashCode(); 309 310 }