001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package javax.print.attribute.standard;
026
027 import java.util.AbstractSet;
028 import java.util.Iterator;
029 import java.util.Map;
030 import java.util.NoSuchElementException;
031 import java.util.HashMap;
032 import java.util.Set;
033
034 import javax.print.attribute.Attribute;
035 import javax.print.attribute.PrintServiceAttribute;
036
037 /**
038 * Class PrinterStateReasons is a printing attribute class, a set of
039 * enumeration values, that provides additional information about the
040 * printer's current state, i.e., information that augments the value of the
041 * printer's {@link PrinterState PrinterState} attribute.
042 * <P>
043 * Instances of {@link PrinterStateReason PrinterStateReason} do not appear in
044 * a Print Service's attribute set directly. Rather, a PrinterStateReasons
045 * attribute appears in the Print Service's attribute set. The
046 * PrinterStateReasons attribute contains zero, one, or more than one {@link
047 * PrinterStateReason PrinterStateReason} objects which pertain to the Print
048 * Service's status, and each {@link PrinterStateReason PrinterStateReason}
049 * object is associated with a {@link Severity Severity} level of REPORT
050 * (least severe), WARNING, or ERROR (most severe). The printer adds a {@link
051 * PrinterStateReason PrinterStateReason} object to the Print Service's
052 * PrinterStateReasons attribute when the corresponding condition becomes true
053 * of the printer, and the printer removes the {@link PrinterStateReason
054 * PrinterStateReason} object again when the corresponding condition becomes
055 * false, regardless of whether the Print Service's overall
056 * {@link PrinterState PrinterState} also changed.
057 * <P>
058 * Class PrinterStateReasons inherits its implementation from class {@link
059 * java.util.HashMap java.util.HashMap}. Each entry in the map consists of a
060 * {@link PrinterStateReason PrinterStateReason} object (key) mapping to a
061 * {@link Severity Severity} object (value):
062 * <P>
063 * Unlike most printing attributes which are immutable once constructed, class
064 * PrinterStateReasons is designed to be mutable; you can add {@link
065 * PrinterStateReason PrinterStateReason} objects to an existing
066 * PrinterStateReasons object and remove them again. However, like class
067 * {@link java.util.HashMap java.util.HashMap}, class PrinterStateReasons is
068 * bot multiple thread safe. If a PrinterStateReasons object will be used by
069 * multiple threads, be sure to synchronize its operations (e.g., using a
070 * synchronized map view obtained from class {@link java.util.Collections
071 * java.util.Collections}).
072 * <P>
073 * <B>IPP Compatibility:</B> The string values returned by each individual
074 * {@link PrinterStateReason PrinterStateReason} object's and the associated
075 * {@link Severity Severity} object's <CODE>toString()</CODE> methods,
076 * concatenated
077 * together with a hyphen (<CODE>"-"</CODE>) in between, gives the IPP keyword
078 * value. The category name returned by <CODE>getName()</CODE> gives the IPP
079 * attribute name.
080 * <P>
081 *
082 * @author Alan Kaminsky
083 */
084 public final class PrinterStateReasons extends
085 HashMap<PrinterStateReason, Severity> implements
086 PrintServiceAttribute {
087
088 private static final long serialVersionUID = -3731791085163619457L;
089
090 /**
091 * Construct a new, empty printer state reasons attribute; the underlying
092 * hash map has the default initial capacity and load factor.
093 */
094 public PrinterStateReasons() {
095 super ();
096 }
097
098 /**
099 * super a new, empty printer state reasons attribute; the underlying
100 * hash map has the given initial capacity and the default load factor.
101 *
102 * @param initialCapacity Initial capacity.
103 *
104 * @throws IllegalArgumentException if the initial capacity is less
105 * than zero.
106 */
107 public PrinterStateReasons(int initialCapacity) {
108 super (initialCapacity);
109 }
110
111 /**
112 * Construct a new, empty printer state reasons attribute; the underlying
113 * hash map has the given initial capacity and load factor.
114 *
115 * @param initialCapacity Initial capacity.
116 * @param loadFactor Load factor.
117 *
118 * @throws IllegalArgumentException if the initial capacity is less
119 * than zero.
120 */
121 public PrinterStateReasons(int initialCapacity, float loadFactor) {
122 super (initialCapacity, loadFactor);
123 }
124
125 /**
126 * Construct a new printer state reasons attribute that contains the same
127 * {@link PrinterStateReason PrinterStateReason}-to-{@link Severity
128 * Severity} mappings as the given map. The underlying hash map's initial
129 * capacity and load factor are as specified in the superclass constructor
130 * {@link java.util.HashMap#HashMap(java.util.Map)
131 * <CODE>HashMap(Map)</CODE>}.
132 *
133 * @param map Map to copy.
134 *
135 * @exception NullPointerException
136 * (unchecked exception) Thrown if <CODE>map</CODE> is null or if any
137 * key or value in <CODE>map</CODE> is null.
138 * @throws ClassCastException
139 * (unchecked exception) Thrown if any key in <CODE>map</CODE> is not
140 * an instance of class {@link PrinterStateReason PrinterStateReason} or
141 * if any value in <CODE>map</CODE> is not an instance of class
142 * {@link Severity Severity}.
143 */
144 public PrinterStateReasons(Map<PrinterStateReason, Severity> map) {
145 this ();
146 for (Map.Entry<PrinterStateReason, Severity> e : map.entrySet())
147 put(e.getKey(), e.getValue());
148 }
149
150 /**
151 * Adds the given printer state reason to this printer state reasons
152 * attribute, associating it with the given severity level. If this
153 * printer state reasons attribute previously contained a mapping for the
154 * given printer state reason, the old value is replaced.
155 *
156 * @param reason Printer state reason. This must be an instance of
157 * class {@link PrinterStateReason PrinterStateReason}.
158 * @param severity Severity of the printer state reason. This must be
159 * an instance of class {@link Severity Severity}.
160 *
161 * @return Previous severity associated with the given printer state
162 * reason, or <tt>null</tt> if the given printer state reason was
163 * not present.
164 *
165 * @throws NullPointerException
166 * (unchecked exception) Thrown if <CODE>reason</CODE> is null or
167 * <CODE>severity</CODE> is null.
168 * @throws ClassCastException
169 * (unchecked exception) Thrown if <CODE>reason</CODE> is not an
170 * instance of class {@link PrinterStateReason PrinterStateReason} or if
171 * <CODE>severity</CODE> is not an instance of class {@link Severity
172 * Severity}.
173 * @since 1.5
174 */
175 public Severity put(PrinterStateReason reason, Severity severity) {
176 if (reason == null) {
177 throw new NullPointerException("reason is null");
178 }
179 if (severity == null) {
180 throw new NullPointerException("severity is null");
181 }
182 return super .put((PrinterStateReason) reason,
183 (Severity) severity);
184 }
185
186 /**
187 * Get the printing attribute class which is to be used as the "category"
188 * for this printing attribute value.
189 * <P>
190 * For class PrinterStateReasons, the
191 * category is class PrinterStateReasons itself.
192 *
193 * @return Printing attribute class (category), an instance of class
194 * {@link java.lang.Class java.lang.Class}.
195 */
196 public final Class<? extends Attribute> getCategory() {
197 return PrinterStateReasons.class;
198 }
199
200 /**
201 * Get the name of the category of which this attribute value is an
202 * instance.
203 * <P>
204 * For class PrinterStateReasons, the
205 * category name is <CODE>"printer-state-reasons"</CODE>.
206 *
207 * @return Attribute category name.
208 */
209 public final String getName() {
210 return "printer-state-reasons";
211 }
212
213 /**
214 * Obtain an unmodifiable set view of the individual printer state reason
215 * attributes at the given severity level in this PrinterStateReasons
216 * attribute. Each element in the set view is a {@link PrinterStateReason
217 * PrinterStateReason} object. The only elements in the set view are the
218 * {@link PrinterStateReason PrinterStateReason} objects that map to the
219 * given severity value. The set view is backed by this
220 * PrinterStateReasons attribute, so changes to this PrinterStateReasons
221 * attribute are reflected in the set view.
222 * The set view does not support element insertion or
223 * removal. The set view's iterator does not support element removal.
224 *
225 * @param severity Severity level.
226 *
227 * @return Set view of the individual {@link PrinterStateReason
228 * PrinterStateReason} attributes at the given {@link Severity
229 * Severity} level.
230 *
231 * @exception NullPointerException
232 * (unchecked exception) Thrown if <CODE>severity</CODE> is null.
233 */
234 public Set<PrinterStateReason> printerStateReasonSet(
235 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 extends
243 AbstractSet<PrinterStateReason> {
244 private Severity mySeverity;
245 private Set myEntrySet;
246
247 public PrinterStateReasonSet(Severity severity, Set entrySet) {
248 mySeverity = severity;
249 myEntrySet = entrySet;
250 }
251
252 public int size() {
253 int result = 0;
254 Iterator iter = iterator();
255 while (iter.hasNext()) {
256 iter.next();
257 ++result;
258 }
259 return result;
260 }
261
262 public Iterator iterator() {
263 return new PrinterStateReasonSetIterator(mySeverity,
264 myEntrySet.iterator());
265 }
266 }
267
268 private class PrinterStateReasonSetIterator implements Iterator {
269 private Severity mySeverity;
270 private Iterator myIterator;
271 private Map.Entry myEntry;
272
273 public PrinterStateReasonSetIterator(Severity severity,
274 Iterator iterator) {
275 mySeverity = severity;
276 myIterator = iterator;
277 goToNext();
278 }
279
280 private void goToNext() {
281 myEntry = null;
282 while (myEntry == null && myIterator.hasNext()) {
283 myEntry = (Map.Entry) myIterator.next();
284 if ((Severity) myEntry.getValue() != mySeverity) {
285 myEntry = null;
286 }
287 }
288 }
289
290 public boolean hasNext() {
291 return myEntry != null;
292 }
293
294 public Object next() {
295 if (myEntry == null) {
296 throw new NoSuchElementException();
297 }
298 Object result = myEntry.getKey();
299 goToNext();
300 return result;
301 }
302
303 public void remove() {
304 throw new UnsupportedOperationException();
305 }
306 }
307
308 }
|