AttributeSetUtilities


1   /*
2    * @(#)AttributeSetUtilities.java   1.10 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   
9   package javax.print.attribute;
10  
11  import java.io.Serializable  ;
12  
13  /**
14   * Class AttributeSetUtilities provides static methods for manipulating
15   * AttributeSets.
16   * <ul>
17   * <li>Methods for creating unmodifiable and synchronized views of attribute
18   * sets. 
19   * <li>operations useful for building 
20   * implementations of interface {@link AttributeSet AttributeSet}
21   * </ul>
22   * <P>
23   * An <B>unmodifiable view</B> <I>U</I> of an AttributeSet <I>S</I> provides a 
24   * client with "read-only" access to <I>S</I>. Query operations on <I>U</I> 
25   * "read through" to <I>S</I>; thus, changes in <I>S</I> are reflected in 
26   * <I>U</I>. However, any attempt to modify <I>U</I>,
27   *  results in an UnmodifiableSetException.
28   * The unmodifiable view object <I>U</I> will be serializable if the
29   * attribute set object <I>S</I> is serializable. 
30   * <P>
31   * A <B>synchronized view</B> <I>V</I> of an attribute set <I>S</I> provides a 
32   * client with synchronized (multiple thread safe) access to <I>S</I>. Each 
33   * operation of <I>V</I> is synchronized using <I>V</I> itself as the lock 
34   * object and then merely invokes the corresponding operation of <I>S</I>. In 
35   * order to guarantee mutually exclusive access, it is critical that all
36   * access to <I>S</I> is accomplished through <I>V</I>. The synchronized view
37   * object <I>V</I> will be serializable if the attribute set object <I>S</I>
38   * is serializable. 
39   * <P>
40   * As mentioned in the package description of javax.print, a null reference 
41   * parameter to methods is 
42   * incorrect unless explicitly documented on the method as having a meaningful
43   * interpretation.  Usage to the contrary is incorrect coding and may result in 
44   * a run time exception either immediately 
45   * or at some later time. IllegalArgumentException and NullPointerException 
46   * are examples of typical and acceptable run time exceptions for such cases.
47   *
48   * @author  Alan Kaminsky
49   */
50  public final class AttributeSetUtilities {
51  
52      /* Suppress default constructor, ensuring non-instantiability.
53       */
54      private AttributeSetUtilities() {
55      }
56  
57      /**
58        * @serial include
59        */
60      private static class UnmodifiableAttributeSet 
61      implements AttributeSet  , Serializable   {
62      
63      private AttributeSet   attrset;   
64  
65      /* Unmodifiable view of the underlying attribute set. 
66       */
67      public UnmodifiableAttributeSet(AttributeSet   attributeSet) {
68  
69          attrset = attributeSet;
70      }
71  
72      public Attribute   get(Class  <?> key) {
73          return attrset.get(key);
74      }
75  
76      public boolean add(Attribute   attribute) {
77          throw new UnmodifiableSetException  ();
78      }
79  
80      public synchronized boolean remove(Class  <?> category) {
81          throw new UnmodifiableSetException  ();
82      }
83  
84      public boolean remove(Attribute   attribute) {
85          throw new UnmodifiableSetException  ();
86      }
87  
88      public boolean containsKey(Class  <?> category) {
89          return attrset.containsKey(category);
90      }
91      
92      public boolean containsValue(Attribute   attribute) {
93          return attrset.containsValue(attribute);
94      }
95      
96      public boolean addAll(AttributeSet   attributes) {
97          throw new UnmodifiableSetException  ();
98      }
99  
100     public int size() {
101         return attrset.size();
102     }
103 
104     public Attribute  [] toArray() {
105         return attrset.toArray();
106     }
107     
108     public void clear() {
109         throw new UnmodifiableSetException  ();
110     }
111 
112     public boolean isEmpty() {
113         return attrset.isEmpty();
114     }
115 
116     public boolean equals(Object   o) {
117         return attrset.equals (o);
118     }
119 
120     public int hashCode() {
121         return attrset.hashCode();
122     }
123 
124     }
125 
126     /**
127       * @serial include
128       */
129     private static class UnmodifiableDocAttributeSet
130     extends UnmodifiableAttributeSet
131     implements DocAttributeSet  , Serializable   {
132 
133     public UnmodifiableDocAttributeSet(DocAttributeSet   attributeSet) {
134 
135         super (attributeSet);
136     }
137     }
138     
139     /**
140       * @serial include
141       */
142     private static class UnmodifiablePrintRequestAttributeSet
143     extends UnmodifiableAttributeSet
144     implements PrintRequestAttributeSet  , Serializable  
145     {
146     public UnmodifiablePrintRequestAttributeSet
147         (PrintRequestAttributeSet   attributeSet) {
148 
149         super (attributeSet);
150     }
151     }
152 
153     /**
154       * @serial include
155       */
156     private static class UnmodifiablePrintJobAttributeSet
157     extends UnmodifiableAttributeSet
158     implements PrintJobAttributeSet  , Serializable  
159     {
160     public UnmodifiablePrintJobAttributeSet
161         (PrintJobAttributeSet   attributeSet) {
162 
163         super (attributeSet);
164     }
165     }
166 
167     /**
168       * @serial include
169       */
170     private static class UnmodifiablePrintServiceAttributeSet
171     extends UnmodifiableAttributeSet
172     implements PrintServiceAttributeSet  , Serializable  
173     {
174     public UnmodifiablePrintServiceAttributeSet
175         (PrintServiceAttributeSet   attributeSet) {
176 
177         super (attributeSet);
178     }
179     }
180 
181     /**
182      * Creates an unmodifiable view of the given attribute set.
183      *
184      * @param  attributeSet  Underlying attribute set.
185      *
186      * @return  Unmodifiable view of <CODE>attributeSet</CODE>.
187      *
188      * @exception  NullPointerException
189      *     Thrown if <CODE>attributeSet</CODE> is null. Null is never a
190      */
191     public static AttributeSet   unmodifiableView(AttributeSet   attributeSet) {
192     if (attributeSet == null) {
193         throw new NullPointerException  ();
194     }
195 
196     return new UnmodifiableAttributeSet(attributeSet);
197     }
198 
199     /**
200      * Creates an unmodifiable view of the given doc attribute set.
201      *
202      * @param  attributeSet  Underlying doc attribute set.
203      *
204      * @return  Unmodifiable view of <CODE>attributeSet</CODE>.
205      *
206      * @exception  NullPointerException
207      *     Thrown if <CODE>attributeSet</CODE> is null.
208      */
209     public static DocAttributeSet   unmodifiableView
210     (DocAttributeSet   attributeSet) {
211     if (attributeSet == null) {
212         throw new NullPointerException  ();
213     }
214     return new UnmodifiableDocAttributeSet(attributeSet);
215     }
216     
217     /**
218      * Creates an unmodifiable view of the given print request attribute set.
219      *
220      * @param  attributeSet  Underlying print request attribute set.
221      *
222      * @return  Unmodifiable view of <CODE>attributeSet</CODE>.
223      *
224      * @exception  NullPointerException
225      *     Thrown if <CODE>attributeSet</CODE> is null.
226      */
227     public static PrintRequestAttributeSet   
228     unmodifiableView(PrintRequestAttributeSet   attributeSet) {
229     if (attributeSet == null) {
230         throw new NullPointerException  ();
231     }
232     return new UnmodifiablePrintRequestAttributeSet(attributeSet);
233     }
234     
235     /**
236      * Creates an unmodifiable view of the given print job attribute set.
237      *
238      * @param  attributeSet  Underlying print job attribute set.
239      *
240      * @return  Unmodifiable view of <CODE>attributeSet</CODE>.
241      *
242      * @exception  NullPointerException
243      *     Thrown if <CODE>attributeSet</CODE> is null.
244      */
245     public static PrintJobAttributeSet   
246     unmodifiableView(PrintJobAttributeSet   attributeSet) {
247         if (attributeSet == null) {
248         throw new NullPointerException  ();
249     }
250     return new UnmodifiablePrintJobAttributeSet(attributeSet);
251     }
252     
253     /**
254      * Creates an unmodifiable view of the given print service attribute set.
255      *
256      * @param  attributeSet  Underlying print service attribute set.
257      *
258      * @return  Unmodifiable view of <CODE>attributeSet</CODE>.
259      *
260      * @exception  NullPointerException
261      *     Thrown if <CODE>attributeSet</CODE> is null.
262      */
263     public static PrintServiceAttributeSet  
264     unmodifiableView(PrintServiceAttributeSet   attributeSet) {
265     if (attributeSet == null) {
266         throw new NullPointerException  ();
267     }
268     return new UnmodifiablePrintServiceAttributeSet (attributeSet);
269     }
270 
271     /**
272       * @serial include
273       */
274     private static class SynchronizedAttributeSet   
275                     implements AttributeSet  , Serializable   {
276     
277     private AttributeSet   attrset;
278         
279     public SynchronizedAttributeSet(AttributeSet   attributeSet) {
280         attrset = attributeSet;
281     }
282 
283     public synchronized Attribute   get(Class  <?> category) {
284         return attrset.get(category);
285     }
286 
287     public synchronized boolean add(Attribute   attribute) {
288         return attrset.add(attribute);
289     }
290 
291     public synchronized boolean remove(Class  <?> category) {
292         return attrset.remove(category);
293     }
294 
295     public synchronized boolean remove(Attribute   attribute) {
296         return attrset.remove(attribute);
297     }
298 
299     public synchronized boolean containsKey(Class  <?> category) {
300         return attrset.containsKey(category);
301     }
302         
303     public synchronized boolean containsValue(Attribute   attribute) {
304         return attrset.containsValue(attribute);
305     }
306     
307     public synchronized boolean addAll(AttributeSet   attributes) {
308         return attrset.addAll(attributes);
309     }
310 
311     public synchronized int size() {
312         return attrset.size();
313     }
314 
315     public synchronized Attribute  [] toArray() {
316         return attrset.toArray();
317     }
318     
319     public synchronized void clear() {
320         attrset.clear();
321     }
322 
323     public synchronized boolean isEmpty() {
324         return attrset.isEmpty();
325     }
326 
327     public synchronized boolean equals(Object   o) {
328         return attrset.equals (o);
329     }
330 
331     public synchronized int hashCode() {
332         return attrset.hashCode();
333     }
334     }
335     
336     /**
337       * @serial include
338       */
339     private static class SynchronizedDocAttributeSet
340     extends SynchronizedAttributeSet
341     implements DocAttributeSet  , Serializable   {
342 
343     public SynchronizedDocAttributeSet(DocAttributeSet   attributeSet) {
344         super(attributeSet);
345     }
346     }
347 
348     /**
349       * @serial include
350       */
351     private static class SynchronizedPrintRequestAttributeSet
352     extends SynchronizedAttributeSet
353     implements PrintRequestAttributeSet  , Serializable   {
354     
355     public SynchronizedPrintRequestAttributeSet
356         (PrintRequestAttributeSet   attributeSet) {
357         super(attributeSet);
358     }
359     }
360 
361     /**
362       * @serial include
363       */
364     private static class SynchronizedPrintJobAttributeSet
365     extends SynchronizedAttributeSet
366     implements PrintJobAttributeSet  , Serializable   {
367 
368     public SynchronizedPrintJobAttributeSet
369         (PrintJobAttributeSet   attributeSet) {
370         super(attributeSet);
371     }
372     }
373 
374     /**
375       * @serial include
376       */
377     private static class SynchronizedPrintServiceAttributeSet
378     extends SynchronizedAttributeSet
379     implements PrintServiceAttributeSet  , Serializable   {
380     public SynchronizedPrintServiceAttributeSet
381         (PrintServiceAttributeSet   attributeSet) {
382         super(attributeSet);
383     }
384     }
385         
386     /**
387      * Creates a synchronized view of the given attribute set.
388      *
389      * @param  attributeSet  Underlying attribute set.
390      *
391      * @return  Synchronized view of <CODE>attributeSet</CODE>.
392      *
393      * @exception  NullPointerException
394      *     Thrown if <CODE>attributeSet</CODE> is null.
395      */
396     public static AttributeSet   synchronizedView
397     (AttributeSet   attributeSet) {
398     if (attributeSet == null) {
399         throw new NullPointerException  ();
400     }
401     return new SynchronizedAttributeSet(attributeSet);
402     }
403   
404     /**
405      * Creates a synchronized view of the given doc attribute set.
406      *
407      * @param  attributeSet  Underlying doc attribute set.
408      *
409      * @return  Synchronized view of <CODE>attributeSet</CODE>.
410      *
411      * @exception  NullPointerException
412      *     Thrown if <CODE>attributeSet</CODE> is null.
413      */
414     public static DocAttributeSet  
415     synchronizedView(DocAttributeSet   attributeSet) {
416     if (attributeSet == null) {
417         throw new NullPointerException  ();
418     }
419     return new SynchronizedDocAttributeSet(attributeSet);
420     }
421     
422     /**
423      * Creates a synchronized view of the given print request attribute set.
424      *
425      * @param  attributeSet  Underlying print request attribute set.
426      *
427      * @return  Synchronized view of <CODE>attributeSet</CODE>.
428      *
429      * @exception  NullPointerException
430      *     Thrown if <CODE>attributeSet</CODE> is null.
431      */
432     public static PrintRequestAttributeSet   
433     synchronizedView(PrintRequestAttributeSet   attributeSet) {
434     if (attributeSet == null) {
435         throw new NullPointerException  ();
436     }
437     return new SynchronizedPrintRequestAttributeSet(attributeSet);
438     }
439 
440     /**
441      * Creates a synchronized view of the given print job attribute set.
442      *
443      * @param  attributeSet  Underlying print job attribute set.
444      *
445      * @return  Synchronized view of <CODE>attributeSet</CODE>.
446      *
447      * @exception  NullPointerException
448      *     Thrown if <CODE>attributeSet</CODE> is null.
449      */
450     public static PrintJobAttributeSet  
451     synchronizedView(PrintJobAttributeSet   attributeSet) {
452     if (attributeSet == null) {
453         throw new NullPointerException  ();
454     }
455     return new SynchronizedPrintJobAttributeSet(attributeSet);
456     }
457 
458     /**
459      * Creates a synchronized view of the given print service attribute set.
460      *
461      * @param  attributeSet  Underlying print service attribute set.
462      *
463      * @return  Synchronized view of <CODE>attributeSet</CODE>.
464      */
465     public static PrintServiceAttributeSet  
466     synchronizedView(PrintServiceAttributeSet   attributeSet) {
467     if (attributeSet == null) {
468         throw new NullPointerException  ();
469     }
470     return new SynchronizedPrintServiceAttributeSet(attributeSet);
471     }
472     
473 
474     /**
475      * Verify that the given object is a {@link java.lang.Class Class} that 
476      * implements the given interface, which is assumed to be interface {@link 
477      * Attribute Attribute} or a subinterface thereof. 
478      *
479      * @param  object     Object to test.
480      * @param  interfaceName  Interface the object must implement.
481      *
482      * @return  If <CODE>object</CODE> is a {@link java.lang.Class Class}
483      *          that implements <CODE>interfaceName</CODE>, 
484      *          <CODE>object</CODE> is returned downcast to type {@link 
485      *          java.lang.Class Class}; otherwise an exception is thrown. 
486      *
487      * @exception  NullPointerException
488      *     (unchecked exception) Thrown if <CODE>object</CODE> is null.
489      * @exception  ClassCastException
490      *     (unchecked exception) Thrown if <CODE>object</CODE> is not a 
491      *     {@link java.lang.Class Class} that implements 
492      *     <CODE>interfaceName</CODE>. 
493      */
494     public static Class  <?>
495     verifyAttributeCategory(Object   object, Class  <?> interfaceName) { 
496 
497     Class   result = (Class  ) object;
498     if (interfaceName.isAssignableFrom (result)) {
499         return result;
500     }
501     else {
502         throw new ClassCastException  ();
503     }
504     }
505     
506     /**
507      * Verify that the given object is an instance of the given interface, which 
508      * is assumed to be interface {@link Attribute Attribute} or a subinterface 
509      * thereof. 
510      *
511      * @param  object     Object to test.
512      * @param  interfaceName  Interface of which the object must be an instance.
513      *
514      * @return  If <CODE>object</CODE> is an instance of
515      *          <CODE>interfaceName</CODE>, <CODE>object</CODE> is returned 
516      *          downcast to type {@link Attribute Attribute}; otherwise an 
517      *          exception is thrown. 
518      *
519      * @exception  NullPointerException
520      *     (unchecked exception) Thrown if <CODE>object</CODE> is null.
521      * @exception  ClassCastException
522      *     (unchecked exception) Thrown if <CODE>object</CODE> is not an 
523      *     instance of <CODE>interfaceName</CODE>. 
524      */
525     public static Attribute  
526     verifyAttributeValue(Object   object, Class  <?> interfaceName) {
527 
528     if (object == null) {
529         throw new NullPointerException  ();
530     }
531     else if (interfaceName.isInstance (object)) {
532         return (Attribute  ) object;
533     } else {
534         throw new ClassCastException  ();
535     }
536     }
537     
538     /**
539      * Verify that the given attribute category object is equal to the
540      * category of the given attribute value object. If so, this method 
541      * returns doing nothing. If not, this method throws an exception. 
542      *
543      * @param  category   Attribute category to test.
544      * @param  attribute  Attribute value to test.
545      *
546      * @exception  NullPointerException
547      *     (unchecked exception) Thrown if the <CODE>category</CODE> is 
548      *     null or if the <CODE>attribute</CODE> is null. 
549      * @exception  IllegalArgumentException
550      *     (unchecked exception) Thrown if the <CODE>category</CODE> is not 
551      *     equal to the category of the <CODE>attribute</CODE>. 
552      */
553     public static void 
554     verifyCategoryForValue(Class  <?> category, Attribute   attribute) {
555 
556     if (!category.equals (attribute.getCategory())) {
557         throw new IllegalArgumentException  ();
558     }
559     }
560 }
561
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags