< prev index next >

src/java.desktop/share/classes/javax/print/attribute/AttributeSet.java

Print this page




  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  *
 107  * @author  Alan Kaminsky
 108  */
 109 public interface AttributeSet {
 110 
 111 
 112     /**
 113      * Returns the attribute value which this attribute set contains in the
 114      * given attribute category. Returns <tt>null</tt> if this attribute set
 115      * does not contain any attribute value in the given attribute category.
 116      *
 117      * @param  category  Attribute category whose associated attribute value
 118      *                   is to be returned. It must be a
 119      *                   {@link java.lang.Class Class}
 120      *                   that implements interface {@link Attribute
 121      *                   Attribute}.
 122      *
 123      * @return  The attribute value in the given attribute category contained
 124      *          in this attribute set, or <tt>null</tt> if this attribute set
 125      *          does not contain any attribute value in the given attribute
 126      *          category.
 127      *
 128      * @throws  NullPointerException
 129      *     (unchecked exception) Thrown if the <CODE>category</CODE> is null.
 130      * @throws  ClassCastException
 131      *     (unchecked exception) Thrown if the <CODE>category</CODE> is not a
 132      *     {@link java.lang.Class Class} that implements interface {@link
 133      *     Attribute Attribute}.
 134      */
 135     public Attribute get(Class<?> category);
 136 
 137     /**
 138      * Adds the specified attribute to this attribute set if it is not
 139      * already present, first removing any existing value in the same
 140      * attribute category as the specified attribute value.
 141      *
 142      * @param  attribute  Attribute value to be added to this attribute set.
 143      *
 144      * @return  <tt>true</tt> if this attribute set changed as a result of the
 145      *          call, i.e., the given attribute value was not already a member
 146      *          of this attribute set.
 147      *
 148      * @throws  NullPointerException
 149      *     (unchecked exception) Thrown if the <CODE>attribute</CODE> is null.
 150      * @throws  UnmodifiableSetException
 151      *     (unchecked exception) Thrown if this attribute set does not support
 152      *     the <CODE>add()</CODE> operation.
 153      */
 154     public boolean add(Attribute attribute);
 155 
 156 
 157     /**
 158      * Removes any attribute for this category from this attribute set if
 159      * present. If <CODE>category</CODE> is null, then
 160      * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>.
 161      *
 162      * @param  category Attribute category to be removed from this
 163      *                  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(Class<?> category);
 174 
 175     /**
 176      * Removes the specified attribute from this attribute set if
 177      * present. If <CODE>attribute</CODE> is null, then
 178      * <CODE>remove()</CODE> does nothing and returns <tt>false</tt>.
 179      *
 180      * @param  attribute Attribute value to be removed from this attribute set.
 181      *
 182      * @return  <tt>true</tt> if this attribute set changed as a result of the
 183      *         call, i.e., the given attribute value had been a member of this
 184      *          attribute set.
 185      *
 186      * @throws  UnmodifiableSetException
 187      *     (unchecked exception) Thrown if this attribute set does not support
 188      *     the <CODE>remove()</CODE> operation.
 189      */
 190     public boolean remove(Attribute attribute);
 191 
 192     /**
 193      * Returns <tt>true</tt> if this attribute set contains an
 194      * attribute for the specified category.
 195      *
 196      * @param  category whose presence in this attribute set is
 197      *            to be tested.
 198      *
 199      * @return  <tt>true</tt> if this attribute set contains an attribute
 200      *         value for the specified category.
 201      */
 202     public boolean containsKey(Class<?> category);
 203 
 204     /**
 205      * Returns <tt>true</tt> if this attribute set contains the given
 206      * attribute value.
 207      *
 208      * @param  attribute  Attribute value whose presence in this
 209      * attribute set is to be tested.
 210      *
 211      * @return  <tt>true</tt> if this attribute set contains the given
 212      *      attribute  value.
 213      */
 214     public boolean containsValue(Attribute attribute);
 215 
 216     /**
 217      * Adds all of the elements in the specified set to this attribute.
 218      * The outcome is the same as if the =
 219      * {@link #add(Attribute) add(Attribute)}
 220      * operation had been applied to this attribute set successively with each
 221      * element from the specified set.
 222      * The behavior of the <CODE>addAll(AttributeSet)</CODE>
 223      * operation is unspecified if the specified set is modified while
 224      * the operation is in progress.
 225      * <P>
 226      * If the <CODE>addAll(AttributeSet)</CODE> operation throws an exception,
 227      * the effect on this attribute set's state is implementation dependent;
 228      * elements from the specified set before the point of the exception may
 229      * or may not have been added to this attribute set.
 230      *
 231      * @param  attributes  whose elements are to be added to this attribute
 232      *            set.
 233      *
 234      * @return  <tt>true</tt> if this attribute set changed as a result of the
 235      *          call.
 236      *
 237      * @throws  UnmodifiableSetException
 238      *     (Unchecked exception) Thrown if this attribute set does not support
 239      *     the <tt>addAll(AttributeSet)</tt> method.
 240      * @throws  NullPointerException
 241      *     (Unchecked exception) Thrown if some element in the specified
 242      *     set is null.
 243      *
 244      * @see #add(Attribute)
 245      */
 246     public boolean addAll(AttributeSet attributes);
 247 
 248     /**
 249      * Returns the number of attributes in this attribute set. If this
 250      * attribute set contains more than <tt>Integer.MAX_VALUE</tt> elements,
 251      * returns  <tt>Integer.MAX_VALUE</tt>.
 252      *
 253      * @return  The number of attributes in this attribute set.
 254      */
 255     public int size();
 256 
 257     /**
 258      * Returns an array of the attributes contained in this set.
 259      * @return the Attributes contained in this set as an array, zero length
 260      * if the AttributeSet is empty.
 261      */
 262     public Attribute[] toArray();
 263 
 264 
 265     /**
 266      * Removes all attributes from this attribute set.
 267      *
 268      * @throws  UnmodifiableSetException
 269      *   (unchecked exception) Thrown if this attribute set does not support
 270      *     the <CODE>clear()</CODE> operation.
 271      */
 272     public void clear();
 273 
 274     /**
 275      * Returns true if this attribute set contains no attributes.
 276      *
 277      * @return true if this attribute set contains no attributes.
 278      */
 279     public boolean isEmpty();
 280 
 281     /**
 282      * Compares the specified object with this attribute set for equality.
 283      * Returns <tt>true</tt> if the given object is also an attribute set and
 284      * the two attribute sets contain the same attribute category-attribute
 285      * value mappings. This ensures that the
 286      * <tt>equals()</tt> method works properly across different
 287      * implementations of the AttributeSet interface.
 288      *
 289      * @param  object to be compared for equality with this attribute set.
 290      *
 291      * @return  <tt>true</tt> if the specified object is equal to this
 292      *       attribute   set.
 293      */
 294     public boolean equals(Object object);
 295 
 296     /**
 297      * Returns the hash code value for this attribute set. The hash code of an
 298      * attribute set is defined to be the sum of the hash codes of each entry
 299      * in the AttributeSet.
 300      * This ensures that <tt>t1.equals(t2)</tt> implies that
 301      * <tt>t1.hashCode()==t2.hashCode()</tt> for any two attribute sets
 302      * <tt>t1</tt> and <tt>t2</tt>, as required by the general contract of
 303      * {@link java.lang.Object#hashCode() Object.hashCode()}.
 304      *
 305      * @return  The hash code value for this attribute set.
 306      */
 307     public int hashCode();
 308 
 309 }


  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  *
 107  * @author  Alan Kaminsky
 108  */
 109 public interface AttributeSet {
 110 
 111 
 112     /**
 113      * Returns the attribute value which this attribute set contains in the
 114      * given attribute category. Returns {@code null} if this attribute set
 115      * does not contain any attribute value in the given attribute category.
 116      *
 117      * @param  category  Attribute category whose associated attribute value
 118      *                   is to be returned. It must be a
 119      *                   {@link java.lang.Class Class}
 120      *                   that implements interface {@link Attribute
 121      *                   Attribute}.
 122      *
 123      * @return  The attribute value in the given attribute category contained
 124      *          in this attribute set, or {@code null} if this attribute set
 125      *          does not contain any attribute value in the given attribute
 126      *          category.
 127      *
 128      * @throws  NullPointerException
 129      *     (unchecked exception) Thrown if the {@code category} is null.
 130      * @throws  ClassCastException
 131      *     (unchecked exception) Thrown if the {@code category} is not a
 132      *     {@link java.lang.Class Class} that implements interface {@link
 133      *     Attribute Attribute}.
 134      */
 135     public Attribute get(Class<?> category);
 136 
 137     /**
 138      * Adds the specified attribute to this attribute set if it is not
 139      * already present, first removing any existing value in the same
 140      * attribute category as the specified attribute value.
 141      *
 142      * @param  attribute  Attribute value to be added to this attribute set.
 143      *
 144      * @return  {@code true} if this attribute set changed as a result of the
 145      *          call, i.e., the given attribute value was not already a member
 146      *          of this attribute set.
 147      *
 148      * @throws  NullPointerException
 149      *     (unchecked exception) Thrown if the {@code attribute} is null.
 150      * @throws  UnmodifiableSetException
 151      *     (unchecked exception) Thrown if this attribute set does not support
 152      *     the {@code add()} operation.
 153      */
 154     public boolean add(Attribute attribute);
 155 
 156 
 157     /**
 158      * Removes any attribute for this category from this attribute set if
 159      * present. If {@code category} is null, then
 160      * {@code remove()} does nothing and returns {@code false}.
 161      *
 162      * @param  category Attribute category to be removed from this
 163      *                  attribute set.
 164      *
 165      * @return  {@code true} 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()} operation.
 172      */
 173     public boolean remove(Class<?> category);
 174 
 175     /**
 176      * Removes the specified attribute from this attribute set if
 177      * present. If {@code attribute} is null, then
 178      * {@code remove()} does nothing and returns {@code false}.
 179      *
 180      * @param  attribute Attribute value to be removed from this attribute set.
 181      *
 182      * @return  {@code true} if this attribute set changed as a result of the
 183      *         call, i.e., the given attribute value had been a member of this
 184      *          attribute set.
 185      *
 186      * @throws  UnmodifiableSetException
 187      *     (unchecked exception) Thrown if this attribute set does not support
 188      *     the {@code remove()} operation.
 189      */
 190     public boolean remove(Attribute attribute);
 191 
 192     /**
 193      * Returns {@code true} if this attribute set contains an
 194      * attribute for the specified category.
 195      *
 196      * @param  category whose presence in this attribute set is
 197      *            to be tested.
 198      *
 199      * @return  {@code true} if this attribute set contains an attribute
 200      *         value for the specified category.
 201      */
 202     public boolean containsKey(Class<?> category);
 203 
 204     /**
 205      * Returns {@code true} if this attribute set contains the given
 206      * attribute value.
 207      *
 208      * @param  attribute  Attribute value whose presence in this
 209      * attribute set is to be tested.
 210      *
 211      * @return  {@code true} if this attribute set contains the given
 212      *      attribute  value.
 213      */
 214     public boolean containsValue(Attribute attribute);
 215 
 216     /**
 217      * Adds all of the elements in the specified set to this attribute.
 218      * The outcome is the same as if the =
 219      * {@link #add(Attribute) add(Attribute)}
 220      * operation had been applied to this attribute set successively with each
 221      * element from the specified set.
 222      * The behavior of the {@code addAll(AttributeSet)}
 223      * operation is unspecified if the specified set is modified while
 224      * the operation is in progress.
 225      * <P>
 226      * If the {@code addAll(AttributeSet)} operation throws an exception,
 227      * the effect on this attribute set's state is implementation dependent;
 228      * elements from the specified set before the point of the exception may
 229      * or may not have been added to this attribute set.
 230      *
 231      * @param  attributes  whose elements are to be added to this attribute
 232      *            set.
 233      *
 234      * @return  {@code true} if this attribute set changed as a result of the
 235      *          call.
 236      *
 237      * @throws  UnmodifiableSetException
 238      *     (Unchecked exception) Thrown if this attribute set does not support
 239      *     the {@code addAll(AttributeSet)} method.
 240      * @throws  NullPointerException
 241      *     (Unchecked exception) Thrown if some element in the specified
 242      *     set is null.
 243      *
 244      * @see #add(Attribute)
 245      */
 246     public boolean addAll(AttributeSet attributes);
 247 
 248     /**
 249      * Returns the number of attributes in this attribute set. If this
 250      * attribute set contains more than {@code Integer.MAX_VALUE} elements,
 251      * returns  {@code Integer.MAX_VALUE}.
 252      *
 253      * @return  The number of attributes in this attribute set.
 254      */
 255     public int size();
 256 
 257     /**
 258      * Returns an array of the attributes contained in this set.
 259      * @return the Attributes contained in this set as an array, zero length
 260      * if the AttributeSet is empty.
 261      */
 262     public Attribute[] toArray();
 263 
 264 
 265     /**
 266      * Removes all attributes from this attribute set.
 267      *
 268      * @throws  UnmodifiableSetException
 269      *   (unchecked exception) Thrown if this attribute set does not support
 270      *     the {@code clear()} operation.
 271      */
 272     public void clear();
 273 
 274     /**
 275      * Returns true if this attribute set contains no attributes.
 276      *
 277      * @return true if this attribute set contains no attributes.
 278      */
 279     public boolean isEmpty();
 280 
 281     /**
 282      * Compares the specified object with this attribute set for equality.
 283      * Returns {@code true} if the given object is also an attribute set and
 284      * the two attribute sets contain the same attribute category-attribute
 285      * value mappings. This ensures that the
 286      * {@code equals()} method works properly across different
 287      * implementations of the AttributeSet interface.
 288      *
 289      * @param  object to be compared for equality with this attribute set.
 290      *
 291      * @return  {@code true} if the specified object is equal to this
 292      *       attribute   set.
 293      */
 294     public boolean equals(Object object);
 295 
 296     /**
 297      * Returns the hash code value for this attribute set. The hash code of an
 298      * attribute set is defined to be the sum of the hash codes of each entry
 299      * in the AttributeSet.
 300      * This ensures that {@code t1.equals(t2)} implies that
 301      * {@code t1.hashCode()==t2.hashCode()} for any two attribute sets
 302      * {@code t1} and {@code t2}, as required by the general contract of
 303      * {@link java.lang.Object#hashCode() Object.hashCode()}.
 304      *
 305      * @return  The hash code value for this attribute set.
 306      */
 307     public int hashCode();
 308 
 309 }
< prev index next >