com.phloc.commons.microdom

Interface IMicroNode

All Superinterfaces:

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

All Known Subinterfaces:

IMicroCDATA, IMicroComment, IMicroContainer, IMicroDocument, IMicroDocumentType, IMicroElement, IMicroEntityReference, IMicroNodeWithChildren, IMicroProcessingInstruction, IMicroText

All Known Implementing Classes:

AbstractMicroNode, AbstractMicroNodeWithChildren, MicroCDATA, MicroComment, MicroContainer, MicroDocument, MicroDocumentType, MicroElement, MicroEntityReference, MicroProcessingInstruction, MicroText

public interface IMicroNode
extends ICloneable<IMicroNode>, IHasChildrenSorted<IMicroNode>, IHasParent<IMicroNode>, Serializable

This is the base interface for all kind of nodes in the micro document object model.

Author:

Philip Helger

Method Summary

Methods

Modifier and Type	Method and Description
IMicroCDATA	appendCDATA(char[] aChars) Append a CDATA node to this node.
IMicroCDATA	appendCDATA(char[] aChars, int nOfs, int nLen) Append a CDATA node to this node.
IMicroCDATA	appendCDATA(CharSequence sText) Append a CDATA node to this node.
IMicroCDATA	appendCDATAWithConversion(Object aValue) Append a CDATA node to this node.
<NODETYPE extends IMicroNode> NODETYPE	appendChild(NODETYPE aChildNode) Append any child to the node.
IMicroComment	appendComment(char[] aChars) Append a comment node to this node.
IMicroComment	appendComment(char[] aChars, int nOfs, int nLen) Append a comment node to this node.
IMicroComment	appendComment(CharSequence sText) Append a comment node to this node.
IMicroComment	appendCommentWithConversion(Object aValue) Append a comment node to this node.
IMicroContainer	appendContainer() Append a new container to this node
IMicroElement	appendElement(IHasElementName aElementNameProvider) Append an element without namespace to this node.
IMicroElement	appendElement(String sTagName) Append an element without namespace to this node.
IMicroElement	appendElement(String sNamespaceURI, IHasElementName aElementNameProvider) Append an element with namespace to this node.
IMicroElement	appendElement(String sNamespaceURI, String sTagName) Append an element with namespace to this node.
IMicroEntityReference	appendEntityReference(String sName) Append an entity reference to this node.
IMicroText	appendIgnorableWhitespaceText(char[] aChars) Append a text node which is ignorable whitespace content to this node.
IMicroText	appendIgnorableWhitespaceText(char[] aChars, int nOfs, int nLen) Append a text node which is ignorable whitespace content to this node.
IMicroText	appendIgnorableWhitespaceText(CharSequence sText) Append a text node which is ignorable whitespace content to this node.
IMicroProcessingInstruction	appendProcessingInstruction(String sTarget, String sData) Append a processing instruction to this node.
IMicroText	appendText(char[] aChars) Append a text node to this node.
IMicroText	appendText(char[] aChars, int nOfs, int nLen) Append a text node to this node.
IMicroText	appendText(CharSequence sText) Append a text node to this node.
IMicroText	appendTextWithConversion(Object aValue) Append a text node to this node.
IMicroNode	detachFromParent() Detach this node from the parent node so it can be inserted into another node without problems.
List<IMicroNode>	getAllChildrenRecursive() Recursively get all children.
List<IMicroNode>	getChildren() Get a list of all direct child nodes.
IMicroNode	getFirstChild() Get the first child node or null if no child is present
IMicroNode	getLastChild() Get the last child node or null if no child is present
IMicroNode	getNextSibling()
String	getNodeName()
String	getNodeValue()
IMicroNode	getParent() Get the parent object of this object.
IMicroElement	getParentElementWithName(String sTagName)
IMicroElement	getParentElementWithName(String sNamespaceURI, String sTagName)
IMicroNode	getPreviousSibling()
EMicroNodeType	getType()
boolean	hasChildren()
boolean	hasParent()
<NODETYPE extends IMicroNode> NODETYPE	insertAfter(NODETYPE aChildNode, IMicroNode aPredecessor) Insert an existing node after a certain child node of this.
<NODETYPE extends IMicroNode> NODETYPE	insertAtIndex(int nIndex, NODETYPE aChildNode) Insert an existing node as a child at the specified index.
<NODETYPE extends IMicroNode> NODETYPE	insertBefore(NODETYPE aChildNode, IMicroNode aSuccessor) Insert an existing node before a certain child node of this.
boolean	isCDATA()
boolean	isComment()
boolean	isContainer()
boolean	isDocument()
boolean	isDocumentType()
boolean	isElement()
boolean	isEntityReference()
boolean	isEqualContent(IMicroNode aNode) As instances of this class may not implement equals/hashCode we need a way to determine, if 2 nodes are equal by content.
boolean	isProcessingInstruction()
boolean	isText()
EChange	registerEventTarget(EMicroEvent eEventType, IMicroEventTarget aTarget) Register a specific MicroDOM event listener.
EChange	removeAllChildren() Remove all children from this node.
EChange	removeChild(IMicroNode aChild) Remove the passed child.
EChange	removeChildAtIndex(int nIndex) Remove the child not at the specified index.
EChange	replaceChild(IMicroNode aOldChild, IMicroNode aNewChild) Replace the passed old child with the new child.
EChange	unregisterEventTarget(EMicroEvent eEventType, IMicroEventTarget aTarget) Unregister a specific MicroDOM event listener.

