All Packages Class Hierarchy This Package Previous Next Index
java.lang.Object | +----org.jdom.Element
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.
{
-
attributes
- The attributes of the
Element
-
content
- The mixed content of the
Element
-
name
- The local name of the
Element
-
namespace
- The
{
-
parent
- Parent element, document, or null if none
This protected constructor is provided in order to support an Element subclass that wants full control over variable initialization.
This will create an
This will create a new
This will create a new
This will create a new Element
in no
{
Element(String, Namespace)
Element
with the supplied (local) name, and define
the {
Element(String, String)
Element
with
the supplied (local) name, and specifies the URI
of the {
Element(String, String, String)
Element
with
the supplied (local) name, and specifies the prefix and URI
of the {
This adds an attribute to this element. Deprecated.
This adds an attribute to this element with the given name and value. Deprecated.
This adds a CDATA section as content to this element.
This adds a comment as content to this element.
This adds element content to this element.
This adds entity content to this element.
This adds a processing instruction as content to this element.
This adds text content to this element.
This will add a namespace declarations to this element.
This returns a deep clone of this element.
This detaches the element from its parent, or does nothing if the element has no parent.
This tests for equality of this Element
to the supplied
Object
, explicitly using the == operator.
This will return any namespace declarations on this element
that exist, excluding the namespace of the element
itself, which can be obtained through
This returns the attribute for this element with the given name
and within no namespace.
This returns the attribute for this element with the given name
and within the given Namespace.
This returns the complete set of attributes for this element, as a
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.
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.
This returns the first child element within this element with the
given local name and belonging to no namespace.
This returns the first child element within this element with the
given local name and belonging to the given namespace.
This returns a
This returns a
This returns a
This convenience method returns the textual content of the named
child element, or returns an empty
This convenience method returns the textual content of the named
child element, or returns null if there's no such child.
This convenience method returns the trimmed textual content of the
named child element, or returns null if there's no such child.
This convenience method returns the trimmed textual content of the
named child element, or returns null if there's no such child.
This returns the full content of the element as a List which
may contain objects of type
This creates a copy of this
This creates a copy of this
This retrieves the owning
This returns the full content of the element as a List which
may contain objects of type
This returns the (local) name of the
This will return this
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).
This returns the namespace prefix
of the
This returns the URI mapped to this
This will return the parent of this
This returns the full name of the
This will return the
This returns the textual content directly held under this
element.
This returns the textual content of this element with all
surrounding whitespace removed and internal whitespace normalized
to a single space.
This returns the textual content of this element with all
surrounding whitespace removed.
This returns the hash code for this
This will indicate whether the element has mixed content or not.
Deprecated.
This returns a
This removes the attribute with the given name and within no
namespace.
This removes the attribute with the given name and within the
given Namespace.
This removes the attribute with the given name and within the
given namespace URI.
Deprecated.
This removes the first child element (one level deep) with the
given local name and belonging to no namespace.
This removes the first child element (one level deep) with the
given local name and belonging to the given namespace.
This removes all child elements.
This removes all child elements (one level deep) with the
given local name and belonging to no namespace.
This removes all child elements (one level deep) with the
given local name and belonging to the given namespace.
This removes the specified
This removes the specified
This removes the specified
This removes the specified
This removes the specified
This will remove a namespace declarations from this element.
This sets an attribute value for this element.
This sets an attribute value for this element.
This sets an attribute value for this element.
This sets all the attributes for this element to be those
in the given
This sets the content of the element to be the List of
This sets the content of the element.
This sets the
This sets the content of the element.
Deprecated.
This sets the (local) name of the
This sets this
This will set the parent of this
This sets the content of the element to be the text given.
This returns a {
getAttribute(String)
getAttribute(String, Namespace)
getAttributes()
List
of Attribute
objects in no particular
order, or an empty list if there are none.
getAttributeValue(String)
getAttributeValue(String, Namespace)
getChild(String)
getChild(String, Namespace)
getChildren()
List
of all the child elements
nested directly (one level deep) within this element, as
Element
objects.
getChildren(String)
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.
getChildren(String, Namespace)
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.
getChildText(String)
String
("")
if the child has no textual content.
getChildText(String, Namespace)
getChildTextTrim(String)
getChildTextTrim(String, Namespace)
getContent()
String
, Element
,
Comment
, ProcessingInstruction
,
CDATA
, and EntityRef
.
getCopy(String)
Element
, with the new
name specified, and in no namespace.
Deprecated.
getCopy(String, Namespace)
Element
, with the new
name specified, and in the specified {
Deprecated.
getDocument()
{
getMixedContent()
String
, Element
,
Comment
, ProcessingInstruction
,
CDATA
, and EntityRef
.
Deprecated.
getName()
Element
, without any
namespace prefix, if one exists.
getNamespace()
Element
's
{
getNamespace(String)
getNamespacePrefix()
Element
, if
one exists.
getNamespaceURI()
Element
's
prefix (or the default namespace if no prefix).
getParent()
Element
.
getQualifiedName()
Element
, in the form
[namespacePrefix]:[localName].
getSerializedForm()
Element
in XML format,
usable in an XML document.
Deprecated.
getText()
getTextNormalize()
getTextTrim()
hasChildren()
hashCode()
Element
.
hasMixedContent()
isRootElement()
boolean
value indicating
whether this Element
is a root
Element
for a JDOM {
removeAttribute(String)
removeAttribute(String, Namespace)
removeAttribute(String, String)
removeChild(String)
removeChild(String, Namespace)
removeChildren()
removeChildren(String)
removeChildren(String, Namespace)
removeContent(CDATA)
CDATA
.
removeContent(Comment)
Comment
.
removeContent(Element)
Element
.
removeContent(EntityRef)
EntityRef
.
removeContent(ProcessingInstruction)
ProcessingInstruction
.
removeNamespaceDeclaration(Namespace)
setAttribute(Attribute)
setAttribute(String, String)
setAttribute(String, String, Namespace)
setAttributes(List)
List
; all existing attributes are removed.
setChildren(List)
Element
objects within the supplied List
.
setContent(List)
setDocument(Document)
{
setMixedContent(List)
setName(String)
Element
.
setNamespace(Namespace)
Element
's {
setParent(Element)
Element
.
setText(String)
toString()
String
representation of the
Element
, suitable for debugging.
protected String name
Element
protected transient Namespace namespace
{@link Namespace}
of the Element
protected transient List additionalNamespaces
{@link Namespace}
declarations on this
element
protected Object parent
protected List attributes
Element
protected List content
Element
protected Element()
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.
public Element(String name, Namespace namespace)
This will create a new Element
with the supplied (local) name, and define
the {@link Namespace}
to be used.
If the provided namespace is null, the element will have
no namespace.
String
name of element.
public Element(String name)
This will create an Element
in no
{@link Namespace}
.
String
name of element.
public Element(String name, String uri)
This will create a new Element
with
the supplied (local) name, and specifies the URI
of the {@link Namespace}
the Element
should be in, resulting it being unprefixed (in the default
namespace).
String
name of element.
String
URI for Namespace
element
should be in.
public Element(String name, String prefix, String uri)
This will create a new Element
with
the supplied (local) name, and specifies the prefix and URI
of the {@link Namespace}
the Element
should be in.
String
name of element.
String
URI for Namespace
element
should be in.
public String getName()
This returns the (local) name of the
Element
, without any
namespace prefix, if one exists.
String
- element name.
public Element setName(String name)
This sets the (local) name of the Element
.
Element
- the element modified.
public Namespace getNamespace()
This will return this Element
's
{@link Namespace}
.
Namespace
- Namespace object for this
Element
public Element setNamespace(Namespace namespace)
This sets this Element
's {@link Namespace}
.
If the provided namespace is null, the element will have no namespace.
Element
- the element modified.
public String getNamespacePrefix()
This returns the namespace prefix
of the Element
, if
one exists. Otherwise, an empty
String
is returned.
String
- namespace prefix.
public String getNamespaceURI()
This returns the URI mapped to this Element
's
prefix (or the default namespace if no prefix). If no
mapping is found, an empty String
is returned.
String
- namespace URI for this
Element
.
public Namespace getNamespace(String prefix)
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.
Namespace
- namespace in scope for the given
prefix on this Element
, or null if none.
public String getQualifiedName()
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.
String
- full name of element.
public void addNamespaceDeclaration(Namespace additionalNamespace)
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.
Namespace
to add.
public void removeNamespaceDeclaration(Namespace additionalNamespace)
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.
Namespace
to remove.
public List getAdditionalNamespaces()
This will return any namespace declarations on this element
that exist, excluding the namespace of the element
itself, which can be obtained through
{@link #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.
public Element getParent()
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 {@link #isRootElement}
to determine this.
Element
.
protected Element setParent(Element parent)
This will set the parent of this Element
.
The caller is responsible for handling pre-existing parentage.
Element
to be new parent.
Element
- this Element
modified.
public Element detach()
This detaches the element from its parent, or does nothing if the element has no parent.
Element
- this Element
modified.
public boolean isRootElement()
This returns a boolean
value indicating
whether this Element
is a root
Element
for a JDOM {@link Document}
.
This should be used in tandem with
{@link #getParent}
to determine
if an Element
has no "attachments" to
parents.
boolean
- whether this is a root element.
protected Element setDocument(Document document)
This sets the {@link Document}
parent of this element
and makes it the root element. The caller is responsible for
ensuring the element doesn't have a pre-existing parent.
Document
parent
Document
this Element
modified
public Document getDocument()
This retrieves the owning {@link Document}
for
this Element, or null if not a currently a member of a
{@link Document}
.
Document
owning this Element, or null.
public String getText()
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 String 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.
public String getTextTrim()
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.
public String getTextNormalize()
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.
public String getChildText(String name)
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.
public String getChildTextTrim(String name)
This convenience method returns the trimmed textual content of the
named child element, or returns null if there's no such child.
See {@link #getTextTrim()}
for details of text trimming.
public String getChildText(String name, Namespace ns)
This convenience method returns the textual content of the named child element, or returns null if there's no such child.
public String getChildTextTrim(String name, Namespace ns)
This convenience method returns the trimmed textual content of the
named child element, or returns null if there's no such child.
See {@link #getTextTrim()}
for
details of text trimming.
public Element setText(String text)
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 {@link #setContent}
instead.
Setting a null text value is equivalent to setting an empty string
value.
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
,
{@link #getMixedContent}
should be used for getting
element data.
boolean
- indicating whether there
is mixed content (both textual data and elements).
public List getContent()
This returns the full content of the element as a List which
may contain objects of type String
, 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.
List
containing the mixed content of the
element: may contain String
,
{@link Element}
, {@link Comment}
,
{@link ProcessingInstruction}
,
{@link CDATA}
, and
{@link EntityRef}
objects.
public Element setContent(List newContent)
This sets the content of the element. The passed in List should
contain only objects of type String
, Element
,
Comment
, ProcessingInstruction
,
CDATA
, and EntityRef
. Passing a null or
empty List clears the existing content. In event of an exception
the original content will be unchanged and the items in the added
content will be unaltered.
public boolean hasChildren()
public List getChildren()
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.
This performs no recursion, so elements nested two levels deep would have to be obtained with:
Iterator itr = currentElement.getChildren().iterator();
while (itr.hasNext()) {
Element oneLevelDeep = (Element)nestedElements.next();
List twoLevelsDeep = oneLevelDeep.getChildren();
// Do something with these children
}
Element
objects for this element
public Element setChildren(List children)
This sets the content of the element to be the List of
Element
objects within the supplied List
.
All existing element and non-element content of the element is removed.
In event of an exception the children may be partially added.
List
of Element
objects to add
public List getChildren(String name)
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 {@link #getChildren}
for a code example.
public List getChildren(String name, Namespace ns)
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 {@link #getChildren}
for a code example.
Namespace
to search within
public Element getChild(String name, Namespace ns)
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.
Namespace
to search within
public Element getChild(String name)
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.
public Element addContent(String text)
This adds text content to this element. It does not replace the
existing content as does setText()
.
String
to add
public Element addContent(Element element)
This adds element content to this element.
Element
to add
public Element addContent(ProcessingInstruction pi)
This adds a processing instruction as content to this element.
ProcessingInstruction
to add
pi
, already has a parent.
public Element addContent(EntityRef entity)
This adds entity content to this element.
EntityRef
to add
public Element addContent(CDATA cdata)
This adds a CDATA section as content to this element.
CDATA
to add
public Element addContent(Comment comment)
This adds a comment as content to this element.
Comment
to add
public boolean removeChild(String name)
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.
public boolean removeChild(String name, Namespace ns)
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.
Namespace
to search within
public boolean removeChildren(String name)
This removes all child elements (one level deep) with the given local name and belonging to no namespace. Returns true if any were removed.
public boolean removeChildren(String name, Namespace ns)
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.
Namespace
to search within
public boolean removeChildren()
This removes all child elements. Returns true if any were removed.
public List getAttributes()
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.
public Attribute getAttribute(String name)
This returns the attribute for this element with the given name and within no namespace.
public Attribute getAttribute(String name, Namespace ns)
This returns the attribute for this element with the given name and within the given Namespace.
Namespace
to search within
public String getAttributeValue(String name)
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.
public String getAttributeValue(String name, Namespace ns)
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.
Namespace
to search within
public Element setAttributes(List attributes)
This sets all the attributes for this element to be those
in the given List
; all existing attributes are removed.
List
of attributes to set
public Element setAttribute(String name, String value)
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
public Element setAttribute(String name, String value, Namespace ns)
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
public Element setAttribute(Attribute attribute)
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
Attribute
to set
public Element addAttribute(String name, String value)
This adds an attribute to this element with the given name and value. To add attributes in namespaces using addAttribute(Attribute).
public boolean removeAttribute(String name, String uri)
This removes the attribute with the given name and within the given namespace URI.
public boolean removeAttribute(String name)
This removes the attribute with the given name and within no namespace. If no such attribute exists, this method does nothing.
public boolean removeAttribute(String name, Namespace ns)
This removes the attribute with the given name and within the given Namespace. If no such attribute exists, this method does nothing.
public String toString()
This returns a String
representation of the
Element
, suitable for debugging. If the XML
representation of the Element
is desired,
{@link org.jdom.output.XMLOutputter#outputString(Element)}
should be used.
String
- information about the
Element
public final boolean equals(Object ob)
This tests for equality of this Element
to the supplied
Object
, explicitly using the == operator.
Object
to compare to
public final int hashCode()
This returns the hash code for this Element
.
public Object clone()
This returns a deep clone of this element. The new element is detached from its parent, and getParent() on the clone will return null.
public boolean removeContent(Element element)
This removes the specified Element
.
If the specified Element
is not a child of
this Element
, this method does nothing.
Element
to delete
public boolean removeContent(ProcessingInstruction pi)
This removes the specified ProcessingInstruction
.
If the specified ProcessingInstruction
is not a child of
this Element
, this method does nothing.
ProcessingInstruction
to delete
public boolean removeContent(Comment comment)
This removes the specified Comment
.
If the specified Comment
is not a child of
this Element
, this method does nothing.
Comment
to delete
public boolean removeContent(CDATA cdata)
This removes the specified CDATA
.
If the specified CDATA
is not a child of
this Element
, this method does nothing.
CDATA
to delete
public boolean removeContent(EntityRef entity)
This removes the specified EntityRef
.
If the specified EntityRef
is not a child of
this Element
, this method does nothing.
EntityRef
to delete
public Element getCopy(String name, Namespace ns)
This creates a copy of this Element
, with the new
name specified, and in the specified {@link Namespace}
.
String
name of new Element
copy.
Namespace
to put copy in.
Element
copy of this Element
.
public Element getCopy(String name)
This creates a copy of this Element
, with the new
name specified, and in no namespace.
String
name of new Element
copy.
public Element addAttribute(Attribute attribute)
This adds an attribute to this element. Any existing attribute with the same name and namespace URI is removed. (TODO: Code the replacement logic.)
Attribute
to add
public final String getSerializedForm()
This will return the Element
in XML format,
usable in an XML document.
String
- the serialized form of the
Element
.
public List getMixedContent()
This returns the full content of the element as a List which
may contain objects of type String
, Element
,
Comment
, ProcessingInstruction
,
CDATA
, and EntityRef
.
When there is technically no mixed content and
all contents are of the same type, then all objects returned in the
List will be of the same type. 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.
List
containing the mixed content of the
element: may contain String
,
{@link Element}
, {@link Comment}
,
{@link ProcessingInstruction}
,
{@link CDATA}
, and
{@link EntityRef}
objects.
public Element setMixedContent(List mixedContent)
This sets the content of the element. The passed in List should
contain only objects of type String
, Element
,
Comment
, ProcessingInstruction
,
CDATA
, and EntityRef
. Passing a null or
empty List clears the existing content. In event of an exception
the original content will be unchanged and the items in the added
content will be unaltered.
All Packages Class Hierarchy This Package Previous Next Index