1 /*
   2  * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.print.attribute;
  27 
  28 /**
  29  * Interface AttributeSet specifies the interface for a set of printing
  30  * attributes. A printing attribute is an object whose class implements
  31  * interface {@link Attribute Attribute}.
  32  * <P>
  33  * An attribute set contains a group of <I>attribute values,</I>
  34  * where duplicate values are not allowed in the set.
  35  * Furthermore, each value in an attribute set is
  36  * a member of some <I>category,</I> and at most one value in any particular
  37  * category is allowed in the set. For an attribute set, the values are {@link
  38  * Attribute Attribute} objects, and the categories are {@link java.lang.Class
  39  * Class} objects. An attribute's category is the class (or interface) at the
  40  * root of the class hierarchy for that kind of attribute. Note that an
  41  * attribute object's category may be a superclass of the attribute object's
  42  * class rather than the attribute object's class itself. An attribute
  43  * object's
  44  * category is determined by calling the {@link Attribute#getCategory()
  45  * getCategory()} method defined in interface {@link Attribute
  46  * Attribute}.
  47  * <P>
  48  * The interfaces of an AttributeSet resemble those of the Java Collections
  49  * API's java.util.Map interface, but is more restrictive in the types
  50  * it will accept, and combines keys and values into an Attribute.
  51  * <P>
  52  * Attribute sets are used in several places in the Print Service API. In
  53  * each context, only certain kinds of attributes are allowed to appear in the
  54  * attribute set, as determined by the tagging interfaces which the attribute
  55  * class implements -- {@link DocAttribute DocAttribute}, {@link
  56  * PrintRequestAttribute PrintRequestAttribute}, {@link PrintJobAttribute
  57  * PrintJobAttribute}, and {@link PrintServiceAttribute
  58  * PrintServiceAttribute}.
  59  * There are four specializations of an attribute set that are restricted to
  60  * contain just one of the four kinds of attribute -- {@link DocAttributeSet
  61  * DocAttributeSet}, {@link PrintRequestAttributeSet
  62  * PrintRequestAttributeSet},
  63  * {@link PrintJobAttributeSet PrintJobAttributeSet}, and {@link
  64  * PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note that
  65  * many attribute classes implement more than one tagging interface and so may
  66  * appear in more than one context.
  67  * <UL>
  68  * <LI>
  69  * A {@link DocAttributeSet DocAttributeSet}, containing {@link DocAttribute
  70  * DocAttribute}s, specifies the characteristics of an individual doc and the
  71  * print job settings to be applied to an individual doc.
  72  * <P>
  73  * <LI>
  74  * A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing
  75  * {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the
  76  * settings
  77  * to be applied to a whole print job and to all the docs in the print job.
  78  * <P>
  79  * <LI>
  80  * A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing {@link
  81  * PrintJobAttribute PrintJobAttribute}s, reports the status of a print job.
  82  * <P>
  83  * <LI>
  84  * A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing
  85  * {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of
  86  *  a Print Service instance.
  87  * </UL>
  88  * <P>
  89  * In some contexts, the client is only allowed to examine an attribute set's
  90  * contents but not change them (the set is read-only). In other places, the
  91  * client is allowed both to examine and to change an attribute set's contents
  92  * (the set is read-write). For a read-only attribute set, calling a mutating
  93  * operation throws an UnmodifiableSetException.
  94  * <P>
  95  * The Print Service API provides one implementation of interface
  96  * AttributeSet, class {@link HashAttributeSet HashAttributeSet}.
  97  * A client can use class {@link
  98  * HashAttributeSet HashAttributeSet} or provide its own implementation of
  99  * interface AttributeSet. The Print Service API also provides
 100  * implementations of interface AttributeSet's subinterfaces -- classes {@link
 101  * HashDocAttributeSet HashDocAttributeSet},
 102  * {@link HashPrintRequestAttributeSet
 103  * HashPrintRequestAttributeSet}, {@link HashPrintJobAttributeSet
 104  * HashPrintJobAttributeSet}, and {@link HashPrintServiceAttributeSet
 105  * HashPrintServiceAttributeSet}.
 106  * <P>
 107  *
 108  * @author  Alan Kaminsky
 109  */
 110 public interface AttributeSet {
 111 
 112 
 113     /**
 114      * Returns the attribute value which this attribute set contains in the
 115      * given attribute category. Returns <tt>null</tt> if this attribute set
 116      * does not contain any attribute value in the given attribute category.
 117      *
 118      * @param  category  Attribute category whose associated attribute value
 119      *                   is to be returned. It must be a
 120      *                   {@link java.lang.Class Class}
 121      *                   that implements interface {@link Attribute
 122      *                   Attribute}.
 123      *
 124      * @return  The attribute value in the given attribute category contained
 125      *          in this attribute set, or <tt>null</tt> if this attribute set
 126      *          does not contain any attribute value in the given attribute
 127      *          category.
 128      *
 129      * @throws  NullPointerException
 130      *     (unchecked exception) Thrown if the <CODE>category</CODE> is null.
 131      * @throws  ClassCastException
 132      *     (unchecked exception) Thrown if the <CODE>category</CODE> is not a
 133      *     {@link java.lang.Class Class} that implements interface {@link
 134      *     Attribute Attribute}.
 135      */
 136     public Attribute get(Class<?> category);
 137 
 138     /**
 139      * Adds the specified attribute to this attribute set if it is not
 140      * already present, first removing any existing value in the same
 141      * attribute category as the specified attribute value.
 142      *
 143      * @param  attribute  Attribute value to be added to this attribute set.
 144      *
 145      * @return  <tt>true</tt> if this attribute set changed as a result of the
 146      *          call, i.e., the given attribute value was not already a member
 147      *          of this attribute set.
 148      *
 149      * @throws  NullPointerException
 150      *     (unchecked exception) Thrown if the <CODE>attribute</CODE> is null.
 151      * @throws  UnmodifiableSetException
 152      *     (unchecked exception) Thrown if this attribute set does not support
 153      *     the <CODE>add()</CODE> operation.
 154      */
 155     public boolean add(Attribute attribute);
 156 
 157 
 158     /**
 159      * Removes any attribute for this category from this attribute set if
 160      * present. If <CODE>category</CODE> is null, then
 161      * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>.
 162      *
 163      * @param  category Attribute category to be removed from this
 164      *                  attribute set.
 165      *
 166      * @return  <tt>true</tt> if this attribute set changed as a result of the
 167      *         call, i.e., the given attribute value had been a member of this
 168      *          attribute set.
 169      *
 170      * @throws  UnmodifiableSetException
 171      *     (unchecked exception) Thrown if this attribute set does not support
 172      *     the <CODE>remove()</CODE> operation.
 173      */
 174     public boolean remove(Class<?> category);
 175 
 176     /**
 177      * Removes the specified attribute from this attribute set if
 178      * present. If <CODE>attribute</CODE> is null, then
 179      * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>.
 180      *
 181      * @param  attribute Attribute value to be removed from this attribute set.
 182      *
 183      * @return  <tt>true</tt> if this attribute set changed as a result of the
 184      *         call, i.e., the given attribute value had been a member of this
 185      *          attribute set.
 186      *
 187      * @throws  UnmodifiableSetException
 188      *     (unchecked exception) Thrown if this attribute set does not support
 189      *     the <CODE>remove()</CODE> operation.
 190      */
 191     public boolean remove(Attribute attribute);
 192 
 193     /**
 194      * Returns <tt>true</tt> if this attribute set contains an
 195      * attribute for the specified category.
 196      *
 197      * @param  category whose presence in this attribute set is
 198      *            to be tested.
 199      *
 200      * @return  <tt>true</tt> if this attribute set contains an attribute
 201      *         value for the specified category.
 202      */
 203     public boolean containsKey(Class<?> category);
 204 
 205     /**
 206      * Returns <tt>true</tt> if this attribute set contains the given
 207      * attribute value.
 208      *
 209      * @param  attribute  Attribute value whose presence in this
 210      * attribute set is to be tested.
 211      *
 212      * @return  <tt>true</tt> if this attribute set contains the given
 213      *      attribute  value.
 214      */
 215     public boolean containsValue(Attribute attribute);
 216 
 217     /**
 218      * Adds all of the elements in the specified set to this attribute.
 219      * The outcome is the same as if the =
 220      * {@link #add(Attribute) add(Attribute)}
 221      * operation had been applied to this attribute set successively with each
 222      * element from the specified set.
 223      * The behavior of the <CODE>addAll(AttributeSet)</CODE>
 224      * operation is unspecified if the specified set is modified while
 225      * the operation is in progress.
 226      * <P>
 227      * If the <CODE>addAll(AttributeSet)</CODE> operation throws an exception,
 228      * the effect on this attribute set's state is implementation dependent;
 229      * elements from the specified set before the point of the exception may
 230      * or may not have been added to this attribute set.
 231      *
 232      * @param  attributes  whose elements are to be added to this attribute
 233      *            set.
 234      *
 235      * @return  <tt>true</tt> if this attribute set changed as a result of the
 236      *          call.
 237      *
 238      * @throws  UnmodifiableSetException
 239      *     (Unchecked exception) Thrown if this attribute set does not support
 240      *     the <tt>addAll(AttributeSet)</tt> method.
 241      * @throws  NullPointerException
 242      *     (Unchecked exception) Thrown if some element in the specified
 243      *     set is null.
 244      *
 245      * @see #add(Attribute)
 246      */
 247     public boolean addAll(AttributeSet attributes);
 248 
 249     /**
 250      * Returns the number of attributes in this attribute set. If this
 251      * attribute set contains more than <tt>Integer.MAX_VALUE</tt> elements,
 252      * returns  <tt>Integer.MAX_VALUE</tt>.
 253      *
 254      * @return  The number of attributes in this attribute set.
 255      */
 256     public int size();
 257 
 258     /**
 259      * Returns an array of the attributes contained in this set.
 260      * @return the Attributes contained in this set as an array, zero length
 261      * if the AttributeSet is empty.
 262      */
 263     public Attribute[] toArray();
 264 
 265 
 266     /**
 267      * Removes all attributes from this attribute set.
 268      *
 269      * @throws  UnmodifiableSetException
 270      *   (unchecked exception) Thrown if this attribute set does not support
 271      *     the <CODE>clear()</CODE> operation.
 272      */
 273     public void clear();
 274 
 275     /**
 276      * Returns true if this attribute set contains no attributes.
 277      *
 278      * @return true if this attribute set contains no attributes.
 279      */
 280     public boolean isEmpty();
 281 
 282     /**
 283      * Compares the specified object with this attribute set for equality.
 284      * Returns <tt>true</tt> if the given object is also an attribute set and
 285      * the two attribute sets contain the same attribute category-attribute
 286      * value mappings. This ensures that the
 287      * <tt>equals()</tt> method works properly across different
 288      * implementations of the AttributeSet interface.
 289      *
 290      * @param  object to be compared for equality with this attribute set.
 291      *
 292      * @return  <tt>true</tt> if the specified object is equal to this
 293      *       attribute   set.
 294      */
 295     public boolean equals(Object object);
 296 
 297     /**
 298      * Returns the hash code value for this attribute set. The hash code of an
 299      * attribute set is defined to be the sum of the hash codes of each entry
 300      * in the AttributeSet.
 301      * This ensures that <tt>t1.equals(t2)</tt> implies that
 302      * <tt>t1.hashCode()==t2.hashCode()</tt> for any two attribute sets
 303      * <tt>t1</tt> and <tt>t2</tt>, as required by the general contract of
 304      * {@link java.lang.Object#hashCode() Object.hashCode()}.
 305      *
 306      * @return  The hash code value for this attribute set.
 307      */
 308     public int hashCode();
 309 
 310 }