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 {@code null} 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 {@code null} 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} is null. 130 * @throws ClassCastException 131 * (unchecked exception) Thrown if the {@code category} 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 {@code true} 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} is null. 150 * @throws UnmodifiableSetException 151 * (unchecked exception) Thrown if this attribute set does not support 152 * the {@code add()} 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} is null, then 160 * {@code remove()} does nothing and returns {@code false}. 161 * 162 * @param category Attribute category to be removed from this 163 * attribute set. 164 * 165 * @return {@code true} 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()} 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} is null, then 178 * {@code remove()} does nothing and returns {@code false}. 179 * 180 * @param attribute Attribute value to be removed from this attribute set. 181 * 182 * @return {@code true} 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()} operation. 189 */ 190 public boolean remove(Attribute attribute); 191 192 /** 193 * Returns {@code true} 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 {@code true} if this attribute set contains an attribute 200 * value for the specified category. 201 */ 202 public boolean containsKey(Class<?> category); 203 204 /** 205 * Returns {@code true} 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 {@code true} 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)} 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)} 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 {@code true} 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 {@code addAll(AttributeSet)} 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 {@code Integer.MAX_VALUE} elements, 251 * returns {@code Integer.MAX_VALUE}. 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()} 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 {@code true} 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 * {@code equals()} 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 {@code true} 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 {@code t1.equals(t2)} implies that 301 * {@code t1.hashCode()==t2.hashCode()} for any two attribute sets 302 * {@code t1} and {@code t2}, 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 } | 1 /* 2 * Copyright (c) 2000, 2017, 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 {@code 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> where duplicate 34 * values are not allowed in the set. Furthermore, each value in an attribute 35 * set is a member of some <i>category,</i> and at most one value in any 36 * particular category is allowed in the set. For an attribute set, the values 37 * are {@link Attribute Attribute} objects, and the categories are 38 * {@link Class Class} objects. An attribute's category is the class (or 39 * interface) at the root of the class hierarchy for that kind of attribute. 40 * Note that an attribute object's category may be a superclass of the attribute 41 * object's class rather than the attribute object's class itself. An attribute 42 * object's category is determined by calling the 43 * {@link Attribute#getCategory() getCategory()} method defined in interface 44 * {@link Attribute Attribute}. 45 * <p> 46 * The interfaces of an {@code AttributeSet} resemble those of the Java 47 * Collections API's {@code java.util.Map} interface, but is more restrictive in 48 * the types it will accept, and combines keys and values into an 49 * {@code Attribute}. 50 * <p> 51 * Attribute sets are used in several places in the Print Service API. In each 52 * context, only certain kinds of attributes are allowed to appear in the 53 * attribute set, as determined by the tagging interfaces which the attribute 54 * class implements -- {@link DocAttribute DocAttribute}, 55 * {@link PrintRequestAttribute PrintRequestAttribute}, 56 * {@link PrintJobAttribute PrintJobAttribute}, and 57 * {@link PrintServiceAttribute PrintServiceAttribute}. 58 * There are four specializations of an attribute set that are restricted to 59 * contain just one of the four kinds of attribute -- 60 * {@link DocAttributeSet DocAttributeSet}, 61 * {@link PrintRequestAttributeSet PrintRequestAttributeSet}, 62 * {@link PrintJobAttributeSet PrintJobAttributeSet}, and 63 * {@link PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note 64 * that many attribute classes implement more than one tagging interface and so 65 * may appear in more than one context. 66 * <ul> 67 * <li>A {@link DocAttributeSet DocAttributeSet}, containing 68 * {@link DocAttribute DocAttribute}s, specifies the characteristics of an 69 * individual doc and the print job settings to be applied to an individual 70 * doc. 71 * <li>A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing 72 * {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the 73 * settings to be applied to a whole print job and to all the docs in the 74 * print job. 75 * <li>A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing 76 * {@link PrintJobAttribute PrintJobAttribute}s, reports the status of a print 77 * job. 78 * <li>A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing 79 * {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of 80 * a Print Service instance. 81 * </ul> 82 * In some contexts, the client is only allowed to examine an attribute set's 83 * contents but not change them (the set is read-only). In other places, the 84 * client is allowed both to examine and to change an attribute set's contents 85 * (the set is read-write). For a read-only attribute set, calling a mutating 86 * operation throws an {@code UnmodifiableSetException}. 87 * <p> 88 * The Print Service API provides one implementation of interface 89 * {@code AttributeSet}, class {@link HashAttributeSet HashAttributeSet}. A 90 * client can use class {@link HashAttributeSet HashAttributeSet} or provide its 91 * own implementation of interface {@code AttributeSet}. The Print Service API 92 * also provides implementations of interface {@code AttributeSet}'s 93 * subinterfaces -- classes 94 * {@link HashDocAttributeSet HashDocAttributeSet}, 95 * {@link HashPrintRequestAttributeSet HashPrintRequestAttributeSet}, 96 * {@link HashPrintJobAttributeSet HashPrintJobAttributeSet}, and 97 * {@link HashPrintServiceAttributeSet HashPrintServiceAttributeSet}. 98 * 99 * @author Alan Kaminsky 100 */ 101 public interface AttributeSet { 102 103 /** 104 * Returns the attribute value which this attribute set contains in the 105 * given attribute category. Returns {@code null} if this attribute set does 106 * not contain any attribute value in the given attribute category. 107 * 108 * @param category attribute category whose associated attribute value is 109 * to be returned. It must be a {@link Class Class} that implements 110 * interface {@link Attribute Attribute}. 111 * @return the attribute value in the given attribute category contained in 112 * this attribute set, or {@code null} if this attribute set does 113 * not contain any attribute value in the given attribute category 114 * @throws NullPointerException if the {@code category} is {@code null} 115 * @throws ClassCastException if the {@code category} is not a 116 * {@link Class Class} that implements interface 117 * {@link Attribute Attribute} 118 */ 119 public Attribute get(Class<?> category); 120 121 /** 122 * Adds the specified attribute to this attribute set if it is not already 123 * present, first removing any existing value in the same attribute category 124 * as the specified attribute value. 125 * 126 * @param attribute attribute value to be added to this attribute set 127 * @return {@code true} if this attribute set changed as a result of the 128 * call, i.e., the given attribute value was not already a member of 129 * this attribute set 130 * @throws NullPointerException if the {@code attribute} is {@code null} 131 * @throws UnmodifiableSetException if this attribute set does not support 132 * the {@code add()} operation 133 */ 134 public boolean add(Attribute attribute); 135 136 /** 137 * Removes any attribute for this category from this attribute set if 138 * present. If {@code category} is {@code null}, then {@code remove()} does 139 * nothing and returns {@code false}. 140 * 141 * @param category attribute category to be removed from this attribute set 142 * @return {@code true} if this attribute set changed as a result of the 143 * call, i.e., the given attribute value had been a member of this 144 * attribute set 145 * @throws UnmodifiableSetException if this attribute set does not support 146 * the {@code remove()} operation 147 */ 148 public boolean remove(Class<?> category); 149 150 /** 151 * Removes the specified attribute from this attribute set if present. If 152 * {@code attribute} is {@code null}, then {@code remove()} does nothing and 153 * returns {@code false}. 154 * 155 * @param attribute attribute value to be removed from this attribute set 156 * @return {@code true} if this attribute set changed as a result of the 157 * call, i.e., the given attribute value had been a member of this 158 * attribute set 159 * @throws UnmodifiableSetException if this attribute set does not support 160 * the {@code remove()} operation 161 */ 162 public boolean remove(Attribute attribute); 163 164 /** 165 * Returns {@code true} if this attribute set contains an attribute for the 166 * specified category. 167 * 168 * @param category whose presence in this attribute set is to be tested 169 * @return {@code true} if this attribute set contains an attribute value 170 * for the specified category 171 */ 172 public boolean containsKey(Class<?> category); 173 174 /** 175 * Returns {@code true} if this attribute set contains the given attribute 176 * value. 177 * 178 * @param attribute attribute value whose presence in this attribute set is 179 * to be tested 180 * @return {@code true} if this attribute set contains the given attribute 181 * value 182 */ 183 public boolean containsValue(Attribute attribute); 184 185 /** 186 * Adds all of the elements in the specified set to this attribute. The 187 * outcome is the same as if the = {@link #add(Attribute) add(Attribute)} 188 * operation had been applied to this attribute set successively with each 189 * element from the specified set. The behavior of the 190 * {@code addAll(AttributeSet)} operation is unspecified if the specified 191 * set is modified while the operation is in progress. 192 * <p> 193 * If the {@code addAll(AttributeSet)} operation throws an exception, the 194 * effect on this attribute set's state is implementation dependent; 195 * elements from the specified set before the point of the exception may or 196 * may not have been added to this attribute set. 197 * 198 * @param attributes whose elements are to be added to this attribute set 199 * @return {@code true} if this attribute set changed as a result of the 200 * call 201 * @throws UnmodifiableSetException if this attribute set does not support 202 * the {@code addAll(AttributeSet)} method 203 * @throws NullPointerException if some element in the specified set is 204 * {@code null} 205 * @see #add(Attribute) 206 */ 207 public boolean addAll(AttributeSet attributes); 208 209 /** 210 * Returns the number of attributes in this attribute set. If this attribute 211 * set contains more than {@code Integer.MAX_VALUE} elements, returns 212 * {@code Integer.MAX_VALUE}. 213 * 214 * @return the number of attributes in this attribute set 215 */ 216 public int size(); 217 218 /** 219 * Returns an array of the attributes contained in this set. 220 * 221 * @return the {@code Attributes} contained in this set as an array, zero 222 * length if the {@code AttributeSet} is empty 223 */ 224 public Attribute[] toArray(); 225 226 /** 227 * Removes all attributes from this attribute set. 228 * 229 * @throws UnmodifiableSetException if this attribute set does not support 230 * the {@code clear()} operation 231 */ 232 public void clear(); 233 234 /** 235 * Returns {@code true} if this attribute set contains no attributes. 236 * 237 * @return {@code true} if this attribute set contains no attributes 238 */ 239 public boolean isEmpty(); 240 241 /** 242 * Compares the specified object with this attribute set for equality. 243 * Returns {@code true} if the given object is also an attribute set and the 244 * two attribute sets contain the same attribute category-attribute value 245 * mappings. This ensures that the {@code equals()} method works properly 246 * across different implementations of the {@code AttributeSet} interface. 247 * 248 * @param object to be compared for equality with this attribute set 249 * @return {@code true} if the specified object is equal to this attribute 250 * set 251 */ 252 public boolean equals(Object object); 253 254 /** 255 * Returns the hash code value for this attribute set. The hash code of an 256 * attribute set is defined to be the sum of the hash codes of each entry in 257 * the {@code AttributeSet}. This ensures that {@code t1.equals(t2)} implies 258 * that {@code t1.hashCode()==t2.hashCode()} for any two attribute sets 259 * {@code t1} and {@code t2}, as required by the general contract of 260 * {@link Object#hashCode() Object.hashCode()}. 261 * 262 * @return the hash code value for this attribute set 263 */ 264 public int hashCode(); 265 } |