1. /*

  2.  * @(#)AttributeSet.java	1.7 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.print.attribute;

  9. 

  10. /**

  11.  * Interface AttributeSet specifies the interface for a set of printing 

  12.  * attributes. A printing attribute is an object whose class implements 

  13.  * interface {@link Attribute Attribute}. 

  14.  * <P>

  15.  * An attribute set contains a group of <I>attribute values,</I>

  16.  * where duplicate values are not allowed in the set.

  17.  * Furthermore, each value in an attribute set is  

  18.  * a member of some <I>category,</I> and at most one value in any particular 

  19.  * category is allowed in the set. For an attribute set, the values are {@link 

  20.  * Attribute Attribute} objects, and the categories are {@link java.lang.Class 

  21.  * Class} objects. An attribute's category is the class (or interface) at the 

  22.  * root of the class hierarchy for that kind of attribute. Note that an 

  23.  * attribute object's category may be a superclass of the attribute object's 

  24.  * class rather than the attribute object's class itself. An attribute

  25.  * object's 

  26.  * category is determined by calling the {@link Attribute#getCategory() 

  27.  * <CODE>getCategory()</CODE>} method defined in interface {@link Attribute 

  28.  * Attribute}. 

  29.  * <P>

  30.  * The interfaces of an AttributeSet resemble those of the Java Collections

  31.  * API's java.util.Map interface, but is more restrictive in the types

  32.  * it will accept, and combines keys and values into an Attribute.

  33.  * <P>

  34.  * Attribute sets are used in several places in the Print Service API. In 

  35.  * each context, only certain kinds of attributes are allowed to appear in the 

  36.  * attribute set, as determined by the tagging interfaces which the attribute 

  37.  * class implements -- {@link DocAttribute DocAttribute}, {@link 

  38.  * PrintRequestAttribute PrintRequestAttribute}, {@link PrintJobAttribute 

  39.  * PrintJobAttribute}, and {@link PrintServiceAttribute

  40.  * PrintServiceAttribute}. 

  41.  * There are four specializations of an attribute set that are restricted to 

  42.  * contain just one of the four kinds of attribute -- {@link DocAttributeSet 

  43.  * DocAttributeSet}, {@link PrintRequestAttributeSet

  44.  * PrintRequestAttributeSet}, 

  45.  * {@link PrintJobAttributeSet PrintJobAttributeSet}, and {@link 

  46.  * PrintServiceAttributeSet PrintServiceAttributeSet}, respectively. Note that 

  47.  * many attribute classes implement more than one tagging interface and so may 

  48.  * appear in more than one context. 

  49.  * <UL>

  50.  * <LI>

  51.  * A {@link DocAttributeSet DocAttributeSet}, containing {@link DocAttribute 

  52.  * DocAttribute}s, specifies the characteristics of an individual doc and the 

  53.  * print job settings to be applied to an individual doc. 

  54.  * <P>

  55.  * <LI>

  56.  * A {@link PrintRequestAttributeSet PrintRequestAttributeSet}, containing 

  57.  * {@link PrintRequestAttribute PrintRequestAttribute}s, specifies the

  58.  * settings 

  59.  * to be applied to a whole print job and to all the docs in the print job. 

  60.  * <P>

  61.  * <LI>

  62.  * A {@link PrintJobAttributeSet PrintJobAttributeSet}, containing {@link 

  63.  * PrintJobAttribute PrintJobAttribute}s, reports the status of a print job. 

  64.  * <P>

  65.  * <LI>

  66.  * A {@link PrintServiceAttributeSet PrintServiceAttributeSet}, containing 

  67.  * {@link PrintServiceAttribute PrintServiceAttribute}s, reports the status of

  68.  *  a Print Service instance. 

  69.  * </UL>

  70.  * <P>

  71.  * In some contexts, the client is only allowed to examine an attribute set's 

  72.  * contents but not change them (the set is read-only). In other places, the 

  73.  * client is allowed both to examine and to change an attribute set's contents 

  74.  * (the set is read-write). For a read-only attribute set, calling a mutating 

  75.  * operation throws an UnmodifiableSetException. 

  76.  * <P>

  77.  * The Print Service API provides one implementation of interface 

  78.  * AttributeSet, class {@link HashAttributeSet HashAttributeSet}.

  79.  * A client can use class {@link 

  80.  * HashAttributeSet HashAttributeSet} or provide its own implementation of 

  81.  * interface AttributeSet. The Print Service API also provides 

  82.  * implementations of interface AttributeSet's subinterfaces -- classes {@link 

  83.  * HashDocAttributeSet HashDocAttributeSet},

  84.  * {@link HashPrintRequestAttributeSet 

  85.  * HashPrintRequestAttributeSet}, {@link HashPrintJobAttributeSet 

  86.  * HashPrintJobAttributeSet}, and {@link HashPrintServiceAttributeSet 

  87.  * HashPrintServiceAttributeSet}. 

  88.  * <P>

  89.  *

  90.  * @author  Alan Kaminsky

  91.  */

  92. public interface AttributeSet {

  93. 

  94. 

  95.     /**

  96.      * Returns the attribute value which this attribute set contains in the 

  97.      * given attribute category. Returns <tt>null</tt> if this attribute set 

  98.      * does not contain any attribute value in the given attribute category.

  99.      *

  100.      * @param  category  Attribute category whose associated attribute value

  101.      *                   is to be returned. It must be a

  102.      *                   {@link java.lang.Class Class}

  103.      *                   that implements interface {@link Attribute 

  104.      *                   Attribute}. 

  105.      *

  106.      * @return  The attribute value in the given attribute category contained

  107.      *          in this attribute set, or <tt>null</tt> if this attribute set

  108.      *          does not contain any attribute value in the given attribute

  109.      *          category. 

  110.      * 

  111.      * @throws  NullPointerException

  112.      *     (unchecked exception) Thrown if the <CODE>category</CODE> is null.

  113.      * @throws  ClassCastException

  114.      *     (unchecked exception) Thrown if the <CODE>category</CODE> is not a 

  115.      *     {@link java.lang.Class Class} that implements interface {@link 

  116.      *     Attribute Attribute}. 

  117.      */

  118.     public Attribute get(Class category);

  119. 

  120.     /**

  121.      * Adds the specified attribute to this attribute set if it is not 

  122.      * already present, first removing any existing value in the same

  123.      * attribute category as the specified attribute value. 

  124.      *

  125.      * @param  attribute  Attribute value to be added to this attribute set.

  126.      *

  127.      * @return  <tt>true</tt> if this attribute set changed as a result of the

  128.      *          call, i.e., the given attribute value was not already a member 

  129.      *          of this attribute set. 

  130.      * 

  131.      * @throws  NullPointerException

  132.      *     (unchecked exception) Thrown if the <CODE>attribute</CODE> is null. 

  133.      * @throws  UnmodifiableSetException

  134.      *     (unchecked exception) Thrown if this attribute set does not support 

  135.      *     the <CODE>add()</CODE> operation. 

  136.      */

  137.     public boolean add(Attribute attribute);

  138. 

  139. 

  140.     /**

  141.      * Removes any attribute for this category from this attribute set if  

  142.      * present. If <CODE>category</CODE> is null, then 

  143.      * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 

  144.      *

  145.      * @param  category Attribute category to be removed from this

  146.      *                  attribute set.

  147.      *

  148.      * @return  <tt>true</tt> if this attribute set changed as a result of the

  149.      *         call, i.e., the given attribute value had been a member of this 

  150.      *          attribute set. 

  151.      * 

  152.      * @throws  UnmodifiableSetException

  153.      *     (unchecked exception) Thrown if this attribute set does not support 

  154.      *     the <CODE>remove()</CODE> operation. 

  155.      */

  156.     public boolean remove(Class category);

  157. 

  158.     /**

  159.      * Removes the specified attribute from this attribute set if  

  160.      * present. If <CODE>attribute</CODE> is null, then 

  161.      * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>. 

  162.      *

  163.      * @param  attribute Attribute value to be removed from this attribute set.

  164.      *

  165.      * @return  <tt>true</tt> if this attribute set changed as a result of the

  166.      *         call, i.e., the given attribute value had been a member of this 

  167.      *          attribute set. 

  168.      * 

  169.      * @throws  UnmodifiableSetException

  170.      *     (unchecked exception) Thrown if this attribute set does not support 

  171.      *     the <CODE>remove()</CODE> operation. 

  172.      */

  173.     public boolean remove(Attribute attribute);

  174. 

  175.     /**

  176.      * Returns <tt>true</tt> if this attribute set contains an 

  177.      * attribute for the specified category.

  178.      *

  179.      * @param  category whose presence in this attribute set is

  180.      *            to be tested.

  181.      *

  182.      * @return  <tt>true</tt> if this attribute set contains an attribute 

  183.      *         value for the specified category.

  184.      */

  185.     public boolean containsKey(Class category);

  186. 

  187.     /**

  188.      * Returns <tt>true</tt> if this attribute set contains the given  

  189.      * attribute value.

  190.      *

  191.      * @param  attribute  Attribute value whose presence in this

  192.      * attribute set is to be tested.

  193.      *

  194.      * @return  <tt>true</tt> if this attribute set contains the given 

  195.      *      attribute  value.

  196.      */

  197.     public boolean containsValue(Attribute attribute);

  198.         

  199.     /**

  200.      * Adds all of the elements in the specified set to this attribute.

  201.      * The outcome is the same as if the =

  202.      * {@link #add(Attribute) <CODE>add(Attribute)</CODE>} 

  203.      * operation had been applied to this attribute set successively with each 

  204.      * element from the specified set.

  205.      * The behavior of the <CODE>addAll(AttributeSet)</CODE>

  206.      * operation is unspecified if the specified set is modified while

  207.      * the operation is in progress.

  208.      * <P>

  209.      * If the <CODE>addAll(AttributeSet)</CODE> operation throws an exception,

  210.      * the effect on this attribute set's state is implementation dependent;

  211.      * elements from the specified set before the point of the exception may

  212.      * or may not have been added to this attribute set. 

  213.      *

  214.      * @param  attributes  whose elements are to be added to this attribute 

  215.      *            set.

  216.      *

  217.      * @return  <tt>true</tt> if this attribute set changed as a result of the

  218.      *          call.

  219.      * 

  220.      * @throws  UnmodifiableSetException

  221.      *     (Unchecked exception) Thrown if this attribute set does not support 

  222.      *     the <tt>addAll(AttributeSet)</tt> method. 

  223.      * @throws  NullPointerException

  224.      *     (Unchecked exception) Thrown if some element in the specified 

  225.      *     set is null.

  226.      *

  227.      * @see #add(Attribute)

  228.      */

  229.     public boolean addAll(AttributeSet attributes);

  230. 

  231.     /**

  232.      * Returns the number of attributes in this attribute set. If this

  233.      * attribute set contains more than <tt>Integer.MAX_VALUE</tt> elements,

  234.      * returns  <tt>Integer.MAX_VALUE</tt>.

  235.      *

  236.      * @return  The number of attributes in this attribute set.

  237.      */

  238.     public int size();

  239.     

  240.     /**

  241.      * Returns an array of the attributes contained in this set.

  242.      * @return the Attributes contained in this set as an array, zero length

  243.      * if the AttributeSet is empty.

  244.      */

  245.     public Attribute[] toArray();

  246. 

  247. 

  248.     /**

  249.      * Removes all attributes from this attribute set.

  250.      *

  251.      * @throws  UnmodifiableSetException

  252.      *   (unchecked exception) Thrown if this attribute set does not support 

  253.      *     the <CODE>clear()</CODE> operation. 

  254.      */

  255.     public void clear();

  256. 

  257.     /**

  258.      * Returns true if this attribute set contains no attributes.

  259.      *

  260.      * @return true if this attribute set contains no attributes.

  261.      */

  262.     public boolean isEmpty();

  263. 

  264.     /**

  265.      * Compares the specified object with this attribute set for equality. 

  266.      * Returns <tt>true</tt> if the given object is also an attribute set and 

  267.      * the two attribute sets contain the same attribute category-attribute 

  268.      * value mappings. This ensures that the 

  269.      * <tt>equals()</tt> method works properly across different  

  270.      * implementations of the AttributeSet interface. 

  271.      *

  272.      * @param  object to be compared for equality with this attribute set.

  273.      *

  274.      * @return  <tt>true</tt> if the specified object is equal to this 

  275.      *       attribute   set.

  276.      */

  277.     public boolean equals(Object object);

  278. 

  279.     /**

  280.      * Returns the hash code value for this attribute set. The hash code of an 

  281.      * attribute set is defined to be the sum of the hash codes of each entry  

  282.      * in the AttributeSet. 

  283.      * This ensures that <tt>t1.equals(t2)</tt> implies that 

  284.      * <tt>t1.hashCode()==t2.hashCode()</tt> for any two attribute sets 

  285.      * <tt>t1</tt> and <tt>t2</tt>, as required by the general contract of 

  286.      * {@link java.lang.Object#hashCode() <CODE>Object.hashCode()</CODE>}. 

  287.      *

  288.      * @return  The hash code value for this attribute set.

  289.      */

  290.     public int hashCode();

  291. 

  292. }