001    /* AttributeSetUtilities.java -- 
002       Copyright (C) 2003, 2004, 2006  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.print.attribute;
039    
040    import java.io.Serializable;
041    
042    /**
043     * <code>AttributeSetUtilities</code> provides static methods for working
044     * with <code>AttributeSet</code>s.
045     * <p>
046     * For every type of an attribute set available in the Java Print Service API
047     * are methods provided to get an unmodifiable view of an attribute set.
048     * This unmodifiable view provides a read-only version of the attribute
049     * set which throws {@link javax.print.attribute.UnmodifiableSetException}s
050     * if state changing methods are invoked.
051     * </p>
052     * <p>
053     * Methods for getting a synchronized view of an attribute set are also 
054     * available. This view provides synchronized (thread safe) access to the
055     * underlying wrapped attribute set.
056     * </P>
057     * <p>
058     * Three static methods for the implementation of own AttributeSets
059     * are provided, which verify that:
060     * <ul>
061     * <li>the given object is an attribute of the given interface.</li>
062     * <li>the category of given attribute is equals to a given category.</li>
063     * <li>the given object is a <code>Class</code> that implements the given 
064     * interface name.</li>
065     * </ul>
066     * 
067     */
068    public final class AttributeSetUtilities
069    {
070      /**
071       * This class isn't intended to be instantiated.
072       */
073      private AttributeSetUtilities() 
074      {
075        // only static methods
076      }
077    
078      private static class UnmodifiableAttributeSet
079        implements AttributeSet, Serializable
080      {
081        private AttributeSet attrset;
082    
083        public UnmodifiableAttributeSet(AttributeSet attributeSet)
084        {
085          if (attributeSet == null)
086            throw new NullPointerException("attributeSet may not be null");
087    
088          this.attrset = attributeSet;
089        }
090    
091        public boolean add(Attribute attribute)
092        {
093          throw new UnmodifiableSetException();
094        }
095    
096        public boolean addAll(AttributeSet attributes)
097        {
098          throw new UnmodifiableSetException();
099        }
100        
101        public void clear()
102        {
103          throw new UnmodifiableSetException();
104        }
105    
106        public boolean containsKey(Class category)
107        {
108          return attrset.containsKey(category);
109        }
110    
111        public boolean containsValue(Attribute attribute)
112        {
113          return attrset.containsValue(attribute);
114        }
115    
116        public boolean equals(Object obj)
117        {
118          return attrset.equals(obj);
119        }
120        
121        public Attribute get(Class interfaceName)
122        {
123          return attrset.get(interfaceName);
124        }
125    
126        public int hashCode()
127        {
128          return attrset.hashCode();
129        }
130        
131        public boolean isEmpty()
132        {
133          return attrset.isEmpty();
134        }
135    
136        public boolean remove(Class category)
137        {
138          throw new UnmodifiableSetException();
139        }
140    
141        public boolean remove(Attribute attribute)
142        {
143          throw new UnmodifiableSetException();
144        }
145    
146        public int size()
147        {
148          return attrset.size();
149        }
150    
151        public Attribute[] toArray()
152        {
153          return attrset.toArray();
154        }
155      }
156    
157      private static class UnmodifiableDocAttributeSet
158        extends UnmodifiableAttributeSet
159        implements DocAttributeSet, Serializable
160      {
161        public UnmodifiableDocAttributeSet(DocAttributeSet attributeSet)
162        {
163          super(attributeSet);
164        }
165      }
166    
167      private static class UnmodifiablePrintJobAttributeSet
168        extends UnmodifiableAttributeSet
169        implements PrintJobAttributeSet, Serializable
170      {
171        public UnmodifiablePrintJobAttributeSet(PrintJobAttributeSet attributeSet)
172        {
173          super(attributeSet);
174        }
175      }
176    
177      private static class UnmodifiablePrintRequestAttributeSet
178        extends UnmodifiableAttributeSet
179        implements PrintRequestAttributeSet, Serializable
180      {
181        public UnmodifiablePrintRequestAttributeSet(PrintRequestAttributeSet attributeSet)
182        {
183          super(attributeSet);
184        }
185      }
186    
187      private static class UnmodifiablePrintServiceAttributeSet
188        extends UnmodifiableAttributeSet
189        implements PrintServiceAttributeSet, Serializable
190      {
191        public UnmodifiablePrintServiceAttributeSet(PrintServiceAttributeSet attributeSet)
192        {
193          super(attributeSet);
194        }
195      }
196    
197      private static class SynchronizedAttributeSet
198        implements AttributeSet, Serializable
199      {
200        private AttributeSet attrset;
201    
202        public SynchronizedAttributeSet(AttributeSet attributeSet)
203        {
204          if (attributeSet == null)
205            throw new NullPointerException("attributeSet may not be null");
206    
207          attrset = attributeSet;
208        }
209    
210        public synchronized boolean add(Attribute attribute)
211        {
212          return attrset.add(attribute);
213        }
214    
215        public synchronized boolean addAll(AttributeSet attributes)
216        {
217          return attrset.addAll(attributes);
218        }
219        
220        public synchronized void clear()
221        {
222          attrset.clear();
223        }
224    
225        public synchronized boolean containsKey(Class category)
226        {
227          return attrset.containsKey(category);
228        }
229    
230        public synchronized boolean containsValue(Attribute attribute)
231        {
232          return attrset.containsValue(attribute);
233        }
234    
235        public synchronized boolean equals(Object obj)
236        {
237          return attrset.equals(obj);
238        }
239        
240        public synchronized Attribute get(Class interfaceName)
241        {
242          return attrset.get(interfaceName);
243        }
244    
245        public synchronized int hashCode()
246        {
247          return attrset.hashCode();
248        }
249        
250        public synchronized boolean isEmpty()
251        {
252          return attrset.isEmpty();
253        }
254    
255        public synchronized boolean remove(Class category)
256        {
257          return attrset.remove(category);
258        }
259    
260        public synchronized boolean remove(Attribute attribute)
261        {
262          return attrset.remove(attribute);
263        }
264    
265        public synchronized int size()
266        {
267          return attrset.size();
268        }
269    
270        public synchronized Attribute[] toArray()
271        {
272          return attrset.toArray();
273        }
274      }
275    
276      private static class SynchronizedDocAttributeSet
277        extends SynchronizedAttributeSet
278        implements DocAttributeSet, Serializable
279      {
280        public SynchronizedDocAttributeSet(DocAttributeSet attributeSet)
281        {
282          super(attributeSet);
283        }
284      }
285    
286      private static class SynchronizedPrintJobAttributeSet
287        extends SynchronizedAttributeSet
288        implements PrintJobAttributeSet, Serializable
289      {
290        public SynchronizedPrintJobAttributeSet(PrintJobAttributeSet attributeSet)
291        {
292          super(attributeSet);
293        }
294      }
295    
296      private static class SynchronizedPrintRequestAttributeSet
297        extends SynchronizedAttributeSet
298        implements PrintRequestAttributeSet, Serializable
299      {
300        public SynchronizedPrintRequestAttributeSet(PrintRequestAttributeSet attributeSet)
301        {
302          super(attributeSet);
303        }
304      }
305    
306      private static class SynchronizedPrintServiceAttributeSet
307        extends SynchronizedAttributeSet
308        implements PrintServiceAttributeSet, Serializable
309      {
310        public SynchronizedPrintServiceAttributeSet(PrintServiceAttributeSet attributeSet)
311        {
312          super(attributeSet);
313        }
314      }
315    
316      /**
317       * Returns a synchronized view of the given attribute set.
318       *
319       * @param attributeSet the set to synchronize.
320       * @return The sychronized attribute set.
321       */
322      public static AttributeSet synchronizedView(AttributeSet attributeSet)
323      {
324        return new SynchronizedAttributeSet(attributeSet);
325      }
326    
327      /**
328       * Returns a synchronized view of the given attribute set.
329       *
330       * @param attributeSet the set to synchronize.
331       * @return The sychronized attribute set.
332       */
333      public static DocAttributeSet synchronizedView(DocAttributeSet attributeSet)
334      {
335        return new SynchronizedDocAttributeSet(attributeSet);
336      }
337      
338      /**
339       * Returns a synchronized view of the given attribute set.
340       *
341       * @param attributeSet the set to synchronize.
342       * @return The sychronized attribute set.
343       */
344      public static PrintJobAttributeSet synchronizedView(PrintJobAttributeSet attributeSet)
345      {
346        return new SynchronizedPrintJobAttributeSet(attributeSet);
347      }
348      
349      /**
350       * Returns a synchronized view of the given attribute set.
351       *
352       * @param attributeSet the set to synchronize.
353       * @return The sychronized attribute set.
354       */
355      public static PrintRequestAttributeSet synchronizedView(PrintRequestAttributeSet attributeSet)
356      {
357        return new SynchronizedPrintRequestAttributeSet(attributeSet);
358      }
359      
360      /**
361       * Returns a synchronized view of the given attribute set.
362       *
363       * @param attributeSet the set to synchronize.
364       * @return The sychronized attribute set.
365       */
366      public static PrintServiceAttributeSet synchronizedView(PrintServiceAttributeSet attributeSet)
367      {
368        return new SynchronizedPrintServiceAttributeSet(attributeSet);
369      }
370      
371      /**
372       * Returns an unmodifiable view of the given attribute set.
373       *
374       * @param attributeSet the set to make unmodifiable.
375       * @return The unmodifiable attribute set.
376       */
377      public static AttributeSet unmodifiableView(AttributeSet attributeSet)
378      {
379        return new UnmodifiableAttributeSet(attributeSet);
380      }
381      
382      /**
383       * Returns an unmodifiable view of the given attribute set.
384       *
385       * @param attributeSet the set to make unmodifiable.
386       * @return The unmodifiable attribute set.
387       */
388      public static DocAttributeSet unmodifiableView(DocAttributeSet attributeSet)
389      {
390        return new UnmodifiableDocAttributeSet(attributeSet);
391      }
392      
393      /**
394       * Returns an unmodifiable view of the given attribute set.
395       *
396       * @param attributeSet the set to make unmodifiable.
397       * @return The unmodifiable attribute set.
398       */
399      public static PrintJobAttributeSet unmodifiableView(PrintJobAttributeSet attributeSet)
400      {
401        return new UnmodifiablePrintJobAttributeSet(attributeSet);
402      }
403      
404      /**
405       * Returns an unmodifiable view of the given attribute set.
406       *
407       * @param attributeSet the set to make unmodifiable.
408       * @return The unmodifiable attribute set.
409       */
410      public static PrintRequestAttributeSet unmodifiableView(PrintRequestAttributeSet attributeSet)
411      {
412        return new UnmodifiablePrintRequestAttributeSet(attributeSet);
413      }
414      
415      /**
416       * Returns an unmodifiable view of the given attribute set.
417       *
418       * @param attributeSet the set to make unmodifiable.
419       * @return The unmodifiable attribute set.
420       */
421      public static PrintServiceAttributeSet unmodifiableView(PrintServiceAttributeSet attributeSet)
422      {
423        return new UnmodifiablePrintServiceAttributeSet(attributeSet);
424      }
425    
426      /**
427       * Verifies that the given object is a <code>Class</code> that
428       * implements the given interface name and returns it casted.
429       * 
430       * @param object the object to test.
431       * @param interfaceName the <code>Class</code> to verify against.
432       * @return object casted to <code>Class</code>
433       *
434       * @exception ClassCastException if object is not a <code>Class</code>
435       * that implements interfaceName
436       * @exception NullPointerException if object is null
437       */
438      public static Class<?> verifyAttributeCategory(Object object,
439                                                     Class<?> interfaceName)
440      {
441        if (object == null)
442          throw new NullPointerException("object may not be null");
443    
444        Class clazz = (Class) object;
445    
446        if (interfaceName.isAssignableFrom(clazz))
447          return clazz;
448    
449        throw new ClassCastException();
450      }
451      
452      /**
453       * Verifies that the given object is an attribute of the given interface.
454       * and returns it casted to the interface type.
455       * 
456       * @param object the object to test.
457       * @param interfaceName the <code>Class</code> to verify against.
458       * @return the object casted to <code>Attribute</code>
459       *
460       * @exception ClassCastException if object is no instance of interfaceName.
461       * @exception NullPointerException if object is null
462       */
463      public static Attribute verifyAttributeValue(Object object,
464                                                   Class<?> interfaceName)
465      {
466        if (object == null)
467          throw new NullPointerException("object may not be null");
468    
469        if (interfaceName.isInstance(object))
470          return (Attribute) object;
471    
472        throw new ClassCastException();
473      }
474    
475      /**
476       * Verifies that the category of attribute is equals to the given category
477       * class.
478       * 
479       * @param category the category to test.
480       * @param attribute the attribute to verify.
481       *
482       * @exception IllegalArgumentException if the categories are not equal
483       * @exception NullPointerException if category is null
484       */
485      public static void verifyCategoryForValue(Class<?> category,
486                                                Attribute attribute)
487      {
488        if (category == null || attribute == null)
489          throw new NullPointerException("category or attribute may not be null");
490    
491        if (!category.equals(attribute.getCategory()))
492          throw new IllegalArgumentException
493            ("category of attribute not equal to category");
494      }
495    }