Methods inherited from interface com.phloc.commons.ICloneable

getClone

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

getChildAtIndex

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

getChildCount

Method Detail

getNodeName

@Nonnull
@Nonempty
String getNodeName()

Returns:

Just an abstract name that depends on the implementing class.

getNodeValue

String getNodeValue()

Returns:

The value of this node. This depends on the concrete implementation class. It is currently implemented for IMicroText, IMicroComment and IMicroEntityReference.

hasChildren

boolean hasChildren()

Specified by:

hasChildren in interface IHasChildren<IMicroNode>

Returns:

true if at least one child is present, false otherwise

getChildren

@Nullable
List<IMicroNode> getChildren()

Get a list of all direct child nodes.

Specified by:

getChildren in interface IHasChildren<IMicroNode>

Specified by:

getChildren in interface IHasChildrenSorted<IMicroNode>

Returns:

May be null if the node has no children.

getFirstChild

@Nullable
IMicroNode getFirstChild()

Description copied from interface: IHasChildrenSorted

Get the first child node or null if no child is present

Specified by:

getFirstChild in interface IHasChildrenSorted<IMicroNode>

Returns:

The first child node of this node, or null if this node has no children.

getLastChild

@Nullable
IMicroNode getLastChild()

Description copied from interface: IHasChildrenSorted

Get the last child node or null if no child is present

Specified by:

getLastChild in interface IHasChildrenSorted<IMicroNode>

Returns:

The last child node of this node, or null if this node has no children.

getAllChildrenRecursive

@Nullable
List<IMicroNode> getAllChildrenRecursive()

Recursively get all children. Micro container are contained in this list (incl. their children of course)

Returns:

A list containing all recursively contained child elements. May be null if this node has no children.

getPreviousSibling

@Nullable
IMicroNode getPreviousSibling()

Returns:

The previous node on the same level as this node, or null if this node has no preceding siblings.

getNextSibling

@Nullable
IMicroNode getNextSibling()

Returns:

The next node on the same level as this node, or null if this node has no succeeding siblings.

hasParent

boolean hasParent()

Returns:

true if this node has a parent node assigned, false otherwise.

getParent

@Nullable
IMicroNode getParent()

Description copied from interface: IHasParent

Get the parent object of this object.

Specified by:

getParent in interface IHasParent<IMicroNode>

Returns:

May be null.

detachFromParent

@Nonnull
IMicroNode detachFromParent()

Detach this node from the parent node so it can be inserted into another node without problems. Otherwise you would get an IllegalStateException if adding this node again to another parent since each node can only have one parent.

Returns:

this

getParentElementWithName

@Nullable
IMicroElement getParentElementWithName(@Nullable
                                              String sTagName)

getParentElementWithName

@Nullable
IMicroElement getParentElementWithName(@Nullable
                                              String sNamespaceURI,
                                              @Nullable
                                              String sTagName)

appendChild

@Nullable
<NODETYPE extends IMicroNode> NODETYPE appendChild(@Nullable
                                                          NODETYPE aChildNode)
                                        throws MicroException

Append any child to the node.

Type Parameters:

NODETYPE - Parameter type == return type

Parameters:

aChildNode - The child node to append. May be null.

Returns:

The appended node, or null if the parameter was null.

Throws:

MicroException - if this node cannot have children

insertBefore

@Nullable
<NODETYPE extends IMicroNode> NODETYPE insertBefore(@Nullable
                                                           NODETYPE aChildNode,
                                                           @Nonnull
                                                           IMicroNode aSuccessor)
                                         throws MicroException

Insert an existing node before a certain child node of this.

Parameters:

aChildNode - The new child node to be inserted.

aSuccessor - The node before which the new node will be inserted.

Returns:

The newly inserted node

Throws:

MicroException - if this node cannot have children

insertAfter

@Nullable
<NODETYPE extends IMicroNode> NODETYPE insertAfter(@Nullable
                                                          NODETYPE aChildNode,
                                                          @Nonnull
                                                          IMicroNode aPredecessor)
                                        throws MicroException

Insert an existing node after a certain child node of this.

Parameters:

aChildNode - The new child node to be inserted.

aPredecessor - The node after which the new node will be inserted.

Returns:

The newly inserted node

Throws:

MicroException - if this node cannot have children

insertAtIndex

@Nullable
<NODETYPE extends IMicroNode> NODETYPE insertAtIndex(@Nonnegative
                                                            int nIndex,
                                                            @Nullable
                                                            NODETYPE aChildNode)
                                          throws MicroException

Insert an existing node as a child at the specified index.

Parameters:

nIndex - The index to insert. Must be ≥ 0.

aChildNode - The new child node to be inserted.

Returns:

The newly inserted node

Throws:

MicroException - if this node cannot have children

appendText

@Nonnull
IMicroText appendText(@Nullable
                            CharSequence sText)
                      throws MicroException

Append a text node to this node.

Parameters:

sText - text to be added

Returns:

The created text node.

Throws:

MicroException - if this node cannot have children

appendText

@Nonnull
IMicroText appendText(@Nonnull
                            char[] aChars)
                      throws MicroException

Append a text node to this node.

Parameters:

aChars - Characters to append. May not be null

Returns:

The created text node.

Throws:

MicroException - if this node cannot have children

appendText

@Nonnull
IMicroText appendText(@Nonnull
                            char[] aChars,
                            @Nonnegative
                            int nOfs,
                            @Nonnegative
                            int nLen)
                      throws MicroException

Append a text node to this node.

Parameters:

aChars - Characters to append. May not be null

nOfs - Offset into the array where to start copying data. May not be <, 0.

nLen - Number of bytes to take from the array. May not be <, 0.

Returns:

The created text node.

Throws:

MicroException - if this node cannot have children

appendTextWithConversion

@Nonnull
IMicroText appendTextWithConversion(@Nullable
                                          Object aValue)
                                    throws MicroException

Append a text node to this node. If the type of the value is not String, the TypeConverter is invoked to convert it to a String object.

Parameters:

aValue - text to be added

Returns:

The created text node.

Throws:

MicroException - if this node cannot have children

appendIgnorableWhitespaceText

@Nonnull
IMicroText appendIgnorableWhitespaceText(@Nullable
                                               CharSequence sText)
                                         throws MicroException

Append a text node which is ignorable whitespace content to this node.

Parameters:

sText - The whitespace content to be added.

Returns:

The created text node.

Throws:

MicroException - if this node cannot have children

appendIgnorableWhitespaceText

@Nonnull
IMicroText appendIgnorableWhitespaceText(@Nonnull
                                               char[] aChars)
                                         throws MicroException

Append a text node which is ignorable whitespace content to this node.

Parameters:

aChars - Characters to append. May not be null

Returns:

The created text node.

Throws:

MicroException - if this node cannot have children

appendIgnorableWhitespaceText

@Nonnull
IMicroText appendIgnorableWhitespaceText(@Nonnull
                                               char[] aChars,
                                               @Nonnegative
                                               int nOfs,
                                               @Nonnegative
                                               int nLen)
                                         throws MicroException

Append a text node which is ignorable whitespace content to this node.

Parameters:

aChars - Characters to append. May not be null

nOfs - Offset into the array where to start copying data. May not be <, 0.

nLen - Number of bytes to take from the array. May not be <, 0.

Returns:

The created text node.

Throws:

MicroException - if this node cannot have children

appendCDATA

@Nonnull
IMicroCDATA appendCDATA(@Nullable
                              CharSequence sText)
                        throws MicroException

