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