org.jdom
Class Element

java.lang.Object
  |
  +--org.jdom.Element

public class Element
extends java.lang.Object

Attribute defines behavior for an XML attribute, modeled in Java. Methods allow the user to obtain the value of the element's textual content, obtain its attributes, and get its children.

Version:
1.0
Author:
Brett McLaughlin, Jason Hunter

Field Summary
protected  java.util.List attributes
          The attributes of the Element
protected  java.util.List content
          The mixed content of the Element
protected  java.lang.String name
          The local name of the Element
protected  java.lang.String prefix
          The namespace prefix of the Element
 
Constructor Summary
protected Element()
           Default, no-args constructor for implementations to use if needed.
  Element(java.lang.String name)
           This will create a new Element with the supplied (local) name.
  Element(java.lang.String prefix, java.lang.String name)
           This will create a new Element with the supplied namespace prefix and (local) name.
 
Method Summary
 Element addAttribute(Attribute attribute)
           This will add an Attribute to this Element.
 Element addAttribute(java.lang.String name, java.lang.String value)
           This will add an Attribute to this Element.
 Element addChild(Comment comment)
           This will add a Comment as a child of this Element.
 Element addChild(Element element)
           This will add an Element as a child of this Element.
 Element addChild(Entity entity)
           This will add an Entity as a child of this Element.
 Element addChild(java.lang.String s)
           This will add a String as a child of this Element.
 Element addText(java.lang.String text)
           This will add test to the content of this Element.
 Attribute getAttribute(java.lang.String name)
           This will return the Attribute for the specified attribute name on this Element.
 Attribute getAttribute(java.lang.String prefix, java.lang.String name)
           This will return the Attribute for the specified attribute name on this Element.
 java.util.List getAttributes()
           This returns the complete set of Attributes for this Element, in no particular order.
 Element getChild(java.lang.String name)
           This will return a List of all the XML elements nested directly (one level deep) within this Element whose names match the name specified, each in Element form.
 Element getChild(java.lang.String prefix, java.lang.String name)
           This will return the child Elements for the specified element name on this Element.
 java.util.List getChildren()
           This will return a List of all the XML elements nested directly (one level deep) within this Element, each in Element form.
 java.util.List getChildren(java.lang.String name)
           This will return a List of all the XML elements nested directly (one level deep) within this Element whose names match the name specified, each in Element form.
 java.util.List getChildren(java.lang.String prefix, java.lang.String name)
           This will return the children Elements for the specified element name on this Element.
 java.lang.String getContent()
           This will return the actual textual content of this Element.
 java.lang.String getFullName()
           This returns the full name of the Element, in the form [namespacePrefix]:[localName].
 java.util.List getMixedContent()
           This will return the content of the element.
 java.lang.String getName()
           This returns the (local) name of the Element, without any namespace prefix, if one exists.
 java.lang.String getNamespacePrefix()
           This returns the namespace prefix of the Element, if one exists.
 boolean hasMixedContent()
           This will indicate whether the element has mixed content or not.
 void removeAttribute(java.lang.String name)
           This will remove the Attribute with the given name.
 void removeAttribute(java.lang.String namespacePrefix, java.lang.String localName)
           This will remove the Attribute with the given name.
 boolean removeChild(Comment comment)
           This will remove the specified Comment.
 boolean removeChild(Element element)
           This will remove the specified Element.
 boolean removeChild(Entity entity)
           This will remove the specified Entity.
 boolean removeChild(java.lang.String name)
           This will remove the Element with the specified name.
 boolean removeChild(java.lang.String prefix, java.lang.String name)
           This will remove the Element with the specified name.
 boolean removeChildren()
           This removes all children for this Element.
 boolean removeChildren(java.lang.String name)
           This will remove the Element with the specified name.
 boolean removeChildren(java.lang.String prefix, java.lang.String name)
           This will remove the Element with the specified name.
 Element setAttributes(java.util.List attributes)
           This will set all the attributes for this Element.
 Element setChildren(java.util.List children)
           This will set the children of this Element to the Elements within the supplied :ost.
 Element setContent(java.lang.String textContent)
           This will set the textual content of the Element.
 Element setMixedContent(java.util.List mixedContent)
           This will return the content of the element.
 Element setName(java.lang.String name)
           This will set the name of the element.
 Element setName(java.lang.String prefix, java.lang.String name)
           This will set the name of the element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

