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 }