1 /*
2 * Copyright 2000-2004 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 * <CODE>getCategory()</CODE>} 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) <CODE>add(Attribute)</CODE>}
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() <CODE>Object.hashCode()</CODE>}.
305 *
306 * @return The hash code value for this attribute set.
307 */
308 public int hashCode();
309
310 }
Save This Page