J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 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 | } |