name

protected java.lang.String name
The local name of the Element

prefix

protected java.lang.String prefix
The namespace prefix of the Element

attributes

protected java.util.List attributes
The attributes of the Element

content

protected java.util.List content
The mixed content of the Element
Constructor Detail

Element

protected Element()

Default, no-args constructor for implementations to use if needed.


Element

public Element(java.lang.String prefix,
               java.lang.String name)

This will create a new Element with the supplied namespace prefix and (local) name.

Parameters:
prefix - String prefix for element.
name - String name of element.

Element

public Element(java.lang.String name)

This will create a new Element with the supplied (local) name. This assumes that no prefix should be issued for the Element, and that it is in the default namespace.

Parameters:
name - String name of element.
Method Detail

getName

public java.lang.String getName()

This returns the (local) name of the Element, without any namespace prefix, if one exists.

Returns:
String - element name.

getNamespacePrefix

public java.lang.String getNamespacePrefix()

This returns the namespace prefix of the Element, if one exists. Otherwise, an empty String is returned.

Returns:
String - namespace prefix.

getFullName

public java.lang.String getFullName()

This returns the full name of the Element, in the form [namespacePrefix]:[localName]. If no namespace prefix exists for the Element, simply the local name is returned.

Returns:
String - full name of element.

setName

public Element setName(java.lang.String name)

This will set the name of the element. If the name specified has a namespace prefix (indicated by a colon), then the prefix is split from the element and handled. If no namespace prefix is supplied, the namespace prefix is empty.

Parameters:
name - String full name of element.
Returns:
Element - this element modified.

setName

public Element setName(java.lang.String prefix,
                       java.lang.String name)

This will set the name of the element. It allows a namespace prefix to be passed in as well as the local name of the element.

Parameters:
prefix - String prefix for name.
name - String local name of element.
Returns:
Element - this element modified.

getContent

public java.lang.String getContent()

This will return the actual textual content of this Element. This will include all text within this single element, including CDATA sections if they exist. If no textual value exists for the Element, an empty String is returned.

Returns:
String - value for this element.

setContent

public Element setContent(java.lang.String textContent)

This will set the textual content of the Element. If this Element will have both textual content and nexted elements, setMixedContent(java.util.List) should be used instead,

Parameters:
textContent - String content for Element.
Returns:
Element - this element modified.

hasMixedContent

public boolean hasMixedContent()

This will indicate whether the element has mixed content or not. Mixed content is when an element contains both textual and element data within it. When this evaluates to true, getMixedContent() should be used for getting element data.

Note:I think there's a better way to do this, maybe store a member variable, but I'm too tired to really think of what it is... (brett).

Returns:
boolean - indicating whether there is mixed content (both textual data and elements).

getMixedContent

public java.util.List getMixedContent()

This will return the content of the element. This should be used when the hasMixedContent() evaluates to true. When there is no mixed content, it returns a List with a single String (when only data is present) or a List with only elements (when only nested elements are present).

Returns:
List - the mixed content of the Element: contains String, Element, Comment, and Entity objects.

setMixedContent

public Element setMixedContent(java.util.List mixedContent)

This will return the content of the element. This should be used when the hasMixedContent() evaluates to true. When there is no mixed content, it returns a List with a single String (when only data is present) or a List with only elements (when only nested elements are present).

Returns:
Element - this element modified.

getChildren

public java.util.List getChildren()

This will return a List of all the XML elements nested directly (one level deep) within this Element, each in Element form. If the Element has no nested elements, an empty list will be returned.

This performs no recursion, so an elements nested two levels deep would have to be obtained with:

 
   List nestedElements = currentElement.getChildren();
   for (int i=0; i<nestedElements.size(); i++) {
     Element oneLevelDeep = (Element)nestedElements.get(i);
     List twoLevelsDeep = oneLevelDeep.getChildren();
     // Do something with these children
   }
 
 

Returns:
List - list of nested Element instances for this element.

setChildren

