1 /*
2 * Copyright 2000-2006 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 package javax.print.attribute.standard;
26
27 import java.util.AbstractSet;
28 import java.util.Iterator;
29 import java.util.Map;
30 import java.util.NoSuchElementException;
31 import java.util.HashMap;
32 import java.util.Set;
33
34 import javax.print.attribute.Attribute;
35 import javax.print.attribute.PrintServiceAttribute;
36
37 /**
38 * Class PrinterStateReasons is a printing attribute class, a set of
39 * enumeration values, that provides additional information about the
40 * printer's current state, i.e., information that augments the value of the
41 * printer's {@link PrinterState PrinterState} attribute.
42 * <P>
43 * Instances of {@link PrinterStateReason PrinterStateReason} do not appear in
44 * a Print Service's attribute set directly. Rather, a PrinterStateReasons
45 * attribute appears in the Print Service's attribute set. The
46 * PrinterStateReasons attribute contains zero, one, or more than one {@link
47 * PrinterStateReason PrinterStateReason} objects which pertain to the Print
48 * Service's status, and each {@link PrinterStateReason PrinterStateReason}
49 * object is associated with a {@link Severity Severity} level of REPORT
50 * (least severe), WARNING, or ERROR (most severe). The printer adds a {@link
51 * PrinterStateReason PrinterStateReason} object to the Print Service's
52 * PrinterStateReasons attribute when the corresponding condition becomes true
53 * of the printer, and the printer removes the {@link PrinterStateReason
54 * PrinterStateReason} object again when the corresponding condition becomes
55 * false, regardless of whether the Print Service's overall
56 * {@link PrinterState PrinterState} also changed.
57 * <P>
58 * Class PrinterStateReasons inherits its implementation from class {@link
59 * java.util.HashMap java.util.HashMap}. Each entry in the map consists of a
60 * {@link PrinterStateReason PrinterStateReason} object (key) mapping to a
61 * {@link Severity Severity} object (value):
62 * <P>
63 * Unlike most printing attributes which are immutable once constructed, class
64 * PrinterStateReasons is designed to be mutable; you can add {@link
65 * PrinterStateReason PrinterStateReason} objects to an existing
66 * PrinterStateReasons object and remove them again. However, like class
67 * {@link java.util.HashMap java.util.HashMap}, class PrinterStateReasons is
68 * bot multiple thread safe. If a PrinterStateReasons object will be used by
69 * multiple threads, be sure to synchronize its operations (e.g., using a
70 * synchronized map view obtained from class {@link java.util.Collections
71 * java.util.Collections}).
72 * <P>
73 * <B>IPP Compatibility:</B> The string values returned by each individual
74 * {@link PrinterStateReason PrinterStateReason} object's and the associated
75 * {@link Severity Severity} object's <CODE>toString()</CODE> methods,
76 * concatenated
77 * together with a hyphen (<CODE>"-"</CODE>) in between, gives the IPP keyword
78 * value. The category name returned by <CODE>getName()</CODE> gives the IPP
79 * attribute name.
80 * <P>
81 *
82 * @author Alan Kaminsky
83 */
84 public final class PrinterStateReasons
85 extends HashMap<PrinterStateReason,Severity>
86 implements PrintServiceAttribute
87 {
88
89 private static final long serialVersionUID = -3731791085163619457L;
90
91 /**
92 * Construct a new, empty printer state reasons attribute; the underlying
93 * hash map has the default initial capacity and load factor.
94 */
95 public PrinterStateReasons() {
96 super();
97 }
98
99 /**
100 * super a new, empty printer state reasons attribute; the underlying
101 * hash map has the given initial capacity and the default load factor.
102 *
103 * @param initialCapacity Initial capacity.
104 *
105 * @throws IllegalArgumentException if the initial capacity is less
106 * than zero.
107 */
108 public PrinterStateReasons(int initialCapacity) {
109 super (initialCapacity);
110 }
111
112 /**
113 * Construct a new, empty printer state reasons attribute; the underlying
114 * hash map has the given initial capacity and load factor.
115 *
116 * @param initialCapacity Initial capacity.
117 * @param loadFactor Load factor.
118 *
119 * @throws IllegalArgumentException if the initial capacity is less
120 * than zero.
121 */
122 public PrinterStateReasons(int initialCapacity, float loadFactor) {
123 super (initialCapacity, loadFactor);
124 }
125
126 /**
127 * Construct a new printer state reasons attribute that contains the same
128 * {@link PrinterStateReason PrinterStateReason}-to-{@link Severity
129 * Severity} mappings as the given map. The underlying hash map's initial
130 * capacity and load factor are as specified in the superclass constructor
131 * {@link java.util.HashMap#HashMap(java.util.Map)
132 * <CODE>HashMap(Map)</CODE>}.
133 *
134 * @param map Map to copy.
135 *
136 * @exception NullPointerException
137 * (unchecked exception) Thrown if <CODE>map</CODE> is null or if any
138 * key or value in <CODE>map</CODE> is null.
139 * @throws ClassCastException
140 * (unchecked exception) Thrown if any key in <CODE>map</CODE> is not
141 * an instance of class {@link PrinterStateReason PrinterStateReason} or
142 * if any value in <CODE>map</CODE> is not an instance of class
143 * {@link Severity Severity}.
144 */
145 public PrinterStateReasons(Map<PrinterStateReason,Severity> map) {
146 this();
147 for (Map.Entry<PrinterStateReason,Severity> e : map.entrySet())
148 put(e.getKey(), e.getValue());
149 }
150
151 /**
152 * Adds the given printer state reason to this printer state reasons
153 * attribute, associating it with the given severity level. If this
154 * printer state reasons attribute previously contained a mapping for the
155 * given printer state reason, the old value is replaced.
156 *
157 * @param reason Printer state reason. This must be an instance of
158 * class {@link PrinterStateReason PrinterStateReason}.
159 * @param severity Severity of the printer state reason. This must be
160 * an instance of class {@link Severity Severity}.
161 *
162 * @return Previous severity associated with the given printer state
163 * reason, or <tt>null</tt> if the given printer state reason was
164 * not present.
165 *
166 * @throws NullPointerException
167 * (unchecked exception) Thrown if <CODE>reason</CODE> is null or
168 * <CODE>severity</CODE> is null.
169 * @throws ClassCastException
170 * (unchecked exception) Thrown if <CODE>reason</CODE> is not an
171 * instance of class {@link PrinterStateReason PrinterStateReason} or if
172 * <CODE>severity</CODE> is not an instance of class {@link Severity
173 * Severity}.
174 * @since 1.5
175 */
176 public Severity put(PrinterStateReason reason, Severity severity) {
177 if (reason == null) {
178 throw new NullPointerException("reason is null");
179 }
180 if (severity == null) {
181 throw new NullPointerException("severity is null");
182 }
183 return super.put((PrinterStateReason) reason,
184 (Severity) severity);
185 }
186
187 /**
188 * Get the printing attribute class which is to be used as the "category"
189 * for this printing attribute value.
190 * <P>
191 * For class PrinterStateReasons, the
192 * category is class PrinterStateReasons itself.
193 *
194 * @return Printing attribute class (category), an instance of class
195 * {@link java.lang.Class java.lang.Class}.
196 */
197 public final Class<? extends Attribute> getCategory() {
198 return PrinterStateReasons.class;
199 }
200
201 /**
202 * Get the name of the category of which this attribute value is an
203 * instance.
204 * <P>
205 * For class PrinterStateReasons, the
206 * category name is <CODE>"printer-state-reasons"</CODE>.
207 *
208 * @return Attribute category name.
209 */
210 public final String getName() {
211 return "printer-state-reasons";
212 }
213
214 /**
215 * Obtain an unmodifiable set view of the individual printer state reason
216 * attributes at the given severity level in this PrinterStateReasons
217 * attribute. Each element in the set view is a {@link PrinterStateReason
218 * PrinterStateReason} object. The only elements in the set view are the
219 * {@link PrinterStateReason PrinterStateReason} objects that map to the
220 * given severity value. The set view is backed by this
221 * PrinterStateReasons attribute, so changes to this PrinterStateReasons
222 * attribute are reflected in the set view.
223 * The set view does not support element insertion or
224 * removal. The set view's iterator does not support element removal.
225 *
226 * @param severity Severity level.
227 *
228 * @return Set view of the individual {@link PrinterStateReason
229 * PrinterStateReason} attributes at the given {@link Severity
230 * Severity} level.
231 *
232 * @exception NullPointerException
233 * (unchecked exception) Thrown if <CODE>severity</CODE> is null.
234 */
235 public Set<PrinterStateReason> printerStateReasonSet(Severity severity) {
236 if (severity == null) {
237 throw new NullPointerException("severity is null");
238 }
239 return new PrinterStateReasonSet (severity, entrySet());
240 }
241
242 private class PrinterStateReasonSet
243 extends AbstractSet<PrinterStateReason>
244 {
245 private Severity mySeverity;
246 private Set myEntrySet;
247
248 public PrinterStateReasonSet(Severity severity, Set entrySet) {
249 mySeverity = severity;
250 myEntrySet = entrySet;
251 }
252
253 public int size() {
254 int result = 0;
255 Iterator iter = iterator();
256 while (iter.hasNext()) {
257 iter.next();
258 ++ result;
259 }
260 return result;
261 }
262
263 public Iterator iterator() {
264 return new PrinterStateReasonSetIterator(mySeverity,
265 myEntrySet.iterator());
266 }
267 }
268
269 private class PrinterStateReasonSetIterator implements Iterator {
270 private Severity mySeverity;
271 private Iterator myIterator;
272 private Map.Entry myEntry;
273
274 public PrinterStateReasonSetIterator(Severity severity,
275 Iterator iterator) {
276 mySeverity = severity;
277 myIterator = iterator;
278 goToNext();
279 }
280
281 private void goToNext() {
282 myEntry = null;
283 while (myEntry == null && myIterator.hasNext()) {
284 myEntry = (Map.Entry) myIterator.next();
285 if ((Severity) myEntry.getValue() != mySeverity) {
286 myEntry = null;
287 }
288 }
289 }
290
291 public boolean hasNext() {
292 return myEntry != null;
293 }
294
295 public Object next() {
296 if (myEntry == null) {
297 throw new NoSuchElementException();
298 }
299 Object result = myEntry.getKey();
300 goToNext();
301 return result;
302 }
303
304 public void remove() {
305 throw new UnsupportedOperationException();
306 }
307 }
308
309 }
Save This Page