Element
defines behavior for an XML element, modeled in Java. Methods allow the user to obtain the value of the element's textual content, obtain its attributes, and get its children.
org::jdom::Element::Element | ( | ) | [inline, protected] |
This protected constructor is provided in order to support an Element subclass that wants full control over variable initialization. It intentionally leaves all instance variables null, allowing a lightweight subclass implementation. The subclass is responsible for ensuring all the get and set methods on Element behave as documented.
When implementing an Element
subclass which doesn't require full control over variable initialization, be aware that simply calling super() (or letting the compiler add the implicit super() call) will not initialize the instance variables which will cause many of the methods to throw a NullPointerException
. Therefore, the constructor for these subclasses should call one of the public constructors so variable initialization is handled automatically.
org::jdom::Element::Element | ( | String | name, | |
Namespace | namespace | |||
) | [inline] |
This will create a new Element
with the supplied (local) name, and define the Namespace
to be used. If the provided namespace is null, the element will have no namespace.
name | String name of element. | |
namespace | Namespace to put element in. |
IllegalNameException | if the given name is illegal as an element name. |
org::jdom::Element::Element | ( | String | name | ) | [inline] |
This will create an Element
in no Namespace
.
name | String name of element. |
IllegalNameException | if the given name is illegal as an element name. |
org::jdom::Element::Element | ( | String | name, | |
String | uri | |||
) | [inline] |
This will create a new Element
with the supplied (local) name, and specifies the URI of the Namespace
the Element
should be in, resulting it being unprefixed (in the default namespace).
name | String name of element. | |
uri | String URI for Namespace element should be in. |
IllegalNameException | if the given name is illegal as an element name or the given URI is illegal as a namespace URI |
org::jdom::Element::Element | ( | String | name, | |
String | prefix, | |||
String | uri | |||
) | [inline] |
This will create a new Element
with the supplied (local) name, and specifies the prefix and URI of the Namespace
the Element
should be in.
name | String name of element. | |
uri | String URI for Namespace element should be in. |
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 |
String org::jdom::Element::getName | ( | ) | [inline] |
This returns the (local) name of the Element
, without any namespace prefix, if one exists.
String
- element name. Element org::jdom::Element::setName | ( | String | name | ) | [inline] |
This sets the (local) name of the Element
.
Element
- the element modified. IllegalNameException | if the given name is illegal as an Element name. |
Namespace org::jdom::Element::getNamespace | ( | ) | [inline] |
String org::jdom::Element::getNamespacePrefix | ( | ) | [inline] |
This returns the namespace prefix of the Element
, if one exists. Otherwise, an empty String
is returned.
String
- namespace prefix. String org::jdom::Element::getNamespaceURI | ( | ) | [inline] |
Namespace org::jdom::Element::getNamespace | ( | String | prefix | ) | [inline] |
This returns the Namespace in scope on this element for the given prefix (this involves searching up the tree, so the results depend on the current location of the element). It returns null if there is no Namespace in scope with the given prefix at this point in the document.
prefix | namespace prefix to look up |
String org::jdom::Element::getQualifiedName | ( | ) | [inline] |
void org::jdom::Element::addNamespaceDeclaration | ( | Namespace | additional | ) | [inline] |
This will add a namespace declarations to this element. This should not be used to add the declaration for this element itself; that should be assigned in the construction of the element. Instead, this is for adding namespace declarations on the element not relating directly to itself.
additional | Namespace to add. |
IllegalAddException | if the namespace prefix collides with another namespace prefix on the element. |
void org::jdom::Element::removeNamespaceDeclaration | ( | Namespace | additionalNamespace | ) | [inline] |
This will remove a namespace declarations from this element. This should not be used to remove the declaration for this element itself; that should be handled in the construction of the element. Instead, this is for removing namespace declarations on the element not relating directly to itself. If the declaration is not present, this method does nothing.
additionalNamespace | Namespace to remove. |
List org::jdom::Element::getAdditionalNamespaces | ( | ) | [inline] |
This will return any namespace declarations on this element that exist, excluding the namespace of the element itself, which can be obtained through getNamespace()
. If there are no additional declarations, this returns an empty list. Note, the returned list is not live, for performance reasons.
List
- the additional namespace declarations. Element org::jdom::Element::getParent | ( | ) | [inline] |
This will return the parent of this Element
. If there is no parent, then this returns null
. Also note that on its own, this is not 100% sufficient to see if the Element
is not in use - this should be used in tandem with isRootElement
to determine this.
Element
. Element org::jdom::Element::detach | ( | ) | [inline] |
boolean org::jdom::Element::isRootElement | ( | ) | [inline] |
Document org::jdom::Element::getDocument | ( | ) | [inline] |
String org::jdom::Element::getText | ( | ) | [inline] |
This returns the textual content directly held under this element. This will include all text within this single element, including whitespace and CDATA sections if they exist. It's essentially the concatenation of all Text
and CDATA
nodes returned by getContent()
. The call does not recurse into child elements. If no textual value exists for the element, an empty String
("") is returned.
String org::jdom::Element::getTextTrim | ( | ) | [inline] |
This returns the textual content of this element with all surrounding whitespace removed. If no textual value exists for the element, or if only whitespace exists, the empty string is returned.
String org::jdom::Element::getTextNormalize | ( | ) | [inline] |
This returns the textual content of this element with all surrounding whitespace removed and internal whitespace normalized to a single space. If no textual value exists for the element, or if only whitespace exists, the empty string is returned.
String org::jdom::Element::getChildText | ( | String | name | ) | [inline] |
This convenience method returns the textual content of the named child element, or returns an empty String
("") if the child has no textual content. However, if the child does not exist, null
is returned.
name | the name of the child |
String org::jdom::Element::getChildTextTrim | ( | String | name | ) | [inline] |
This convenience method returns the trimmed textual content of the named child element, or returns null if there's no such child. See getTextTrim()
for details of text trimming.
name | the name of the child |
String org::jdom::Element::getChildTextNormalize | ( | String | name | ) | [inline] |
This convenience method returns the normalized textual content of the named child element, or returns null if there's no such child. See getTextNormalize()
for details of text normalizing.
name | the name of the child |
String org::jdom::Element::getChildText | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This convenience method returns the textual content of the named child element, or returns null if there's no such child.
name | the name of the child | |
ns | the namespace of the child |
String org::jdom::Element::getChildTextTrim | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This convenience method returns the trimmed textual content of the named child element, or returns null if there's no such child. See getTextTrim()
for details of text trimming.
name | the name of the child | |
ns | the namespace of the child |
String org::jdom::Element::getChildTextNormalize | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This convenience method returns the normalized textual content of the named child element, or returns null if there's no such child. See getTextNormalize()
for details of text normalizing.
name | the name of the child | |
ns | the namespace of the child |
Element org::jdom::Element::setText | ( | String | text | ) | [inline] |
This sets the content of the element to be the text given. All existing text content and non-text context is removed. If this element should have both textual content and nested elements, use setContent
instead. Setting a null text value is equivalent to setting an empty string value.
text | new content for the element |
IllegalDataException | if text contains an illegal character such as a vertical tab (as determined by org.jdom.Verifier#checkCharacterData) |
List org::jdom::Element::getContent | ( | ) | [inline] |
This returns the full content of the element as a List which may contain objects of type Text
, Element
, Comment
, ProcessingInstruction
, CDATA
, and EntityRef
. The List returned is "live" in document order and modifications to it affect the element's actual contents. Whitespace content is returned in its entirety.
Sequential traversal through the List is best done with an Iterator since the underlying implement of List.size() may require walking the entire list.
List org::jdom::Element::getContent | ( | Filter | filter | ) | [inline] |
Element org::jdom::Element::setContent | ( | List | newContent | ) | [inline] |
This sets the content of the element. The supplied List should contain only objects of type Element
, Text
, CDATA
, Comment
, ProcessingInstruction
, and EntityRef
.
When all objects in the supplied List are legal and before the new content is added, all objects in the old content will have their parentage set to null (no parent) and the old content list will be cleared. This has the effect that any active list (previously obtained with a call to getContent or getChildren) will also change to reflect the new content. In addition, all objects in the supplied List will have their parentage set to this element, but the List itself will not be "live" and further removals and additions will have no effect on this elements content. If the user wants to continue working with a "live" list, then a call to setContent should be followed by a call to getContent or getChildren to obtain a "live" version of the content.
Passing a null or empty List clears the existing content.
In event of an exception the original content will be unchanged and the objects in the supplied content will be unaltered.
newContent | List of content to set |
IllegalAddException | if the List contains objects of illegal types. |
List org::jdom::Element::getChildren | ( | ) | [inline] |
This returns a List
of all the child elements nested directly (one level deep) within this element, as Element
objects. If this target element has no nested elements, an empty List is returned. The returned list is "live" in document order and changes to it affect the element's actual contents.
Sequential traversal through the List is best done with a Iterator since the underlying implement of List.size() may not be the most efficient.
No recursion is performed, so elements nested two levels deep would have to be obtained with:
Iterator itr = (currentElement.getChildren()).iterator();
while(itr.hasNext()) {
Element oneLevelDeep = (Element)itr.next();
List twoLevelsDeep = oneLevelDeep.getChildren();
// Do something with these children
}
Element
objects for this element List org::jdom::Element::getChildren | ( | String | name | ) | [inline] |
This returns a List
of all the child elements nested directly (one level deep) within this element with the given local name and belonging to no namespace, returned as Element
objects. If this target element has no nested elements with the given name outside a namespace, an empty List is returned. The returned list is "live" in document order and changes to it affect the element's actual contents.
Please see the notes for getChildren
for a code example.
name | local name for the children to match |
List org::jdom::Element::getChildren | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This returns a List
of all the child elements nested directly (one level deep) within this element with the given local name and belonging to the given Namespace, returned as Element
objects. If this target element has no nested elements with the given name in the given Namespace, an empty List is returned. The returned list is "live" in document order and changes to it affect the element's actual contents.
Please see the notes for getChildren
for a code example.
name | local name for the children to match | |
ns | Namespace to search within |
This returns the first child element within this element with the given local name and belonging to the given namespace. If no elements exist for the specified name and namespace, null is returned.
name | local name of child element to match | |
ns | Namespace to search within |
Element org::jdom::Element::getChild | ( | String | name | ) | [inline] |
This returns the first child element within this element with the given local name and belonging to no namespace. If no elements exist for the specified name and namespace, null is returned.
name | local name of child element to match |
Element org::jdom::Element::addContent | ( | String | str | ) | [inline] |
This adds text content to this element. It does not replace the existing content as does setText()
.
str | String to add |
IllegalDataException | if str contains an illegal character such as a vertical tab (as determined by org.jdom.Verifier#checkCharacterData) |
This adds text content to this element. It does not replace the existing content as does setText()
.
text | Text to add |
IllegalAddException | if the Text object you're attempting to add already has a parent element. |
This adds element content to this element.
element | Element to add |
IllegalAddException | if the element you're attempting to add already has a parent element, or if you're attempting to add it as a descendent of itself (which would result in a recursive element definition!). |
Element org::jdom::Element::addContent | ( | ProcessingInstruction | pi | ) | [inline] |
This adds a processing instruction as content to this element.
pi | ProcessingInstruction to add |
IllegalAddException | if the given processing instruction, pi , already has a parent. |
This adds entity content to this element.
entity | EntityRef to add |
IllegalAddException | if the given EntityRef already has a parent. |
This adds a comment as content to this element.
comment | Comment to add |
IllegalAddException | if the given Comment already has a parent. |
boolean org::jdom::Element::isAncestor | ( | Element | element | ) | [inline] |
Determines if this element is the ancestor of another element.
element | Element to check against |
true
if this element is the ancestor of the supplied element boolean org::jdom::Element::removeChild | ( | String | name | ) | [inline] |
This removes the first child element (one level deep) with the given local name and belonging to no namespace. Returns true if a child was removed.
name | the name of child elements to remove |
boolean org::jdom::Element::removeChild | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This removes the first child element (one level deep) with the given local name and belonging to the given namespace. Returns true if a child was removed.
name | the name of child element to remove | |
ns | Namespace to search within |
boolean org::jdom::Element::removeChildren | ( | String | name | ) | [inline] |
This removes all child elements (one level deep) with the given local name and belonging to no namespace. Returns true if any were removed.
name | the name of child elements to remove |
boolean org::jdom::Element::removeChildren | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This removes all child elements (one level deep) with the given local name and belonging to the given namespace. Returns true if any were removed.
name | the name of child elements to remove | |
ns | Namespace to search within |
List org::jdom::Element::getAttributes | ( | ) | [inline] |
This returns the complete set of attributes for this element, as a List
of Attribute
objects in no particular order, or an empty list if there are none. The returned list is "live" and changes to it affect the element's actual attributes.
Attribute org::jdom::Element::getAttribute | ( | String | name | ) | [inline] |
This returns the attribute for this element with the given name and within no namespace, or null if no such attribute exists.
name | name of the attribute to return |
String org::jdom::Element::getAttributeValue | ( | String | name | ) | [inline] |
This returns the attribute value for the attribute with the given name and within no namespace, null if there is no such attribute, and the empty string if the attribute value is empty.
name | name of the attribute whose value to be returned |
String org::jdom::Element::getAttributeValue | ( | String | name, | |
Namespace | ns, | |||
String | def | |||
) | [inline] |
This returns the attribute value for the attribute with the given name and within the given Namespace, or the passed-in default if there is no such attribute.
name | name of the attribute whose valud is to be returned | |
ns | Namespace to search within | |
def | a default value to return if the attribute does not exist |
String org::jdom::Element::getAttributeValue | ( | String | name, | |
String | def | |||
) | [inline] |
This returns the attribute value for the attribute with the given name and within no namespace, or the passed-in default if there is no such attribute.
name | name of the attribute whose value to be returned | |
def | a default value to return if the attribute does not exist |
String org::jdom::Element::getAttributeValue | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This returns the attribute value for the attribute with the given name and within the given Namespace, null if there is no such attribute, and the empty string if the attribute value is empty.
name | name of the attribute whose valud is to be returned | |
ns | Namespace to search within |
Element org::jdom::Element::setAttributes | ( | List | newAttributes | ) | [inline] |
This sets the attributes of the element. The supplied List should contain only objects of type Attribute
.
When all objects in the supplied List are legal and before the new attributes are added, all old attributes will have their parentage set to null (no parent) and the old attribute list will be cleared. This has the effect that any active attribute list (previously obtained with a call to getAttributes) will also change to reflect the new attributes. In addition, all attributes in the supplied List will have their parentage set to this element, but the List itself will not be "live" and further removals and additions will have no effect on this elements attributes. If the user wants to continue working with a "live" attribute list, then a call to setAttributes should be followed by a call to getAttributes to obtain a "live" version of the attributes.
Passing a null or empty List clears the existing attributes.
In cases where the List contains duplicate attributes, only the last one will be retained. This has the same effect as calling setAttribute(Attribute) sequentially.
In event of an exception the original attributes will be unchanged and the attributes in the supplied attributes will be unaltered.
newAttributes | List of attributes to set |
IllegalAddException | if the List contains objects that are not instances of Attribute , or if any of the Attribute objects have conflicting namespace prefixes. |
Element org::jdom::Element::setAttribute | ( | String | name, | |
String | value | |||
) | [inline] |
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
name | name of the attribute to set | |
value | value of the attribute to set |
IllegalNameException | if the given name is illegal as an attribute name. | |
IllegalDataException | if the given attribute value is illegal character data (as determined by org.jdom.Verifier#checkCharacterData). |
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
name | name of the attribute to set | |
value | value of the attribute to set | |
ns | namespace of the attribute to set |
IllegalNameException | if the given name is illegal as an attribute name, or if the namespace is an unprefixed default namespace | |
IllegalDataException | if the given attribute value is illegal character data (as determined by org.jdom.Verifier#checkCharacterData). | |
IllegalAddException | if the attribute namespace prefix collides with another namespace prefix on the element. |
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
attribute | Attribute to set |
IllegalAddException | if the attribute being added already has a parent or if the attribute namespace prefix collides with another namespace prefix on the element. |
boolean org::jdom::Element::removeAttribute | ( | String | name | ) | [inline] |
This removes the attribute with the given name and within no namespace. If no such attribute exists, this method does nothing.
name | name of attribute to remove |
boolean org::jdom::Element::removeAttribute | ( | String | name, | |
Namespace | ns | |||
) | [inline] |
This removes the attribute with the given name and within the given Namespace. If no such attribute exists, this method does nothing.
name | name of attribute to remove | |
ns | namespace URI of attribute to remove |
boolean org::jdom::Element::removeAttribute | ( | Attribute | attribute | ) | [inline] |
This removes the supplied Attribute should it exist.
attribute | Reference to the attribute to be removed. |
boolean org::jdom::Element::removeContent | ( | Element | element | ) | [inline] |
boolean org::jdom::Element::removeContent | ( | ProcessingInstruction | pi | ) | [inline] |
This removes the specified ProcessingInstruction
. If the specified ProcessingInstruction
is not a child of this Element
, this method does nothing.
pi | ProcessingInstruction to delete |
boolean org::jdom::Element::removeContent | ( | Comment | comment | ) | [inline] |
boolean org::jdom::Element::removeContent | ( | Text | text | ) | [inline] |
boolean org::jdom::Element::removeContent | ( | EntityRef | entity | ) | [inline] |
String org::jdom::Element::toString | ( | ) | [inline] |
This returns a String
representation of the Element
, suitable for debugging. If the XML representation of the Element
is desired, org.jdom.output.XMLOutputter#outputString(Element) should be used.
String
- information about the Element
final boolean org::jdom::Element::equals | ( | Object | ob | ) | [inline] |
This tests for equality of this Element
to the supplied Object
, explicitly using the == operator.
ob | Object to compare to |
final int org::jdom::Element::hashCode | ( | ) | [inline] |
Object org::jdom::Element::clone | ( | ) | [inline] |
This returns a deep clone of this element. The new element is detached from its parent, and getParent() on the clone will return null.
boolean org::jdom::Element::removeChildren | ( | ) | [inline] |
This removes all child elements. Returns true if any were removed.
clear()
on the list returned by getChildren()
or by getContent()
boolean org::jdom::Element::hasChildren | ( | ) | [inline] |
Test whether this element has a child element. This method can be used before a call to getContent, which always creates a "live" list, to improve performance.
true
if this element has at least one child element Element org::jdom::Element::setChildren | ( | List | children | ) | [inline] |
This sets the content of the element the same as setContent, except only Element
objects are allowed in the supplied list.
children | List of Element objects to add |
String org::jdom::Element::name [protected] |
The local name of the Element
transient List org::jdom::Element::additionalNamespaces [protected] |
Additional Namespace
declarations on this element
Object org::jdom::Element::parent [protected] |
Parent element, document, or null if none
AttributeList org::jdom::Element::attributes = new AttributeList(this) [protected] |
The attributes of the Element
.
ContentList org::jdom::Element::content = new ContentList(this) [protected] |
The mixed content of the Element
.