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