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 }