Append a CDATA node to this node.

Parameters:

sText - CDATA text

Returns:

The created CDATA node.

Throws:

MicroException - if this node cannot have children

appendCDATA

@Nonnull
IMicroCDATA appendCDATA(@Nonnull
                              char[] aChars)
                        throws MicroException

Append a CDATA node to this node.

Parameters:

aChars - Characters to append. May not be null

Returns:

The created CDATA node.

Throws:

MicroException - if this node cannot have children

appendCDATA

@Nonnull
IMicroCDATA appendCDATA(@Nonnull
                              char[] aChars,
                              @Nonnegative
                              int nOfs,
                              @Nonnegative
                              int nLen)
                        throws MicroException

Append a CDATA node to this node.

Parameters:

aChars - Characters to append. May not be null

nOfs - Offset into the array where to start copying data. May not be <, 0.

nLen - Number of bytes to take from the array. May not be <, 0.

Returns:

The created CDATA node.

Throws:

MicroException - if this node cannot have children

appendCDATAWithConversion

@Nonnull
IMicroCDATA appendCDATAWithConversion(@Nullable
                                            Object aValue)
                                      throws MicroException

Append a CDATA node to this node. If the type of the value is not String, the TypeConverter is invoked to convert it to a String object.

Parameters:

aValue - CDATA to be added

Returns:

The created CDATA node.

Throws:

MicroException - if this node cannot have children

appendComment

@Nonnull
IMicroComment appendComment(@Nullable
                                  CharSequence sText)
                            throws MicroException

Append a comment node to this node.

Parameters:

sText - comment text

Returns:

The created comment.

Throws:

MicroException - if this node cannot have children

appendComment

@Nonnull
IMicroComment appendComment(@Nonnull
                                  char[] aChars)
                            throws MicroException

Append a comment node to this node.

Parameters:

aChars - Characters to append. May not be null

Returns:

The created comment.

Throws:

MicroException - if this node cannot have children

appendComment

@Nonnull
IMicroComment appendComment(@Nonnull
                                  char[] aChars,
                                  @Nonnegative
                                  int nOfs,
                                  @Nonnegative
                                  int nLen)
                            throws MicroException

Append a comment node to this node.

Parameters:

aChars - Characters to append. May not be null

nOfs - Offset into the array where to start copying data. May not be <, 0.

nLen - Number of bytes to take from the array. May not be <, 0.

Returns:

The created comment.

Throws:

MicroException - if this node cannot have children

appendCommentWithConversion

@Nonnull
IMicroComment appendCommentWithConversion(@Nullable
                                                Object aValue)
                                          throws MicroException

Append a comment node to this node. If the type of the value is not String, the TypeConverter is invoked to convert it to a String object.

Parameters:

aValue - Comment to be added

Returns:

The created comment node.

Throws:

MicroException - if this node cannot have children

appendEntityReference

@Nonnull
IMicroEntityReference appendEntityReference(@Nonnull
                                                  String sName)
                                            throws MicroException

Append an entity reference to this node.

Parameters:

sName - The name of the entity reference.

Returns:

The created entity reference.

Throws:

MicroException - if this node cannot have children

appendElement

@Nonnull
IMicroElement appendElement(@Nonnull@Nonempty
                                  String sTagName)
                            throws MicroException

Append an element without namespace to this node.

Parameters:

sTagName - Element name to be created. May neither be null nor empty.

Returns:

The created element

Throws:

MicroException - if this node cannot have children

appendElement

@Nonnull
IMicroElement appendElement(@Nullable
                                  String sNamespaceURI,
                                  @Nonnull@Nonempty
                                  String sTagName)
                            throws MicroException

Append an element with namespace to this node.

Parameters:

sNamespaceURI - Namespace URI to use. May be null.

sTagName - Element name to be created. May neither be null nor empty.

Returns:

The created element

Throws:

MicroException - if this node cannot have children

appendElement

@Nonnull
IMicroElement appendElement(@Nonnull
                                  IHasElementName aElementNameProvider)
                            throws MicroException

Append an element without namespace to this node.

Parameters:

aElementNameProvider - Element name provider. May not be null.

Returns:

The created element

Throws:

MicroException - if this node cannot have children

appendElement

@Nonnull
IMicroElement appendElement(@Nullable
                                  String sNamespaceURI,
                                  @Nonnull
                                  IHasElementName aElementNameProvider)
                            throws MicroException

