|
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 } |