1. /*
  2. * @(#)JobStateReasons.java 1.5 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. package javax.print.attribute.standard;
  8. import java.util.Collection;
  9. import java.util.HashSet;
  10. import javax.print.attribute.PrintJobAttribute;
  11. /**
  12. * Class JobStateReasons is a printing attribute class, a set of enumeration
  13. * values, that provides additional information about the job's current state,
  14. * i.e., information that augments the value of the job's {@link JobState
  15. * JobState} attribute.
  16. * <P>
  17. * Instances of {@link JobStateReason JobStateReason} do not appear in a Print
  18. * Job's attribute set directly. Rather, a JobStateReasons attribute appears in
  19. * the Print Job's attribute set. The JobStateReasons attribute contains zero,
  20. * one, or more than one {@link JobStateReason JobStateReason} objects which
  21. * pertain to the Print Job's status. The printer adds a {@link JobStateReason
  22. * JobStateReason} object to the Print Job's JobStateReasons attribute when the
  23. * corresponding condition becomes true of the Print Job, and the printer
  24. * removes the {@link JobStateReason JobStateReason} object again when the
  25. * corresponding condition becomes false, regardless of whether the Print Job's
  26. * overall {@link JobState JobState} also changed.
  27. * <P>
  28. * Class JobStateReasons inherits its implementation from class {@link
  29. * java.util.HashSet java.util.HashSet}. Unlike most printing attributes which
  30. * are immutable once constructed, class JobStateReasons is designed to be
  31. * mutable; you can add {@link JobStateReason JobStateReason} objects to an
  32. * existing JobStateReasons object and remove them again. However, like class
  33. * {@link java.util.HashSet java.util.HashSet}, class JobStateReasons is not
  34. * multiple thread safe. If a JobStateReasons object will be used by multiple
  35. * threads, be sure to synchronize its operations (e.g., using a synchronized
  36. * set view obtained from class {@link java.util.Collections
  37. * java.util.Collections}).
  38. * <P>
  39. * <B>IPP Compatibility:</B> The string value returned by each individual {@link
  40. * JobStateReason JobStateReason} object's <CODE>toString()</CODE> method gives
  41. * the IPP keyword value. The category name returned by <CODE>getName()</CODE>
  42. * gives the IPP attribute name.
  43. * <P>
  44. *
  45. * @author Alan Kaminsky
  46. */
  47. public final class JobStateReasons extends HashSet implements PrintJobAttribute {
  48. /**
  49. * Construct a new, empty job state reasons attribute; the underlying hash
  50. * set has the default initial capacity and load factor.
  51. */
  52. public JobStateReasons() {
  53. super();
  54. }
  55. /**
  56. * Construct a new, empty job state reasons attribute; the underlying hash
  57. * set has the given initial capacity and the default load factor.
  58. *
  59. * @param initialCapacity Initial capacity.
  60. * @throws IllegalArgumentException if the initial capacity is less
  61. * than zero.
  62. */
  63. public JobStateReasons(int initialCapacity) {
  64. super (initialCapacity);
  65. }
  66. /**
  67. * Construct a new, empty job state reasons attribute; the underlying hash
  68. * set has the given initial capacity and load factor.
  69. *
  70. * @param initialCapacity Initial capacity.
  71. * @param loadFactor Load factor.
  72. * @throws IllegalArgumentException if the initial capacity is less
  73. * than zero.
  74. */
  75. public JobStateReasons(int initialCapacity, float loadFactor) {
  76. super (initialCapacity, loadFactor);
  77. }
  78. /**
  79. * Construct a new job state reasons attribute that contains the same
  80. * {@link JobStateReason JobStateReason} objects as the given collection.
  81. * The underlying hash set's initial capacity and load factor are as
  82. * specified in the superclass constructor {@link
  83. * java.util.HashSet#HashSet(java.util.Collection)
  84. * <CODE>HashSet(Collection)</CODE>}.
  85. *
  86. * @param collection Collection to copy.
  87. *
  88. * @exception NullPointerException
  89. * (unchecked exception) Thrown if <CODE>collection</CODE> is null or
  90. * if any element in <CODE>collection</CODE> is null.
  91. * @throws ClassCastException
  92. * (unchecked exception) Thrown if any element in
  93. * <CODE>collection</CODE> is not an instance of class {@link
  94. * JobStateReason JobStateReason}.
  95. */
  96. public JobStateReasons(Collection collection) {
  97. super (collection);
  98. }
  99. /**
  100. * Adds the specified element to this job state reasons attribute if it is
  101. * not already present. The element to be added must be an instance of class
  102. * {@link JobStateReason JobStateReason}. If this job state reasons
  103. * attribute already contains the specified element, the call leaves this
  104. * job state reasons attribute unchanged and returns <tt>false</tt>.
  105. *
  106. * @param o Element to be added to this job state reasons attribute.
  107. *
  108. * @return <tt>true</tt> if this job state reasons attribute did not
  109. * already contain the specified element.
  110. *
  111. * @throws NullPointerException
  112. * (unchecked exception) Thrown if the specified element is null.
  113. * @throws ClassCastException
  114. * (unchecked exception) Thrown if the specified element is not an
  115. * instance of class {@link JobStateReason JobStateReason}.
  116. */
  117. public boolean add(Object o) {
  118. if (o == null) {
  119. throw new NullPointerException();
  120. }
  121. return super.add ((JobStateReason) o);
  122. }
  123. /**
  124. * Get the printing attribute class which is to be used as the "category"
  125. * for this printing attribute value.
  126. * <P>
  127. * For class JobStateReasons, the category is class JobStateReasons itself.
  128. *
  129. * @return Printing attribute class (category), an instance of class
  130. * {@link java.lang.Class java.lang.Class}.
  131. */
  132. public final Class getCategory() {
  133. return JobStateReasons.class;
  134. }
  135. /**
  136. * Get the name of the category of which this attribute value is an
  137. * instance.
  138. * <P>
  139. * For class JobStateReasons, the category
  140. * name is <CODE>"job-state-reasons"</CODE>.
  141. *
  142. * @return Attribute category name.
  143. */
  144. public final String getName() {
  145. return "job-state-reasons";
  146. }
  147. }