src/java.desktop/share/classes/javax/print/attribute/AttributeSet.java

/*
 * Copyright (c) 2000, 2017, 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;

/**
 * Interface {@code AttributeSet} specifies the interface for a set of printing
 * attributes. A printing attribute is an object whose class implements
 * interface {@link Attribute Attribute}.
 * <p>
 * An attribute set contains a group of <i>attribute values,</i> where duplicate
 * values are not allowed in the set. Furthermore, each value in an attribute
 * set is a member of some <i>category,</i> and at most one value in any
 * particular category is allowed in the set. For an attribute set, the values
 * are {@link Attribute Attribute} objects, and the categories are
 * {@link Class Class} objects. An attribute's category is the class (or
 * interface) at the root of the class hierarchy for that kind of attribute.
 * Note that an attribute object's category may be a superclass of the attribute
 * object's class rather than the attribute object's class itself. An attribute
 * object's category is determined by calling the
 * {@link Attribute#getCategory() getCategory()} method defined in interface
 * {@link Attribute Attribute}.
 * <p>
 * The interfaces of an {@code AttributeSet} resemble those of the Java
 * Collections API's {@code java.util.Map} interface, but is more restrictive in
 * the types it will accept, and combines keys and values into an
 * {@code Attribute}.
 * <p>
 * Attribute sets are used in several places in the Print Service API. In each
 * context, only certain kinds of attributes are allowed to appear in the
 * attribute set, as determined by the tagging interfaces which the attribute
 * class implements -- {@link DocAttribute DocAttribute},
 * {@link PrintRequestAttribute PrintRequestAttribute},
 * {@link PrintJobAttribute PrintJobAttribute}, and
 * {@link PrintServiceAttribute PrintServiceAttribute}.
 * There are four specializations of an attribute set that are restricted to
 * contain just one of the four kinds of attribute --
 * {@link DocAttributeSet DocAttributeSet},
 * {@link PrintRequestAttributeSet PrintRequestAttributeSet},
 * {@link PrintJobAttributeSet PrintJobAttributeSet}, and
 * {@link PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note
 * that many attribute classes implement more than one tagging interface and so
 * may appear in more than one context.
 * <ul>
 *   <li>A {@link DocAttributeSet DocAttributeSet}, containing
 *   {@link DocAttribute DocAttribute}s, specifies the characteristics of an
 *   individual doc and the print job settings to be applied to an individual
 *   doc.
 *   <li>A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing
 *   {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the
 *   settings to be applied to a whole print job and to all the docs in the
 *   print job.
 *   <li>A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing
 *   {@link PrintJobAttribute PrintJobAttribute}s, reports the status of a print
 *   job.
 *   <li>A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing
 *   {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of
 *   a Print Service instance.
 * </ul>
 * In some contexts, the client is only allowed to examine an attribute set's
 * contents but not change them (the set is read-only). In other places, the
 * client is allowed both to examine and to change an attribute set's contents
 * (the set is read-write). For a read-only attribute set, calling a mutating
 * operation throws an {@code UnmodifiableSetException}.
 * <p>
 * The Print Service API provides one implementation of interface
 * {@code AttributeSet}, class {@link HashAttributeSet HashAttributeSet}. A
 * client can use class {@link HashAttributeSet HashAttributeSet} or provide its
 * own implementation of interface {@code AttributeSet}. The Print Service API
 * also provides implementations of interface {@code AttributeSet}'s
 * subinterfaces -- classes
 * {@link HashDocAttributeSet HashDocAttributeSet},
 * {@link HashPrintRequestAttributeSet HashPrintRequestAttributeSet},
 * {@link HashPrintJobAttributeSet HashPrintJobAttributeSet}, and
 * {@link HashPrintServiceAttributeSet HashPrintServiceAttributeSet}.
 *
 * @author Alan Kaminsky
 */
public interface AttributeSet {

    /**
     * Returns the attribute value which this attribute set contains in the
     * given attribute category. Returns {@code null} if this attribute set does
     * not contain any attribute value in the given attribute category.
     *
     * @param  category attribute category whose associated attribute value is
     *         to be returned. It must be a {@link Class Class} that implements
     *         interface {@link Attribute Attribute}.
     * @return the attribute value in the given attribute category contained in
     *         this attribute set, or {@code null} if this attribute set does
     *         not contain any attribute value in the given attribute category
     * @throws NullPointerException if the {@code category} is {@code null}
     * @throws ClassCastException if the {@code category} is not a
     *         {@link Class Class} that implements interface
     *         {@link Attribute Attribute}
     */
    public Attribute get(Class<?> category);