Append an element with namespace to this node.

Parameters:

sNamespaceURI - Namespace URI to use. May be null.

aElementNameProvider - Element name provider. May not be null.

Returns:

The created element

Throws:

MicroException - if this node cannot have children

appendProcessingInstruction

@Nonnull
IMicroProcessingInstruction appendProcessingInstruction(@Nonnull@Nonempty
                                                              String sTarget,
                                                              @Nullable
                                                              String sData)
                                                        throws MicroException

Append a processing instruction to this node.

Parameters:

sTarget - The PI target

sData - The PI data

Returns:

The created element

Throws:

MicroException - if this node cannot have children

appendContainer

@Nonnull
IMicroContainer appendContainer()
                                throws MicroException

Append a new container to this node

Returns:

The created container.

Throws:

MicroException - if this node cannot have children

removeChild

@Nonnull
EChange removeChild(@Nonnull
                          IMicroNode aChild)

Remove the passed child.

Parameters:

aChild - The child to be removed. May not be null.

Returns:

EChange.CHANGED if the child was successfully removed, EChange.UNCHANGED otherwise.

removeChildAtIndex

@Nonnull
EChange removeChildAtIndex(@Nonnegative
                                 int nIndex)

Remove the child not at the specified index.

Parameters:

nIndex - The 0-based index of the item to be removed.

Returns:

EChange.CHANGED if the node was successfully removed, EChange.UNCHANGED otherwise.

removeAllChildren

@Nonnull
EChange removeAllChildren()

Remove all children from this node.

Returns:

EChange.CHANGED if at least one child was present, and was successfully removed, EChange.UNCHANGED otherwise.

replaceChild

@Nonnull
EChange replaceChild(@Nonnull
                           IMicroNode aOldChild,
                           @Nonnull
                           IMicroNode aNewChild)

Replace the passed old child with the new child.

Parameters:

aOldChild - The child to be removed. May not be null.

aNewChild - The child to be inserted instead. May not be null.

Returns:

EChange.CHANGED if the child was successfully replaced, EChange.UNCHANGED if old child and new child are identical.

getType

@Nonnull
EMicroNodeType getType()

Returns:

The node type. Never null.

isDocument

boolean isDocument()

Returns:

true if this node can safely be casted to IMicroDocument.

isDocumentType

boolean isDocumentType()

Returns:

true if this node can safely be casted to IMicroDocumentType.

isText

boolean isText()

Returns:

true if this node can safely be casted to IMicroText.

isCDATA

boolean isCDATA()

Returns:

true if this node can safely be casted to IMicroCDATA.

isComment

boolean isComment()

Returns:

true if this node can safely be casted to IMicroComment.

isEntityReference

boolean isEntityReference()

Returns:

true if this node can safely be casted to IMicroEntityReference.

isElement

boolean isElement()

Returns:

true if this node can safely be casted to IMicroElement.

isProcessingInstruction

boolean isProcessingInstruction()

Returns:

true if this node can safely be casted to IMicroProcessingInstruction.

isContainer

boolean isContainer()

Returns:

true if this node can safely be casted to IMicroContainer.

registerEventTarget

@Nonnull
EChange registerEventTarget(@Nonnull
                                  EMicroEvent eEventType,
                                  @Nonnull
                                  IMicroEventTarget aTarget)

Register a specific MicroDOM event listener. One event listener can only be attached once to an event!

Parameters:

eEventType - The event type. May not be null.

aTarget - The event target to be added. May not be null.

Returns:

EChange.CHANGED if the event listener was registered, EChange.UNCHANGED otherwise.

unregisterEventTarget

@Nonnull
EChange unregisterEventTarget(@Nonnull
                                    EMicroEvent eEventType,
                                    @Nonnull
                                    IMicroEventTarget aTarget)

Unregister a specific MicroDOM event listener.

Parameters:

eEventType - The event type. May not be null.

aTarget - The event target to be added. May not be null.

Returns:

EChange.CHANGED if the event listener was unregistered, EChange.UNCHANGED otherwise.

isEqualContent

boolean isEqualContent(@Nullable
                     IMicroNode aNode)

As instances of this class may not implement equals/hashCode we need a way to determine, if 2 nodes are equal by content.

Parameters:

aNode - The node to compare to this.

Returns:

true if the nodes are of the same type and the same content, false otherwise.