/*
* Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.print.attribute;
import java.io.Serializable;
/**
* Class AttributeSetUtilities provides static methods for manipulating
* AttributeSets.
* <ul>
* <li>Methods for creating unmodifiable and synchronized views of attribute
* sets.
* <li>operations useful for building
* implementations of interface {@link AttributeSet AttributeSet}
* </ul>
* <P>
* An <B>unmodifiable view</B> <I>U</I> of an AttributeSet <I>S</I> provides a
* client with "read-only" access to <I>S</I>. Query operations on <I>U</I>
* "read through" to <I>S</I>; thus, changes in <I>S</I> are reflected in
* <I>U</I>. However, any attempt to modify <I>U</I>,
* results in an UnmodifiableSetException.
* The unmodifiable view object <I>U</I> will be serializable if the
* attribute set object <I>S</I> is serializable.
* <P>
* A <B>synchronized view</B> <I>V</I> of an attribute set <I>S</I> provides a
* client with synchronized (multiple thread safe) access to <I>S</I>. Each
* operation of <I>V</I> is synchronized using <I>V</I> itself as the lock
* object and then merely invokes the corresponding operation of <I>S</I>. In
* order to guarantee mutually exclusive access, it is critical that all
* access to <I>S</I> is accomplished through <I>V</I>. The synchronized view
* object <I>V</I> will be serializable if the attribute set object <I>S</I>
* is serializable.
* <P>
* As mentioned in the package description of javax.print, a null reference
* parameter to methods is
* incorrect unless explicitly documented on the method as having a meaningful
* interpretation. Usage to the contrary is incorrect coding and may result in
* a run time exception either immediately
* or at some later time. IllegalArgumentException and NullPointerException
* are examples of typical and acceptable run time exceptions for such cases.
*
* @author Alan Kaminsky
*/
public final class AttributeSetUtilities {
/* Suppress default constructor, ensuring non-instantiability.
*/
private AttributeSetUtilities() {
}
/**
* @serial include
*/
private static class UnmodifiableAttributeSet
implements AttributeSet, Serializable {
private AttributeSet attrset;
/* Unmodifiable view of the underlying attribute set.
*/
public UnmodifiableAttributeSet(AttributeSet attributeSet) {
attrset = attributeSet;
}
public Attribute get(Class<?> key) {
return attrset.get(key);
}
public boolean add(Attribute attribute) {
throw new UnmodifiableSetException();
}
public synchronized boolean remove(Class<?> category) {
throw new UnmodifiableSetException();
}
public boolean remove(Attribute attribute) {
throw new UnmodifiableSetException();
}
public boolean containsKey(Class<?> category) {
return attrset.containsKey(category);
}
public boolean containsValue(Attribute attribute) {
return attrset.containsValue(attribute);
}
public boolean addAll(AttributeSet attributes) {
throw new UnmodifiableSetException();
}
public int size() {
return attrset.size();
}
public Attribute[] toArray() {
return attrset.toArray();
}
public void clear() {
throw new UnmodifiableSetException();
}
public boolean isEmpty() {
return attrset.isEmpty();
}
public boolean equals(Object o) {
return attrset.equals (o);
}
public int hashCode() {
return attrset.hashCode();
}
}
/**
* @serial include
*/
private static class UnmodifiableDocAttributeSet
extends UnmodifiableAttributeSet
implements DocAttributeSet, Serializable {
public UnmodifiableDocAttributeSet(DocAttributeSet attributeSet) {
super (attributeSet);
}
}
/**
* @serial include
*/
private static class UnmodifiablePrintRequestAttributeSet
extends UnmodifiableAttributeSet
implements PrintRequestAttributeSet, Serializable
{
public UnmodifiablePrintRequestAttributeSet
(PrintRequestAttributeSet attributeSet) {
super (attributeSet);
}
}
/**
* @serial include
*/
private static class UnmodifiablePrintJobAttributeSet
extends UnmodifiableAttributeSet
implements PrintJobAttributeSet, Serializable
{
public UnmodifiablePrintJobAttributeSet
(PrintJobAttributeSet attributeSet) {
super (attributeSet);
}
}
/**
* @serial include
*/
private static class UnmodifiablePrintServiceAttributeSet
extends UnmodifiableAttributeSet
implements PrintServiceAttributeSet, Serializable
{
public UnmodifiablePrintServiceAttributeSet
(PrintServiceAttributeSet attributeSet) {
super (attributeSet);
}
}
/**
* Creates an unmodifiable view of the given attribute set.
*
* @param attributeSet Underlying attribute set.
*
* @return Unmodifiable view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null. Null is never a
*/
public static AttributeSet unmodifiableView(AttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new UnmodifiableAttributeSet(attributeSet);
}
/**
* Creates an unmodifiable view of the given doc attribute set.
*
* @param attributeSet Underlying doc attribute set.
*
* @return Unmodifiable view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static DocAttributeSet unmodifiableView
(DocAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new UnmodifiableDocAttributeSet(attributeSet);
}
/**
* Creates an unmodifiable view of the given print request attribute set.
*
* @param attributeSet Underlying print request attribute set.
*
* @return Unmodifiable view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static PrintRequestAttributeSet
unmodifiableView(PrintRequestAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new UnmodifiablePrintRequestAttributeSet(attributeSet);
}
/**
* Creates an unmodifiable view of the given print job attribute set.
*
* @param attributeSet Underlying print job attribute set.
*
* @return Unmodifiable view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static PrintJobAttributeSet
unmodifiableView(PrintJobAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new UnmodifiablePrintJobAttributeSet(attributeSet);
}
/**
* Creates an unmodifiable view of the given print service attribute set.
*
* @param attributeSet Underlying print service attribute set.
*
* @return Unmodifiable view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static PrintServiceAttributeSet
unmodifiableView(PrintServiceAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new UnmodifiablePrintServiceAttributeSet (attributeSet);
}
/**
* @serial include
*/
private static class SynchronizedAttributeSet
implements AttributeSet, Serializable {
private AttributeSet attrset;
public SynchronizedAttributeSet(AttributeSet attributeSet) {
attrset = attributeSet;
}
public synchronized Attribute get(Class<?> category) {
return attrset.get(category);
}
public synchronized boolean add(Attribute attribute) {
return attrset.add(attribute);
}
public synchronized boolean remove(Class<?> category) {
return attrset.remove(category);
}
public synchronized boolean remove(Attribute attribute) {
return attrset.remove(attribute);
}
public synchronized boolean containsKey(Class<?> category) {
return attrset.containsKey(category);
}
public synchronized boolean containsValue(Attribute attribute) {
return attrset.containsValue(attribute);
}
public synchronized boolean addAll(AttributeSet attributes) {
return attrset.addAll(attributes);
}
public synchronized int size() {
return attrset.size();
}
public synchronized Attribute[] toArray() {
return attrset.toArray();
}
public synchronized void clear() {
attrset.clear();
}
public synchronized boolean isEmpty() {
return attrset.isEmpty();
}
public synchronized boolean equals(Object o) {
return attrset.equals (o);
}
public synchronized int hashCode() {
return attrset.hashCode();
}
}
/**
* @serial include
*/
private static class SynchronizedDocAttributeSet
extends SynchronizedAttributeSet
implements DocAttributeSet, Serializable {
public SynchronizedDocAttributeSet(DocAttributeSet attributeSet) {
super(attributeSet);
}
}
/**
* @serial include
*/
private static class SynchronizedPrintRequestAttributeSet
extends SynchronizedAttributeSet
implements PrintRequestAttributeSet, Serializable {
public SynchronizedPrintRequestAttributeSet
(PrintRequestAttributeSet attributeSet) {
super(attributeSet);
}
}
/**
* @serial include
*/
private static class SynchronizedPrintJobAttributeSet
extends SynchronizedAttributeSet
implements PrintJobAttributeSet, Serializable {
public SynchronizedPrintJobAttributeSet
(PrintJobAttributeSet attributeSet) {
super(attributeSet);
}
}
/**
* @serial include
*/
private static class SynchronizedPrintServiceAttributeSet
extends SynchronizedAttributeSet
implements PrintServiceAttributeSet, Serializable {
public SynchronizedPrintServiceAttributeSet
(PrintServiceAttributeSet attributeSet) {
super(attributeSet);
}
}
/**
* Creates a synchronized view of the given attribute set.
*
* @param attributeSet Underlying attribute set.
*
* @return Synchronized view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static AttributeSet synchronizedView
(AttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new SynchronizedAttributeSet(attributeSet);
}
/**
* Creates a synchronized view of the given doc attribute set.
*
* @param attributeSet Underlying doc attribute set.
*
* @return Synchronized view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static DocAttributeSet
synchronizedView(DocAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new SynchronizedDocAttributeSet(attributeSet);
}
/**
* Creates a synchronized view of the given print request attribute set.
*
* @param attributeSet Underlying print request attribute set.
*
* @return Synchronized view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static PrintRequestAttributeSet
synchronizedView(PrintRequestAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new SynchronizedPrintRequestAttributeSet(attributeSet);
}
/**
* Creates a synchronized view of the given print job attribute set.
*
* @param attributeSet Underlying print job attribute set.
*
* @return Synchronized view of <CODE>attributeSet</CODE>.
*
* @exception NullPointerException
* Thrown if <CODE>attributeSet</CODE> is null.
*/
public static PrintJobAttributeSet
synchronizedView(PrintJobAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new SynchronizedPrintJobAttributeSet(attributeSet);
}
/**
* Creates a synchronized view of the given print service attribute set.
*
* @param attributeSet Underlying print service attribute set.
*
* @return Synchronized view of <CODE>attributeSet</CODE>.
*/
public static PrintServiceAttributeSet
synchronizedView(PrintServiceAttributeSet attributeSet) {
if (attributeSet == null) {
throw new NullPointerException();
}
return new SynchronizedPrintServiceAttributeSet(attributeSet);
}
/**
* Verify that the given object is a {@link java.lang.Class Class} that
* implements the given interface, which is assumed to be interface {@link
* Attribute Attribute} or a subinterface thereof.
*
* @param object Object to test.
* @param interfaceName Interface the object must implement.
*
* @return If <CODE>object</CODE> is a {@link java.lang.Class Class}
* that implements <CODE>interfaceName</CODE>,
* <CODE>object</CODE> is returned downcast to type {@link
* java.lang.Class Class}; otherwise an exception is thrown.
*
* @exception NullPointerException
* (unchecked exception) Thrown if <CODE>object</CODE> is null.
* @exception ClassCastException
* (unchecked exception) Thrown if <CODE>object</CODE> is not a
* {@link java.lang.Class Class} that implements
* <CODE>interfaceName</CODE>.
*/
public static Class<?>
verifyAttributeCategory(Object object, Class<?> interfaceName) {
Class result = (Class) object;
if (interfaceName.isAssignableFrom (result)) {
return result;
}
else {
throw new ClassCastException();
}
}
/**
* Verify that the given object is an instance of the given interface, which
* is assumed to be interface {@link Attribute Attribute} or a subinterface
* thereof.
*
* @param object Object to test.
* @param interfaceName Interface of which the object must be an instance.
*
* @return If <CODE>object</CODE> is an instance of
* <CODE>interfaceName</CODE>, <CODE>object</CODE> is returned
* downcast to type {@link Attribute Attribute}; otherwise an
* exception is thrown.
*
* @exception NullPointerException
* (unchecked exception) Thrown if <CODE>object</CODE> is null.
* @exception ClassCastException
* (unchecked exception) Thrown if <CODE>object</CODE> is not an
* instance of <CODE>interfaceName</CODE>.
*/
public static Attribute
verifyAttributeValue(Object object, Class<?> interfaceName) {
if (object == null) {
throw new NullPointerException();
}
else if (interfaceName.isInstance (object)) {
return (Attribute) object;
} else {
throw new ClassCastException();
}
}
/**
* Verify that the given attribute category object is equal to the
* category of the given attribute value object. If so, this method
* returns doing nothing. If not, this method throws an exception.
*
* @param category Attribute category to test.
* @param attribute Attribute value to test.
*
* @exception NullPointerException
* (unchecked exception) Thrown if the <CODE>category</CODE> is
* null or if the <CODE>attribute</CODE> is null.
* @exception IllegalArgumentException
* (unchecked exception) Thrown if the <CODE>category</CODE> is not
* equal to the category of the <CODE>attribute</CODE>.
*/
public static void
verifyCategoryForValue(Class<?> category, Attribute attribute) {
if (!category.equals (attribute.getCategory())) {
throw new IllegalArgumentException();
}
}
}