AttributeSetUtilities.java revision 0
0N/A * Copyright 2000-2004 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * Class AttributeSetUtilities provides static methods for manipulating 0N/A * <li>Methods for creating unmodifiable and synchronized views of attribute 0N/A * <li>operations useful for building 0N/A * implementations of interface {@link AttributeSet AttributeSet} 0N/A * An <B>unmodifiable view</B> <I>U</I> of an AttributeSet <I>S</I> provides a 0N/A * client with "read-only" access to <I>S</I>. Query operations on <I>U</I> 0N/A * "read through" to <I>S</I>; thus, changes in <I>S</I> are reflected in 0N/A * <I>U</I>. However, any attempt to modify <I>U</I>, 0N/A * results in an UnmodifiableSetException. 0N/A * The unmodifiable view object <I>U</I> will be serializable if the 0N/A * attribute set object <I>S</I> is serializable. 0N/A * A <B>synchronized view</B> <I>V</I> of an attribute set <I>S</I> provides a 0N/A * client with synchronized (multiple thread safe) access to <I>S</I>. Each 0N/A * operation of <I>V</I> is synchronized using <I>V</I> itself as the lock 0N/A * object and then merely invokes the corresponding operation of <I>S</I>. In 0N/A * order to guarantee mutually exclusive access, it is critical that all 0N/A * access to <I>S</I> is accomplished through <I>V</I>. The synchronized view 0N/A * object <I>V</I> will be serializable if the attribute set object <I>S</I> 0N/A * As mentioned in the package description of javax.print, a null reference 0N/A * parameter to methods is 0N/A * incorrect unless explicitly documented on the method as having a meaningful 0N/A * interpretation. Usage to the contrary is incorrect coding and may result in 0N/A * a run time exception either immediately 0N/A * or at some later time. IllegalArgumentException and NullPointerException 0N/A * are examples of typical and acceptable run time exceptions for such cases. 0N/A * @author Alan Kaminsky 0N/A /* Suppress default constructor, ensuring non-instantiability. 0N/A /* Unmodifiable view of the underlying attribute set. 0N/A * Creates an unmodifiable view of the given attribute set. 0N/A * @param attributeSet Underlying attribute set. 0N/A * @return Unmodifiable view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. Null is never a 0N/A * Creates an unmodifiable view of the given doc attribute set. 0N/A * @param attributeSet Underlying doc attribute set. 0N/A * @return Unmodifiable view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates an unmodifiable view of the given print request attribute set. 0N/A * @param attributeSet Underlying print request attribute set. 0N/A * @return Unmodifiable view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates an unmodifiable view of the given print job attribute set. 0N/A * @param attributeSet Underlying print job attribute set. 0N/A * @return Unmodifiable view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates an unmodifiable view of the given print service attribute set. 0N/A * @param attributeSet Underlying print service attribute set. 0N/A * @return Unmodifiable view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates a synchronized view of the given attribute set. 0N/A * @param attributeSet Underlying attribute set. 0N/A * @return Synchronized view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates a synchronized view of the given doc attribute set. 0N/A * @param attributeSet Underlying doc attribute set. 0N/A * @return Synchronized view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates a synchronized view of the given print request attribute set. 0N/A * @param attributeSet Underlying print request attribute set. 0N/A * @return Synchronized view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates a synchronized view of the given print job attribute set. 0N/A * @param attributeSet Underlying print job attribute set. 0N/A * @return Synchronized view of <CODE>attributeSet</CODE>. 0N/A * @exception NullPointerException 0N/A * Thrown if <CODE>attributeSet</CODE> is null. 0N/A * Creates a synchronized view of the given print service attribute set. 0N/A * @param attributeSet Underlying print service attribute set. 0N/A * @return Synchronized view of <CODE>attributeSet</CODE>. 0N/A * Verify that the given object is a {@link java.lang.Class Class} that 0N/A * implements the given interface, which is assumed to be interface {@link 0N/A * Attribute Attribute} or a subinterface thereof. 0N/A * @param object Object to test. 0N/A * @param interfaceName Interface the object must implement. 0N/A * @return If <CODE>object</CODE> is a {@link java.lang.Class Class} 0N/A * that implements <CODE>interfaceName</CODE>, 0N/A * <CODE>object</CODE> is returned downcast to type {@link 0N/A * java.lang.Class Class}; otherwise an exception is thrown. 0N/A * @exception NullPointerException 0N/A * (unchecked exception) Thrown if <CODE>object</CODE> is null. 0N/A * @exception ClassCastException 0N/A * (unchecked exception) Thrown if <CODE>object</CODE> is not a 0N/A * {@link java.lang.Class Class} that implements 0N/A * <CODE>interfaceName</CODE>. 0N/A * Verify that the given object is an instance of the given interface, which 0N/A * is assumed to be interface {@link Attribute Attribute} or a subinterface 0N/A * @param object Object to test. 0N/A * @param interfaceName Interface of which the object must be an instance. 0N/A * @return If <CODE>object</CODE> is an instance of 0N/A * <CODE>interfaceName</CODE>, <CODE>object</CODE> is returned 0N/A * downcast to type {@link Attribute Attribute}; otherwise an 0N/A * exception is thrown. 0N/A * @exception NullPointerException 0N/A * (unchecked exception) Thrown if <CODE>object</CODE> is null. 0N/A * @exception ClassCastException 0N/A * (unchecked exception) Thrown if <CODE>object</CODE> is not an 0N/A * instance of <CODE>interfaceName</CODE>. 0N/A * Verify that the given attribute category object is equal to the 0N/A * category of the given attribute value object. If so, this method 0N/A * returns doing nothing. If not, this method throws an exception. 0N/A * @param category Attribute category to test. 0N/A * @param attribute Attribute value to test. 0N/A * @exception NullPointerException 0N/A * (unchecked exception) Thrown if the <CODE>category</CODE> is 0N/A * null or if the <CODE>attribute</CODE> is null. 0N/A * @exception IllegalArgumentException 0N/A * (unchecked exception) Thrown if the <CODE>category</CODE> is not 0N/A * equal to the category of the <CODE>attribute</CODE>.