public Element setChildren(java.util.List children)

This will set the children of this Element to the Elements within the supplied :ost. All existing children of this Element are replaced.

Parameters:
children - List of Elements to add.
Returns:
Element - this element modified.

getChildren

public java.util.List getChildren(java.lang.String name)

This will return a List of all the XML elements nested directly (one level deep) within this Element whose names match the name specified, each in Element form. If the Element has no nested elements that match the requested name, an empty list will be returned.

Either the raw name (XML 1.0: namespace prefix and local name) of the element can be provided (for example, JavaXML:Book), or simply the local name (XML Namespace aware: local name only) of the element (for example, Book), can be provided.

Please see the notes for getChildren() regarding how deep this search will go within element nestings. Only elements directly nested within this Element will be returned.

Parameters:
name - String name of attribute to return.
Returns:
List - all matching child elements.

getChildren

public java.util.List getChildren(java.lang.String prefix,
                                  java.lang.String name)

This will return the children Elements for the specified element name on this Element. If multiple elements exist for the specified name, all are returned.

Please see the notes for getChildren() regarding how deep this search will go within element nestings. Only elements directly nested within this Element will be returned.

Parameters:
prefix - String prefix of elements to find
name - String name of child elements to return.
Returns:
List - the requested elements.

getChild

public Element getChild(java.lang.String name)
                 throws NoSuchElementException

This will return a List of all the XML elements nested directly (one level deep) within this Element whose names match the name specified, each in Element form. If the Element has no nested elements that match the requested name, an empty list will be returned.

Either the raw name (XML 1.0: namespace prefix and local name) of the element can be provided (for example, JavaXML:Book), or simply the local name (XML Namespace aware: local name only) of the element (for example, Book), can be provided.

Please see the notes for getChildren() regarding how deep this search will go within element nestings. Only elements directly nested within this Element will be returned.

Parameters:
name - String name of attribute to return.
Returns:
Element - the first matching child element.
Throws:
NoSuchElementException - - when the requested XML element does not exist within this Element.

getChild

public Element getChild(java.lang.String prefix,
                        java.lang.String name)
                 throws NoSuchElementException

This will return the child Elements for the specified element name on this Element. If multiple elements exist for the specified name, only the first is returned.

Please see the notes for getChildren() regarding how deep this search will go within element nestings. Only elements directly nested within this Element will be returned.

Parameters:
prefix - String prefix of elements to find
name - String name of child elements to return.
Returns:
Element - the first matching child element.
Throws:
NoSuchElementException - - when the requested XML element does not exist within this Element.

addText

public Element addText(java.lang.String text)

This will add test to the content of this Element.

Parameters:
text - String to add as content.
Returns:
Element - this element modified.

addChild

public Element addChild(Element element)

This will add an Element as a child of this Element.

Parameters:
element - Element to add as a child.
Returns:
Element - this element modified.

addChild

public Element addChild(Entity entity)

This will add an Entity as a child of this Element.

Parameters:
entity - Entity to add as a child.
Returns:
Element - this element modified.

addChild

public Element addChild(java.lang.String s)

This will add a String as a child of this Element.

Parameters:
s - String to add as a child.
Returns:
Element - this element modified.

removeChild

public boolean removeChild(Element element)

This will remove the specified Element.

Parameters:
child - Element to delete.
Returns:
boolean - whether deletion occurred.

removeChild

public boolean removeChild(Entity entity)

This will remove the specified Entity.

Parameters:
child - Entity to delete.
Returns:
boolean - whether deletion occurred.

removeChild

public boolean removeChild(java.lang.String name)

This will remove the Element with the specified name. If multiple Elements exist with that name, the first matching child is removed.

Note:Currently, this does not assume that you want the default namespace. I can perform removeChild("foo:bar"), and it does the right thing. But if I have a document with elements <foo:bar> as well as <bar>, this currently removes the first of those when removeChild("bar") is invoked. Do we want to explicitly enforce the default namespace (none) if no prefix is given? (brett)

Parameters:
name - String name of child to delete.
Returns:
boolean - whether deletion occurred.

removeChild

public boolean removeChild(java.lang.String prefix,
                           java.lang.String name)

