1 /* 2 * Copyright (c) 2000, 2013, 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 * 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 * 79 * <LI> 80 * A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing {@link 81 * PrintJobAttribute PrintJobAttribute}s, reports the status of a print job. 82 * 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 * 107 * @author Alan Kaminsky 108 */ 109 public interface AttributeSet { 110 111 112 /** 113 * Returns the attribute value which this attribute set contains in the 114 * given attribute category. Returns <tt>null</tt> if this attribute set 115 * does not contain any attribute value in the given attribute category. 116 * 117 * @param category Attribute category whose associated attribute value 118 * is to be returned. It must be a 119 * {@link java.lang.Class Class} 120 * that implements interface {@link Attribute 121 * Attribute}. 122 * 123 * @return The attribute value in the given attribute category contained 124 * in this attribute set, or <tt>null</tt> if this attribute set 125 * does not contain any attribute value in the given attribute 126 * category. 127 * 128 * @throws NullPointerException 129 * (unchecked exception) Thrown if the <CODE>category</CODE> is null. 130 * @throws ClassCastException 131 * (unchecked exception) Thrown if the <CODE>category</CODE> is not a 132 * {@link java.lang.Class Class} that implements interface {@link 133 * Attribute Attribute}. 134 */ 135 public Attribute get(Class<?> category); 136 137 /** 138 * Adds the specified attribute to this attribute set if it is not 139 * already present, first removing any existing value in the same 140 * attribute category as the specified attribute value. 141 * 142 * @param attribute Attribute value to be added to this attribute set. 143 * 144 * @return <tt>true</tt> if this attribute set changed as a result of the 145 * call, i.e., the given attribute value was not already a member 146 * of this attribute set. 147 * 148 * @throws NullPointerException 149 * (unchecked exception) Thrown if the <CODE>attribute</CODE> is null. 150 * @throws UnmodifiableSetException 151 * (unchecked exception) Thrown if this attribute set does not support 152 * the <CODE>add()</CODE> operation. 153 */ 154 public boolean add(Attribute attribute); 155 156 157 /** 158 * Removes any attribute for this category from this attribute set if 159 * present. If <CODE>category</CODE> is null, then 160 * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 161 * 162 * @param category Attribute category to be removed from this 163 * attribute set. 164 * 165 * @return <tt>true</tt> if this attribute set changed as a result of the 166 * call, i.e., the given attribute value had been a member of this 167 * attribute set. 168 * 169 * @throws UnmodifiableSetException 170 * (unchecked exception) Thrown if this attribute set does not support 171 * the <CODE>remove()</CODE> operation. 172 */ 173 public boolean remove(Class<?> category); 174 175 /** 176 * Removes the specified attribute from this attribute set if 177 * present. If <CODE>attribute</CODE> is null, then 178 * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 179 * 180 * @param attribute Attribute value to be removed from this attribute set. 181 * 182 * @return <tt>true</tt> if this attribute set changed as a result of the 183 * call, i.e., the given attribute value had been a member of this 184 * attribute set. 185 * 186 * @throws UnmodifiableSetException 187 * (unchecked exception) Thrown if this attribute set does not support 188 * the <CODE>remove()</CODE> operation. 189 */ 190 public boolean remove(Attribute attribute); 191 192 /** 193 * Returns <tt>true</tt> if this attribute set contains an 194 * attribute for the specified category. 195 * 196 * @param category whose presence in this attribute set is 197 * to be tested. 198 * 199 * @return <tt>true</tt> if this attribute set contains an attribute 200 * value for the specified category. 201 */ 202 public boolean containsKey(Class<?> category); 203 204 /** 205 * Returns <tt>true</tt> if this attribute set contains the given 206 * attribute value. 207 * 208 * @param attribute Attribute value whose presence in this 209 * attribute set is to be tested. 210 * 211 * @return <tt>true</tt> if this attribute set contains the given 212 * attribute value. 213 */ 214 public boolean containsValue(Attribute attribute); 215 216 /** 217 * Adds all of the elements in the specified set to this attribute. 218 * The outcome is the same as if the = 219 * {@link #add(Attribute) add(Attribute)} 220 * operation had been applied to this attribute set successively with each 221 * element from the specified set. 222 * The behavior of the <CODE>addAll(AttributeSet)</CODE> 223 * operation is unspecified if the specified set is modified while 224 * the operation is in progress. 225 * <P> 226 * If the <CODE>addAll(AttributeSet)</CODE> operation throws an exception, 227 * the effect on this attribute set's state is implementation dependent; 228 * elements from the specified set before the point of the exception may 229 * or may not have been added to this attribute set. 230 * 231 * @param attributes whose elements are to be added to this attribute 232 * set. 233 * 234 * @return <tt>true</tt> if this attribute set changed as a result of the 235 * call. 236 * 237 * @throws UnmodifiableSetException 238 * (Unchecked exception) Thrown if this attribute set does not support 239 * the <tt>addAll(AttributeSet)</tt> method. 240 * @throws NullPointerException 241 * (Unchecked exception) Thrown if some element in the specified 242 * set is null. 243 * 244 * @see #add(Attribute) 245 */ 246 public boolean addAll(AttributeSet attributes); 247 248 /** 249 * Returns the number of attributes in this attribute set. If this 250 * attribute set contains more than <tt>Integer.MAX_VALUE</tt> elements, 251 * returns <tt>Integer.MAX_VALUE</tt>. 252 * 253 * @return The number of attributes in this attribute set. 254 */ 255 public int size(); 256 257 /** 258 * Returns an array of the attributes contained in this set. 259 * @return the Attributes contained in this set as an array, zero length 260 * if the AttributeSet is empty. 261 */ 262 public Attribute[] toArray(); 263 264 265 /** 266 * Removes all attributes from this attribute set. 267 * 268 * @throws UnmodifiableSetException 269 * (unchecked exception) Thrown if this attribute set does not support 270 * the <CODE>clear()</CODE> operation. 271 */ 272 public void clear(); 273 274 /** 275 * Returns true if this attribute set contains no attributes. 276 * 277 * @return true if this attribute set contains no attributes. 278 */ 279 public boolean isEmpty(); 280 281 /** 282 * Compares the specified object with this attribute set for equality. 283 * Returns <tt>true</tt> if the given object is also an attribute set and 284 * the two attribute sets contain the same attribute category-attribute 285 * value mappings. This ensures that the 286 * <tt>equals()</tt> method works properly across different 287 * implementations of the AttributeSet interface. 288 * 289 * @param object to be compared for equality with this attribute set. 290 * 291 * @return <tt>true</tt> if the specified object is equal to this 292 * attribute set. 293 */ 294 public boolean equals(Object object); 295 296 /** 297 * Returns the hash code value for this attribute set. The hash code of an 298 * attribute set is defined to be the sum of the hash codes of each entry 299 * in the AttributeSet. 300 * This ensures that <tt>t1.equals(t2)</tt> implies that 301 * <tt>t1.hashCode()==t2.hashCode()</tt> for any two attribute sets 302 * <tt>t1</tt> and <tt>t2</tt>, as required by the general contract of 303 * {@link java.lang.Object#hashCode() Object.hashCode()}. 304 * 305 * @return The hash code value for this attribute set. 306 */ 307 public int hashCode(); 308 309 }