    /**
     * Adds the specified attribute to this attribute set if it is not already
     * present, first removing any existing value in the same attribute category
     * as the specified attribute value.
     *
     * @param  attribute attribute value to be added to this attribute set
     * @return {@code true} if this attribute set changed as a result of the
     *         call, i.e., the given attribute value was not already a member of
     *         this attribute set
     * @throws NullPointerException if the {@code attribute} is {@code null}
     * @throws UnmodifiableSetException if this attribute set does not support
     *         the {@code add()} operation
     */
    public boolean add(Attribute attribute);

    /**
     * Removes any attribute for this category from this attribute set if
     * present. If {@code category} is {@code null}, then {@code remove()} does
     * nothing and returns {@code false}.
     *
     * @param  category attribute category to be removed from this attribute set
     * @return {@code true} if this attribute set changed as a result of the
     *         call, i.e., the given attribute value had been a member of this
     *         attribute set
     * @throws UnmodifiableSetException if this attribute set does not support
     *         the {@code remove()} operation
     */
    public boolean remove(Class<?> category);

    /**
     * Removes the specified attribute from this attribute set if present. If
     * {@code attribute} is {@code null}, then {@code remove()} does nothing and
     * returns {@code false}.
     *
     * @param  attribute attribute value to be removed from this attribute set
     * @return {@code true} if this attribute set changed as a result of the
     *         call, i.e., the given attribute value had been a member of this
     *         attribute set
     * @throws UnmodifiableSetException if this attribute set does not support
     *         the {@code remove()} operation
     */
    public boolean remove(Attribute attribute);

    /**
     * Returns {@code true} if this attribute set contains an attribute for the
     * specified category.
     *
     * @param  category whose presence in this attribute set is to be tested
     * @return {@code true} if this attribute set contains an attribute value
     *         for the specified category
     */
    public boolean containsKey(Class<?> category);

    /**
     * Returns {@code true} if this attribute set contains the given attribute
     * value.
     *
     * @param  attribute attribute value whose presence in this attribute set is
     *         to be tested
     * @return {@code true} if this attribute set contains the given attribute
     *         value
     */
    public boolean containsValue(Attribute attribute);

    /**
     * Adds all of the elements in the specified set to this attribute. The
     * outcome is the same as if the = {@link #add(Attribute) add(Attribute)}
     * operation had been applied to this attribute set successively with each
     * element from the specified set. The behavior of the
     * {@code addAll(AttributeSet)} operation is unspecified if the specified
     * set is modified while the operation is in progress.
     * <p>
     * If the {@code addAll(AttributeSet)} operation throws an exception, the
     * effect on this attribute set's state is implementation dependent;
     * elements from the specified set before the point of the exception may or
     * may not have been added to this attribute set.
     *
     * @param  attributes whose elements are to be added to this attribute set
     * @return {@code true} if this attribute set changed as a result of the
     *         call
     * @throws UnmodifiableSetException if this attribute set does not support
     *         the {@code addAll(AttributeSet)} method
     * @throws NullPointerException if some element in the specified set is
     *         {@code null}
     * @see #add(Attribute)
     */
    public boolean addAll(AttributeSet attributes);

    /**
     * Returns the number of attributes in this attribute set. If this attribute
     * set contains more than {@code Integer.MAX_VALUE} elements, returns
     * {@code Integer.MAX_VALUE}.
     *
     * @return the number of attributes in this attribute set
     */
    public int size();

    /**
     * Returns an array of the attributes contained in this set.
     *
     * @return the {@code Attributes} contained in this set as an array, zero
     *         length if the {@code AttributeSet} is empty
     */
    public Attribute[] toArray();

    /**
     * Removes all attributes from this attribute set.
     *
     * @throws UnmodifiableSetException if this attribute set does not support
     *         the {@code clear()} operation
     */
    public void clear();

    /**
     * Returns {@code true} if this attribute set contains no attributes.
     *
     * @return {@code true} if this attribute set contains no attributes
     */
    public boolean isEmpty();

    /**
     * Compares the specified object with this attribute set for equality.
     * Returns {@code true} if the given object is also an attribute set and the
     * two attribute sets contain the same attribute category-attribute value
     * mappings. This ensures that the {@code equals()} method works properly
     * across different implementations of the {@code AttributeSet} interface.
     *
     * @param  object to be compared for equality with this attribute set
     * @return {@code true} if the specified object is equal to this attribute
     *         set
     */
    public boolean equals(Object object);

    /**
     * Returns the hash code value for this attribute set. The hash code of an
     * attribute set is defined to be the sum of the hash codes of each entry in
     * the {@code AttributeSet}. This ensures that {@code t1.equals(t2)} implies
     * that {@code t1.hashCode()==t2.hashCode()} for any two attribute sets
     * {@code t1} and {@code t2}, as required by the general contract of
     * {@link Object#hashCode() Object.hashCode()}.
     *
     * @return the hash code value for this attribute set
     */
    public int hashCode();
}