1 /* 2 * Copyright (c) 2000, 2013, 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 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 * not 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 * HashMap(Map)}. 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(reason, 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(Severity severity) { 235 if (severity == null) { 236 throw new NullPointerException("severity is null"); 237 } 238 return new PrinterStateReasonSet (severity, entrySet()); 239 } 240 241 private class PrinterStateReasonSet 242 extends AbstractSet<PrinterStateReason> 243 { 244 private Severity mySeverity; 245 246 private Set<Map.Entry<PrinterStateReason, Severity>> myEntrySet; 247 248 public PrinterStateReasonSet(Severity severity, 249 Set<Map.Entry<PrinterStateReason, Severity>> entrySet) { 250 mySeverity = severity; 251 myEntrySet = entrySet; 252 } 253 254 public int size() { 255 int result = 0; 256 Iterator<PrinterStateReason> iter = iterator(); 257 while (iter.hasNext()) { 258 iter.next(); 259 ++ result; 260 } 261 return result; 262 } 263 264 public Iterator<PrinterStateReason> iterator() { 265 return new PrinterStateReasonSetIterator(mySeverity, 266 myEntrySet.iterator()); 267 } 268 } 269 270 private class PrinterStateReasonSetIterator implements Iterator<PrinterStateReason> { 271 private Severity mySeverity; 272 private Iterator<Map.Entry<PrinterStateReason, Severity>> myIterator; 273 private Map.Entry<PrinterStateReason, Severity> myEntry; 274 275 public PrinterStateReasonSetIterator(Severity severity, 276 Iterator<Map.Entry<PrinterStateReason, Severity>> iterator) { 277 mySeverity = severity; 278 myIterator = iterator; 279 goToNext(); 280 } 281 282 private void goToNext() { 283 myEntry = null; 284 while (myEntry == null && myIterator.hasNext()) { 285 myEntry = myIterator.next(); 286 if (myEntry.getValue() != mySeverity) { 287 myEntry = null; 288 } 289 } 290 } 291 292 public boolean hasNext() { 293 return myEntry != null; 294 } 295 296 public PrinterStateReason next() { 297 if (myEntry == null) { 298 throw new NoSuchElementException(); 299 } 300 PrinterStateReason result = myEntry.getKey(); 301 goToNext(); 302 return result; 303 } 304 305 public void remove() { 306 throw new UnsupportedOperationException(); 307 } 308 } 309 310 }