View Javadoc
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         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 }