View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, 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 }