I committed this patch:
2006-01-16 David Gilbert <[EMAIL PROTECTED]>
* javax/swing/text/SimpleAttributeSet.java: Updated API docs all over.
Regards,
Dave
Index: javax/swing/text/SimpleAttributeSet.java
===================================================================
RCS file:
/sources/classpath/classpath/javax/swing/text/SimpleAttributeSet.java,v
retrieving revision 1.12
diff -u -r1.12 SimpleAttributeSet.java
--- javax/swing/text/SimpleAttributeSet.java 27 Sep 2005 21:31:36 -0000
1.12
+++ javax/swing/text/SimpleAttributeSet.java 16 Jan 2006 09:21:28 -0000
@@ -1,5 +1,5 @@
/* SimpleAttributeSet.java --
- Copyright (C) 2004, 2005 Free Software Foundation, Inc.
+ Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -42,33 +42,67 @@
import java.util.Enumeration;
import java.util.Hashtable;
+/**
+ * A set of attributes.
+ */
public class SimpleAttributeSet
implements MutableAttributeSet, Serializable, Cloneable
{
/** The serialization UID (compatible with JDK1.5). */
private static final long serialVersionUID = 8267656273837665219L;
+ /** An empty attribute set. */
public static final AttributeSet EMPTY = new SimpleAttributeSet();
+ /** Storage for the attributes. */
Hashtable tab;
+ /**
+ * Creates a new attribute set that is initially empty.
+ */
public SimpleAttributeSet()
{
this(null);
}
+ /**
+ * Creates a new <code>SimpleAttributeSet</code> with the same attributes
+ * and resolve parent as the specified set.
+ *
+ * @param a the attributes.
+ */
public SimpleAttributeSet(AttributeSet a)
{
+ // FIXME: null argument should throw NullPointerException
tab = new Hashtable();
if (a != null)
addAttributes(a);
}
+ /**
+ * Adds an attribute with the given <code>name</code> and <code>value</code>
+ * to the set. If the set already contains an attribute with the given
+ * <code>name</code>, the attribute value is updated.
+ *
+ * @param name the attribute name (<code>null</code> not permitted).
+ * @param value the value (<code>null</code> not permitted).
+ *
+ * @throws NullPointerException if either argument is <code>null</code>.
+ */
public void addAttribute(Object name, Object value)
{
tab.put(name, value);
}
+ /**
+ * Adds all the attributes from <code>attributes</code> to this set.
+ *
+ * @param attributes the set of attributes to add (<code>null</code> not
+ * permitted).
+ *
+ * @throws NullPointerException if <code>attributes</code> is
+ * <code>null</code>.
+ */
public void addAttributes(AttributeSet attributes)
{
Enumeration e = attributes.getAttributeNames();
@@ -80,6 +114,11 @@
}
}
+ /**
+ * Returns a clone of the attribute set.
+ *
+ * @return A clone of the attribute set.
+ */
public Object clone()
{
SimpleAttributeSet s = new SimpleAttributeSet();
@@ -97,6 +136,8 @@
*/
public boolean containsAttribute(Object name, Object value)
{
+ // FIXME: if the name is defined in this set, any match in the parent
+ // should be ignored
return (tab.containsKey(name) && tab.get(name).equals(value)) ||
(getResolveParent() != null && getResolveParent().
containsAttribute(name, value));
@@ -115,6 +156,15 @@
&& tab.get(name).equals(value);
}
+ /**
+ * Returns <code>true</code> of this <code>AttributeSet</code> contains all
+ * of the specified <code>attributes</code>.
+ *
+ * @param attributes the requested attributes
+ *
+ * @return <code>true</code> of this <code>AttributeSet</code> contains all
+ * of the specified <code>attributes</code>
+ */
public boolean containsAttributes(AttributeSet attributes)
{
Enumeration e = attributes.getAttributeNames();
@@ -128,11 +178,24 @@
return true;
}
+ /**
+ * Creates and returns a copy of this <code>AttributeSet</code>.
+ *
+ * @return a copy of this <code>AttributeSet</code>
+ */
public AttributeSet copyAttributes()
{
return (AttributeSet) clone();
}
+ /**
+ * Checks this set for equality with an arbitrary object.
+ *
+ * @param obj the object (<code>null</code> permitted).
+ *
+ * @return <code>true</code> if this set is equal to <code>obj</code>, and
+ * <code>false</code> otherwise.
+ */
public boolean equals(Object obj)
{
return
@@ -140,12 +203,23 @@
&& this.isEqual((AttributeSet) obj);
}
+ /**
+ * Returns the value of the specified attribute, or <code>null</code> if
+ * there is no attribute with that name. If the attribute is not defined
+ * directly in this set, the parent hierarchy (if there is one) will be
+ * used.
+ *
+ * @param name the attribute (<code>null</code> not permitted).
+ *
+ * @throws NullPointerException if <code>name</code> is <code>null</code>.
+ */
public Object getAttribute(Object name)
{
Object val = tab.get(name);
if (val != null)
return val;
+ // FIXME: The following instanceof check and cast is redundant
Object p = getResolveParent();
if (p != null && p instanceof AttributeSet)
return (((AttributeSet)p).getAttribute(name));
@@ -153,31 +227,72 @@
return null;
}
+ /**
+ * Returns the number of attributes stored in this set, plus 1 if a parent
+ * has been specified (the reference to the parent is stored as a special
+ * attribute). The attributes stored in the parent do NOT contribute
+ * to the count.
+ *
+ * @return The attribute count.
+ */
public int getAttributeCount()
{
return tab.size();
}
+ /**
+ * Returns an enumeration of the attribute names.
+ *
+ * @return An enumeration of the attribute names.
+ */
public Enumeration getAttributeNames()
{
return tab.keys();
}
+ /**
+ * Returns the resolving parent.
+ *
+ * @return The resolving parent (possibly <code>null</code>).
+ *
+ * @see #setResolveParent(AttributeSet)
+ */
public AttributeSet getResolveParent()
{
return (AttributeSet) tab.get(ResolveAttribute);
}
+ /**
+ * Returns a hash code for this instance.
+ *
+ * @return A hash code.
+ */
public int hashCode()
{
return tab.hashCode();
}
+ /**
+ * Returns <code>true</code> if the given attribute is defined in this set,
+ * and <code>false</code> otherwise. The parent attribute set is not
+ * checked.
+ *
+ * @param attrName the attribute name (<code>null</code> not permitted).
+ */
public boolean isDefined(Object attrName)
{
return tab.containsKey(attrName);
}
+ /**
+ * Returns <code>true</code> if the set contains no attributes, and
+ * <code>false</code> otherwise. Note that the resolving parent is
+ * stored as an attribute, so this method will return <code>false</code> if
+ * a resolving parent is set.
+ *
+ * @return <code>true</code> if the set contains no attributes, and
+ * <code>false</code> otherwise.
+ */
public boolean isEmpty()
{
return tab.isEmpty();
@@ -186,7 +301,13 @@
/**
* Returns true if the given set has the same number of attributes
* as this set and <code>containsAttributes(attr)</code> returns
- * true.
+ * <code>true</code>.
+ *
+ * @param attr the attribute set (<code>null</code> not permitted).
+ *
+ * @return A boolean.
+ *
+ * @throws NullPointerException if <code>attr</code> is <code>null</code>.
*/
public boolean isEqual(AttributeSet attr)
{
@@ -194,6 +315,15 @@
&& this.containsAttributes(attr);
}
+ /**
+ * Removes the attribute with the specified <code>name</code>, if this
+ * attribute is defined. This method will only remove an attribute from
+ * this set, not from the resolving parent.
+ *
+ * @param name the attribute name (<code>null</code> not permitted).
+ *
+ * @throws NullPointerException if <code>name</code> is <code>null</code>.
+ */
public void removeAttribute(Object name)
{
tab.remove(name);
@@ -202,7 +332,12 @@
/**
* Removes attributes from this set if they are found in the
* given set. Only attributes whose key AND value are removed.
- * Removes attributes only from this set, not from the resolving parent.
+ * Removes attributes only from this set, not from the resolving parent.
+ * Since the resolving parent is stored as an attribute, if
+ * <code>attributes</code> has the same resolving parent as this set, the
+ * parent will be removed from this set.
+ *
+ * @param attributes the attributes (<code>null</code> not permitted).
*/
public void removeAttributes(AttributeSet attributes)
{
@@ -216,6 +351,14 @@
}
}
+ /**
+ * Removes the attributes listed in <code>names</code>.
+ *
+ * @param names the attribute names (<code>null</code> not permitted).
+ *
+ * @throws NullPointerException if <code>names</code> is <code>null</code>
+ * or contains any <code>null</code> values.
+ */
public void removeAttributes(Enumeration names)
{
while (names.hasMoreElements())
@@ -224,11 +367,31 @@
}
}
+ /**
+ * Sets the reolving parent for this set. When looking up an attribute, if
+ * it is not found in this set, then the resolving parent is also used for
+ * the lookup.
+ * <p>
+ * Note that the parent is stored as an attribute, and will contribute 1 to
+ * the count returned by [EMAIL PROTECTED] #getAttributeCount()}.
+ *
+ * @param parent the parent attribute set (<code>null</code> not permitted).
+ *
+ * @throws NullPointerException if <code>parent</code> is <code>null</code>.
+ *
+ * @see #setResolveParent(AttributeSet)
+ */
public void setResolveParent(AttributeSet parent)
{
addAttribute(ResolveAttribute, parent);
}
-
+
+ /**
+ * Returns a string representation of this instance, typically used for
+ * debugging purposes.
+ *
+ * @return A string representation of this instance.
+ */
public String toString()
{
return tab.toString();
_______________________________________________
Classpath-patches mailing list
Classpath-patches@gnu.org
http://lists.gnu.org/mailman/listinfo/classpath-patches