This will remove the Element with the specified name. If multiple Elements exist with that name, the first matching child is removed.

Parameters:
prefix - String prefix of element to remove.
name - String local name of child to delete.
Returns:
boolean - whether deletion occurred.

removeChildren

public boolean removeChildren(java.lang.String name)

This will remove the Element with the specified name. If multiple Elements exist with that name, all matching children are removed.

Note:Currently, this does not assume that you want the default namespace. I can perform removeChild("foo:bar"), and it does the right thing. But if I have a document with elements <foo:bar> as well as <bar>, this currently removes the first of those when removeChild("bar") is invoked. Do we want to explicitly enforce the default namespace (none) if no prefix is given? (brett)

Parameters:
name - String name of child to delete.
Returns:
boolean - whether deletion occurred.

removeChildren

public boolean removeChildren(java.lang.String prefix,
                              java.lang.String name)

This will remove the Element with the specified name. If multiple Elements exist with that name, the first matching child is removed.

Parameters:
prefix - String prefix of element to remove.
name - String local name of child to delete.
Returns:
boolean - whether deletion occurred.

removeChildren

public boolean removeChildren()

This removes all children for this Element.

Returns:
boolean - whether deletion occurred.

addChild

public Element addChild(Comment comment)

This will add a Comment as a child of this Element.

Parameters:
comment - Comment to add as a child.
Returns:
Element - this element modified.

removeChild

public boolean removeChild(Comment comment)

This will remove the specified Comment.

Parameters:
comment - Comment to delete.
Returns:
boolean - whether deletion occurred.

getAttributes

public java.util.List getAttributes()

This returns the complete set of Attributes for this Element, in no particular order.

Returns:
List - attributes for the element.

getAttribute

public Attribute getAttribute(java.lang.String name)
                       throws NoSuchAttributeException

This will return the Attribute for the specified attribute name on this Element.

Note:Currently, this does not assume that you want the default namespace. I can perform getAttribute("foo:bar"), and it does the right thing. But if I have a document with an element with attributes foo:bar as well as bar, this currently gets the first of those when getAttribute("bar") is invoked. Do we want to explicitly enforce the default namespace (none) if no prefix is given? (brett)

Parameters:
name - String name of attribute to return.
Returns:
Attribute - the requested attribute.
Throws:
NoSuchAttributeException - - when the requested XML attribute does not exist for this Element.

getAttribute

public Attribute getAttribute(java.lang.String prefix,
                              java.lang.String name)
                       throws NoSuchAttributeException

This will return the Attribute for the specified attribute name on this Element.

Parameters:
prefix - String prefix of attribute to return
name - String local name of attribute to return.
Returns:
Attribute - the requested attribute.
Throws:
NoSuchAttributeException - - when the requested XML attribute does not exist for this Element.

setAttributes

public Element setAttributes(java.util.List attributes)

This will set all the attributes for this Element.

Parameters:
attributes - List of attributes to add.
Returns:
Element - this element modified.

addAttribute

public Element addAttribute(Attribute attribute)

This will add an Attribute to this Element.

Parameters:
attribute - Attribute to add.
Returns:
Element - this element modified.

addAttribute

public Element addAttribute(java.lang.String name,
                            java.lang.String value)

This will add an Attribute to this Element.

Parameters:
name - name of the attribute to add.
value - value of the attribute to add.
Returns:
Element - this element modified.

removeAttribute

public void removeAttribute(java.lang.String name)

This will remove the Attribute with the given name.

Note:Currently, this does not assume that you want the default namespace. I can perform removeAttribute("foo:bar"), and it does the right thing. But if I have a document with an element with attributes foo:bar as well as bar, this currently removes the first of those when removeAttribute("bar") is invoked. Do we want to explicitly enforce the default namespace (none) if no prefix is given? (brett)

Parameters:
fullName - String name of attribute to remove.

removeAttribute

public void removeAttribute(java.lang.String namespacePrefix,
                            java.lang.String localName)

This will remove the Attribute with the given name.

Parameters:
namespacePrefix - String prefix of attribute to delete.
localName - String name of attribute to remove.


Copyright © 2000 Brett McLaughlin, Jason Hunter. All Rights Reserved.