AttributeSet


1   /*
2    * @(#)AttributeSet.java    1.9 04/05/05
3    *
4    * Copyright 2004 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 }
293
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags