com.phloc.commons.microdom

Interface IMicroElement

All Superinterfaces:

ICloneable<IMicroNode>, IHasChildren<IMicroNode>, IHasChildrenSorted<IMicroNode>, IHasParent<IMicroNode>, IMicroNode, IMicroNodeWithChildren, Serializable

All Known Implementing Classes:

MicroElement

public interface IMicroElement
extends IMicroNodeWithChildren

Represents a single element (=tag) of a document.

Author:

Philip Helger

Method Summary

Methods

Modifier and Type	Method and Description
Set<String>	getAllAttributeNames() Get a set of all attribute names.
Map<String,String>	getAllAttributes() Get a map of all attribute names and values.
Collection<String>	getAllAttributeValues() Get a set of all attribute values.
List<IMicroElement>	getAllChildElements() Get a list of all direct child elements.
List<IMicroElement>	getAllChildElements(IHasElementName aElementNameProvider) Get a list of all direct child elements having the specified tag name.
List<IMicroElement>	getAllChildElements(String sTagName) Get a list of all direct child elements having the specified tag name.
List<IMicroElement>	getAllChildElements(String sNamespaceURI, IHasElementName aElementNameProvider) Get a list of all direct child elements having the specified namespace and the specified tag name.
List<IMicroElement>	getAllChildElements(String sNamespaceURI, String sLocalName) Get a list of all direct child elements having the specified namespace and the specified tag name.
List<IMicroElement>	getAllChildElementsRecursive() Recursively get all child elements.
String	getAttribute(String sAttrName) Get the attribute value of the given attribute name.
int	getAttributeCount()
<DSTTYPE> DSTTYPE	getAttributeWithConversion(String sAttrName, Class<DSTTYPE> aDstClass) Get the attribute value of the given attribute name.
int	getChildElementCount()
IMicroElement	getClone()
IMicroElement	getFirstChildElement() Get the first child element of this element.
IMicroElement	getFirstChildElement(IHasElementName aElementNameProvider) Get the first child element with the given tag name.
IMicroElement	getFirstChildElement(String sTagName) Get the first child element with the given tag name.
IMicroElement	getFirstChildElement(String sNamespaceURI, IHasElementName aElementNameProvider) Get the first child element with the given tag name and the given namespace.
IMicroElement	getFirstChildElement(String sNamespaceURI, String sLocalName) Get the first child element with the given tag name and the given namespace.
String	getLocalName() Get the local name of the element.
String	getNamespaceURI() Get the namespace URI of this element
String	getTagName() Get the name of the tag.
boolean	hasAttribute(String sAttrName) Check if this element has an attribute with the specified name.
boolean	hasAttributes()
boolean	hasChildElements() Check if this element has at least one child element.
boolean	hasChildElements(IHasElementName aElementNameProvider) Check if this element has at least one child element with the specified tag name.
boolean	hasChildElements(String sTagName) Check if this element has at least one child element with the specified tag name.
boolean	hasChildElements(String sNamespaceURI, IHasElementName aElementNameProvider) Check if this element has at least one child element with the specified namespace URI and tag name.
boolean	hasChildElements(String sNamespaceURI, String sLocalName) Check if this element has at least one child element with the specified namespace URI and tag name.
boolean	hasNamespaceURI() Check if this element has a specified namespace URI.
boolean	hasNamespaceURI(String sNamespaceURI) Check if this element has the specified namespace URI.
boolean	hasNoNamespaceURI() Check if this element has no namespace URI.
EChange	removeAllAttributes() Remove all attributes from this element
EChange	removeAttribute(String sAttrName) Remove the attribute with the given name.
IMicroElement	setAttribute(String sAttrName, IHasAttributeValue aAttrValueProvider) Set an attribute value of this element.
IMicroElement	setAttribute(String sAttrName, int nAttrValue) Set an attribute value of this element.
IMicroElement	setAttribute(String sAttrName, long nAttrValue) Set an attribute value of this element.
IMicroElement	setAttribute(String sAttrName, String sAttrValue) Set an attribute value of this element.
IMicroElement	setAttributeWithConversion(String sAttrName, Object aAttrValue) Set an attribute value of this element.
EChange	setNamespaceURI(String sNamespaceURI) Set a new namespace URI for this element.

Methods inherited from interface com.phloc.commons.microdom.IMicroNodeWithChildren

getTextContent, getTextContentTrimmed, getTextContentWithConversion

Methods inherited from interface com.phloc.commons.microdom.IMicroNode

appendCDATA, appendCDATA, appendCDATA, appendCDATAWithConversion, appendChild, appendComment, appendComment, appendComment, appendCommentWithConversion, appendContainer, appendElement, appendElement, appendElement, appendElement, appendEntityReference, appendIgnorableWhitespaceText, appendIgnorableWhitespaceText, appendIgnorableWhitespaceText, appendProcessingInstruction, appendText, appendText, appendText, appendTextWithConversion, detachFromParent, getAllChildrenRecursive, getChildren, getFirstChild, getLastChild, getNextSibling, getNodeName, getNodeValue, getParent, getParentElementWithName, getParentElementWithName, getPreviousSibling, getType, hasChildren, hasParent, insertAfter, insertAtIndex, insertBefore, isCDATA, isComment, isContainer, isDocument, isDocumentType, isElement, isEntityReference, isEqualContent, isProcessingInstruction, isText, registerEventTarget, removeAllChildren, removeChild, removeChildAtIndex, replaceChild, unregisterEventTarget

Methods inherited from interface com.phloc.commons.parent.IHasChildrenSorted

getChildAtIndex

Methods inherited from interface com.phloc.commons.parent.IHasChildren

getChildCount

Method Detail

hasAttributes

boolean hasAttributes()

Returns:

true if this element has at least one attribute, false otherwise

getAttributeCount

@Nonnegative
int getAttributeCount()

Returns:

The number of assigned attributes. Always ≥ 0.

hasAttribute

boolean hasAttribute(@Nullable
                   String sAttrName)

Check if this element has an attribute with the specified name.

Parameters:

sAttrName - The attribute name to retrieve the value of.

Returns:

true if such an attribute is present, false otherwise

getAttribute

@Nullable
String getAttribute(@Nullable
                           String sAttrName)

Get the attribute value of the given attribute name. If this element has no such attribute, null is returned.

Parameters:

sAttrName - The attribute name to retrieve the value of.

Returns:

The assigned attribute value or null.

getAttributeWithConversion

@Nullable
<DSTTYPE> DSTTYPE getAttributeWithConversion(@Nullable
                                                    String sAttrName,
                                                    @Nonnull
                                                    Class<DSTTYPE> aDstClass)

Get the attribute value of the given attribute name. If this element has no such attribute, null is returned. The attribute value is converted via the TypeConverter to the desired destination class. If no such attribute is present, null is returned.

Parameters:

sAttrName - The attribute name to retrieve the value of.

aDstClass - The destination class.

Returns:

The assigned attribute value or null.

Throws:

ClassCastException - if the value cannot be converted

getAllAttributes

@Nullable
@ReturnsMutableCopy
Map<String,String> getAllAttributes()

Get a map of all attribute names and values. Is ensured to be not null if hasAttributes() returns true.

Returns:

May be null.

getAllAttributeNames

@Nullable
@ReturnsMutableCopy
Set<String> getAllAttributeNames()

Get a set of all attribute names. Is ensured to be not null if hasAttributes() returns true.

Returns:

May be null.

getAllAttributeValues

@Nullable
@ReturnsMutableCopy
Collection<String> getAllAttributeValues()

Get a set of all attribute values. Is ensured to be not null if hasAttributes() returns true.

Returns:

May be null.

setAttribute

@Nonnull
IMicroElement setAttribute(@Nonnull
                                 String sAttrName,
                                 @Nullable
                                 String sAttrValue)

Set an attribute value of this element.

Parameters:

sAttrName - Name of the attribute. May neither be null nor empty.

sAttrValue - If the value is null the attribute is removed (if present)

Returns:

this

setAttribute

@Nonnull
IMicroElement setAttribute(@Nonnull
                                 String sAttrName,
                                 @Nonnull
                                 IHasAttributeValue aAttrValueProvider)

Set an attribute value of this element.

Parameters:

sAttrName - Name of the attribute. May neither be null nor empty.

aAttrValueProvider - The attribute value provider. May not be null. If the contained attribute value is null the attribute is removed (if present)

Returns:

this

setAttribute

@Nonnull
IMicroElement setAttribute(@Nonnull
                                 String sAttrName,
                                 int nAttrValue)

Set an attribute value of this element. This is a shortcut for setAttribute(name, Integer.toString (nValue)).

Parameters:

sAttrName - Name of the attribute. May neither be null nor empty.

nAttrValue - The new value to be set.

Returns:

this

setAttribute

@Nonnull
IMicroElement setAttribute(@Nonnull
                                 String sAttrName,
                                 long nAttrValue)

Set an attribute value of this element. This is a shortcut for setAttribute(name, Long.toString (nValue)).

Parameters:

sAttrName - Name of the attribute. May neither be null nor empty.

nAttrValue - The new value to be set.

Returns:

this

setAttributeWithConversion

@Nonnull
IMicroElement setAttributeWithConversion(@Nonnull
                                               String sAttrName,
                                               @Nullable
                                               Object aAttrValue)

Set an attribute value of this element. If the type of the value is not String, the TypeConverter is invoked to convert it to a String object.

Parameters:

sAttrName - Name of the attribute. May neither be null nor empty.

aAttrValue - If the value is null the attribute is removed (if present)

Returns:

this

removeAttribute

@Nonnull
EChange removeAttribute(@Nullable
                              String sAttrName)

Remove the attribute with the given name.

Parameters:

sAttrName - The name of the attribute to be removed. May be null.

Returns:

EChange.CHANGED if the attribute was removed, EChange.UNCHANGED if no such attribute exists at this element.

removeAllAttributes

@Nonnull
EChange removeAllAttributes()

Remove all attributes from this element

Returns:

EChange.

getNamespaceURI

@Nullable
String getNamespaceURI()

Get the namespace URI of this element

Returns:

May be null if this element has no namespace URI.

setNamespaceURI

@Nonnull
EChange setNamespaceURI(@Nullable
                              String sNamespaceURI)

Set a new namespace URI for this element.

Parameters:

sNamespaceURI - The namespace URI to be set. May be null or empty to indicate that the namespace should be removed.

Returns:

EChange

hasNamespaceURI

boolean hasNamespaceURI()

Check if this element has a specified namespace URI.

Returns:

true if this element has a specified namespace URI, false otherwise

hasNoNamespaceURI

boolean hasNoNamespaceURI()

Check if this element has no namespace URI.

Returns:

true if this element has no namespace URI, false otherwise

hasNamespaceURI

boolean hasNamespaceURI(@Nullable
                      String sNamespaceURI)

Check if this element has the specified namespace URI.

Parameters:

sNamespaceURI - The namespace URI to check. May not be null.

Returns:

true if this element has the specified namespace URI, false otherwise

getLocalName

@Nullable
String getLocalName()

Get the local name of the element. Is the same name as returned by getTagName() but it is only present, if a namespace URI is present.

Returns:

May be null if no namespace is present.

getTagName

@Nonnull
String getTagName()

Get the name of the tag. It never contains XML schema prefixes or the like. Is the same as getLocalName() if a namespace URI is present.

Returns:

May not be null.

getChildElementCount

@Nonnegative
int getChildElementCount()

Returns:

The number of all direct child elements. Always ≥ 0.

getAllChildElements

@Nonnull
@ReturnsMutableCopy
List<IMicroElement> getAllChildElements()

Get a list of all direct child elements. Text nodes and other other child nodes are not returned with this call. Micro container children are inlined.

Returns:

Never be null.

getAllChildElements

@Nonnull
@ReturnsMutableCopy
List<IMicroElement> getAllChildElements(@Nullable
                                                                 String sTagName)

Get a list of all direct child elements having the specified tag name. Micro container children are inlined.

Parameters:

sTagName - The tag name to check. May be null.

Returns:

Never be null.

getAllChildElements

@Nonnull
@ReturnsMutableCopy
List<IMicroElement> getAllChildElements(@Nullable
                                                                 String sNamespaceURI,
                                                                 @Nullable
                                                                 String sLocalName)

Get a list of all direct child elements having the specified namespace and the specified tag name. Micro container children are inlined.

Parameters:

sNamespaceURI - The namespace URI to check. May be null.

sLocalName - The tag name to check. May be null.

Returns:

Never be null.

getAllChildElements

@Nonnull
@ReturnsMutableCopy
List<IMicroElement> getAllChildElements(@Nonnull
                                                                 IHasElementName aElementNameProvider)

Get a list of all direct child elements having the specified tag name. Micro container children are inlined.

Parameters:

aElementNameProvider - Element name provider. May not be null.

Returns:

Never be null.

getAllChildElements

@Nonnull
@ReturnsMutableCopy
List<IMicroElement> getAllChildElements(@Nullable
                                                                 String sNamespaceURI,
                                                                 @Nonnull
                                                                 IHasElementName aElementNameProvider)

Get a list of all direct child elements having the specified namespace and the specified tag name. Micro container children are inlined.

Parameters:

sNamespaceURI - The namespace URI to check. May be null.

aElementNameProvider - Element name provider. May not be null.

Returns:

Never be null.

getAllChildElementsRecursive

@Nonnull
@ReturnsMutableCopy
List<IMicroElement> getAllChildElementsRecursive()

Recursively get all child elements. Micro container children are inlined.

Returns:

A list containing all recursively contained elements. May not be null but empty.

hasChildElements

boolean hasChildElements()

Check if this element has at least one child element. Micro container children are also checked.

Returns:

true if this element has at least one child element

hasChildElements

boolean hasChildElements(@Nullable
                       String sTagName)

Check if this element has at least one child element with the specified tag name. Micro container children are also checked.

Parameters:

sTagName - The tag name to check. May be null.

Returns:

true if this element has at least one child element with the specified tag name

hasChildElements

boolean hasChildElements(@Nullable
                       String sNamespaceURI,
                       @Nullable
                       String sLocalName)

Check if this element has at least one child element with the specified namespace URI and tag name. Micro container children are also checked.

Parameters:

sNamespaceURI - The namespace URI to check. May be null.

sLocalName - The tag name to check. May be null.

Returns:

true if this element has at least one child element with the specified namespace URI and tag name

hasChildElements

boolean hasChildElements(@Nonnull
                       IHasElementName aElementNameProvider)

Check if this element has at least one child element with the specified tag name. Micro container children are also checked.

Parameters:

aElementNameProvider - Element name provider. May not be null.

Returns:

true if this element has at least one child element with the specified tag name

hasChildElements

boolean hasChildElements(@Nullable
                       String sNamespaceURI,
                       @Nonnull
                       IHasElementName aElementNameProvider)

Check if this element has at least one child element with the specified namespace URI and tag name. Micro container children are also checked.

Parameters:

sNamespaceURI - The namespace URI to check. May be null.

aElementNameProvider - Element name provider. May not be null.

Returns:

true if this element has at least one child element with the specified namespace URI and tag name

getFirstChildElement

@Nullable
IMicroElement getFirstChildElement()

Get the first child element of this element. Micro container children are also checked.

Returns:

The first child element or null if this element has no child element.

getFirstChildElement

@Nullable
IMicroElement getFirstChildElement(@Nullable
                                          String sTagName)

Get the first child element with the given tag name. Micro container children are also checked.

Parameters:

sTagName - The tag name of the element to search. May be null.

Returns:

null if no such child element is present

getFirstChildElement

@Nullable
IMicroElement getFirstChildElement(@Nullable
                                          String sNamespaceURI,
                                          @Nullable
                                          String sLocalName)

Get the first child element with the given tag name and the given namespace. Micro container children are also checked.

Parameters:

sNamespaceURI - The namespace URL to search.

sLocalName - The tag name of the element to search.

Returns:

null if no such child element is present

getFirstChildElement

@Nullable
IMicroElement getFirstChildElement(@Nonnull
                                          IHasElementName aElementNameProvider)

Get the first child element with the given tag name. Micro container children are also checked.

Parameters:

aElementNameProvider - Element name provider. May not be null.

Returns:

null if no such child element is present

getFirstChildElement

@Nullable
IMicroElement getFirstChildElement(@Nullable
                                          String sNamespaceURI,
                                          @Nonnull
                                          IHasElementName aElementNameProvider)

Get the first child element with the given tag name and the given namespace. Micro container children are also checked.

Parameters:

sNamespaceURI - The namespace URL to search.

aElementNameProvider - Element name provider. May not be null.

Returns:

null if no such child element is present

getClone

@Nonnull
IMicroElement getClone()

Specified by:

getClone in interface ICloneable<IMicroNode>

Specified by:

getClone in interface IMicroNodeWithChildren

Returns:

A 100% deep-copy of the implementing class.