[jdom-interest] Element javadoc
Elliotte Rusty Harold
elharo at metalab.unc.edu
Thu May 16 14:35:35 PDT 2002
The atatched patch adds @throws comments for various runtime exceptions
thrown by various constructors and methods in the Element class. It also
makes a couple of other minor changes to the doc comments in a couple of
places. No actual code is changed.
--
+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo at metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+
| The XML Bible, 2nd Edition (IDG Books, 2001) |
| http://www.cafeconleche.org/books/bible2/ |
| http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/ |
+----------------------------------+---------------------------------+
| Read Cafe au Lait for Java News: http://www.cafeaulait.org/ |
| Read Cafe con Leche for XML News: http://www.cafeconleche.org/ |
+----------------------------------+---------------------------------+
-------------- next part --------------
Index: src/java/org/jdom/Element.java
===================================================================
RCS file: /home/cvspublic/jdom/src/java/org/jdom/Element.java,v
retrieving revision 1.123
diff -d -u -r1.123 Element.java
--- src/java/org/jdom/Element.java 2002/05/11 07:52:48 1.123
+++ src/java/org/jdom/Element.java 2002/05/17 05:41:33
@@ -139,6 +139,8 @@
*
* @param name <code>String</code> name of element.
* @param namespace <code>Namespace</code> to put element in.
+ * @throws IllegalNameException if the given name is illegal as an
+ * element name.
*/
public Element(String name, Namespace namespace) {
setName(name);
@@ -150,6 +152,8 @@
* <code>{@link Namespace}</code>.
*
* @param name <code>String</code> name of element.
+ * @throws IllegalNameException if the given name is illegal as an
+ * element name.
*/
public Element(String name) {
this(name, (Namespace) null);
@@ -165,6 +169,9 @@
* @param name <code>String</code> name of element.
* @param uri <code>String</code> URI for <code>Namespace</code> element
* should be in.
+ * @throws IllegalNameException if the given name is illegal as an
+ * element name or the given URI is illegal as a
+ * namespace URI
*/
public Element(String name, String uri) {
this(name, Namespace.getNamespace("", uri));
@@ -179,6 +186,9 @@
* @param name <code>String</code> name of element.
* @param uri <code>String</code> URI for <code>Namespace</code> element
* should be in.
+ * @throws IllegalNameException if the given name is illegal as an
+ * element name, the given prefix is illegal as a namespace
+ * prefix, or the given URI is illegal as a namespace URI
*/
public Element(String name, String prefix, String uri) {
this(name, Namespace.getNamespace(prefix, uri));
@@ -304,9 +314,8 @@
* This returns the full name of the
* <code>Element</code>, in the form
* [namespacePrefix]:[localName]. If
- * no namespace prefix exists for the
- * <code>Element</code>, simply the
- * local name is returned.
+ * the <code>Element</code> does not have a namespace prefix,
+ * then the local name is returned.
*
* @return <code>String</code> - full name of element.
*/
@@ -482,7 +491,7 @@
* this single element, including whitespace and CDATA
* sections if they exist. It's essentially the concatenation of
* all <code>Text</code> and <code>CDATA</code> nodes returned by
- * getContent(). The call does not recurse into child elements.
+ * <code>getContent()</code>. The call does not recurse into child elements.
* If no textual value exists for the
* element, an empty <code>String</code> ("") is returned.
*
@@ -661,6 +670,9 @@
*
* @param text new content for the element
* @return this element modified
+ * @throws IllegalDataException if <code>text</code> contains an
+ * illegal character such as a vertical tab (as determined
+ * by {@link org.jdom.Verifier#checkCharacterData})
*/
public Element setText(String text) {
content.clear();
@@ -877,6 +889,9 @@
*
* @param str <code>String</code> to add
* @return this element modified
+ * @throws IllegalDataException if <code>str</code> contains an
+ * illegal character such as a vertical tab (as determined
+ * by {@link org.jdom.Verifier#checkCharacterData})
*/
public Element addContent(String str) {
return addContent(new Text(str));
@@ -888,6 +903,8 @@
*
* @param text <code>Text</code> to add
* @return this element modified
+ * @throws IllegalAddException if the <code>Text</code> object
+ * you're attempting to add already has a parent element.
*/
public Element addContent(Text text) {
content.add(text);
@@ -1188,8 +1205,10 @@
*
* @param attributes <code>List</code> of attributes to set
* @return this element modified
- * @throws IllegalAddException if the List contains objects of
- * illegal types.
+ * @throws IllegalAddException if the List contains objects
+ * that are not instances of <code>Attribute</code>,
+ * or if any of the <code>Attribute</code> objects have
+ * conflicting namespace prefixes.
*/
public Element setAttributes(List newAttributes) {
attributes.clearAndSet(newAttributes);
@@ -1205,6 +1224,11 @@
* @param name name of the attribute to set
* @param value value of the attribute to set
* @return this element modified
+ * @throws IllegalNameException if the given name is illegal as an
+ * attribute name.
+ * @throws IllegalDataException if the given attribute value is
+ * illegal character data (as determined by
+ * {@link org.jdom.Verifier#checkCharacterData}).
*/
public Element setAttribute(String name, String value) {
return setAttribute(new Attribute(name, value));
@@ -1220,6 +1244,14 @@
* @param value value of the attribute to set
* @param ns namespace of the attribute to set
* @return this element modified
+ * @throws IllegalNameException if the given name is illegal as an
+ * attribute name, or if the namespace is an unprefixed default
+ * namespace
+ * @throws IllegalDataException if the given attribute value is
+ * illegal character data (as determined by
+ * {@link org.jdom.Verifier#checkCharacterData}).
+ * @throws IllegalAddException if the attribute namespace prefix
+ * collides with another namespace prefix on the element.
*/
public Element setAttribute(String name, String value, Namespace ns) {
return setAttribute(new Attribute(name, value, ns));
@@ -1543,7 +1575,8 @@
* This removes all child elements. Returns true if any were removed.
* </p>
* @deprecated Deprecated in Beta 9, instead of this method you can call
- * clear() on the list returned by getChildren() or by getContent()
+ * <code>clear()</code> on the list returned by <code>getChildren()</code> or by
+ * <code>getContent()</code>
*
* @return whether deletion occurred
*/
More information about the jdom-interest
mailing list