diff options
Diffstat (limited to 'libjava/classpath/javax/print/attribute/AttributeSet.java')
| -rw-r--r-- | libjava/classpath/javax/print/attribute/AttributeSet.java | 147 |
1 files changed, 133 insertions, 14 deletions
diff --git a/libjava/classpath/javax/print/attribute/AttributeSet.java b/libjava/classpath/javax/print/attribute/AttributeSet.java index cdc7a8e4876..b4bdecad254 100644 --- a/libjava/classpath/javax/print/attribute/AttributeSet.java +++ b/libjava/classpath/javax/print/attribute/AttributeSet.java @@ -1,5 +1,5 @@ /* AttributeSet.java -- - Copyright (C) 2002 Free Software Foundation, Inc. + Copyright (C) 2002, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,40 +38,159 @@ exception statement from your version. */ package javax.print.attribute; /** - * @author Michael Koch + * <code>AttributeSet</code> is the top-level interface for sets of printing + * attributes in the Java Print Service API. + * <p> + * There are no duplicate values allowed in an attribute set and there is + * at most one attribute object contained per category type. Based on the + * {@link java.util.Map} interface the values of attribute sets are objects + * of type {@link javax.print.attribute.Attribute} and the entries are the + * categories as {@link java.lang.Class} instances. + * </p> + * <p> + * The following specialized types of <code>AttributeSet</code> are available: + * <ul> + * <li>{@link javax.print.attribute.DocAttributeSet}</li> + * <li>{@link javax.print.attribute.PrintRequestAttributeSet}</li> + * <li>{@link javax.print.attribute.PrintJobAttributeSet}</li> + * <li>{@link javax.print.attribute.PrintServiceAttributeSet}</li> + * </ul> + * </p> + * <p> + * Attribute sets may be unmodifiable depending on the context of usage. If + * used as read-only attribute set modifying operations throw an + * {@link javax.print.attribute.UnmodifiableSetException}. + * </p> + * <p> + * The Java Print Service API provides implementation classes for the existing + * attribute set interfaces but applications may use their own implementations. + * </p> + * + * @author Michael Koch (konqueror@gmx.de) */ public interface AttributeSet { /** - * Adds the specified attribute value to this attribute set + * Adds the specified attribute value to this attribute set * if it is not already present. + * + * This operation removes any existing attribute of the same category + * before adding the given attribute to the set. + * + * @param attribute the attribute to add. + * @return <code>true</code> if the set is changed, false otherwise. + * @throws NullPointerException if the attribute is <code>null</code>. + * @throws UnmodifiableSetException if the set does not support modification. */ boolean add (Attribute attribute); /** - * Adds all of the elements in the specified set to this attribute. + * Adds all of the elements in the specified set to this attribute set. + * + * @param attributes the set of attributes to add. + * @return <code>true</code> if the set is changed, false otherwise. + * @throws UnmodifiableSetException if the set does not support modification. + * + * @see #add(Attribute) */ boolean addAll (AttributeSet attributes); - + + /** + * Removes all attributes from this attribute set. + * + * @throws UnmodifiableSetException if the set does not support modification. + */ void clear (); - + + /** + * Checks if this attributes set contains an attribute with the given + * category. + * + * @param category the category to test for. + * @return <code>true</code> if an attribute of the category is contained + * in the set, <code>false</code> otherwise. + */ boolean containsKey (Class category); - + + /** + * Checks if this attribute set contains the given attribute. + * + * @param attribute the attribute to test for. + * @return <code>true</code> if the attribute is contained in the set, + * <code>false</code> otherwise. + */ boolean containsValue (Attribute attribute); + /** + * Tests this set for equality with the given object. <code>true</code> is + * returned, if the given object is also of type <code>AttributeSet</code> + * and the contained attributes are the same as in this set. + * + * @param obj the Object to test. + * @return <code>true</code> if equal, false otherwise. + */ boolean equals (Object obj); - - Attribute get (Class Category); - + + /** + * Returns the attribute object contained in this set for the given attribute + * category. + * + * @param category the category of the attribute. A <code>Class</code> + * instance of a class implementing the <code>Attribute</code> interface. + * @return The attribute for this category or <code>null</code> if no + * attribute is contained for the given category. + * @throws NullPointerException if category is null. + * @throws ClassCastException if category is not implementing + * <code>Attribute</code>. + */ + Attribute get (Class category); + + /** + * Returns the hashcode value. The hashcode value is the sum of all hashcodes + * of the attributes contained in this set. + * + * @return The hashcode for this attribute set. + */ int hashCode (); - + + /** + * Checks if the attribute set is empty. + * + * @return <code>true</code> if the attribute set is empty, false otherwise. + */ boolean isEmpty (); + /** + * Removes the given attribute from the set. If the given attribute is <code>null</code> + * nothing is done and <code>false</code> is returned. + * + * @param attribute the attribute to remove. + * @return <code>true</code> if removed, false in all other cases. + * @throws UnmodifiableSetException if the set does not support modification. + */ boolean remove (Attribute attribute); - + + /** + * Removes the attribute entry of the given category from the set. If the given + * category is <code>null</code> nothing is done and <code>false</code> is returned. + * + * @param category the category of the entry to be removed. + * @return <code>true</code> if an attribute is removed, false in all other cases. + * @throws UnmodifiableSetException if the set does not support modification. + */ boolean remove (Class category); - + + /** + * Returns the number of elements in this attribute set. + * + * @return The number of elements. + */ int size (); - + + /** + * Returns the content of the attribute set as an array + * + * @return An array of attributes. + */ Attribute[] toArray (); } |