Package com.aquima.interactions.foundation.xml.parsing

Class XmlNode

java.lang.Object
com.aquima.interactions.foundation.xml.parsing.XmlNode
All Implemented Interfaces:
IXmlNode
public class XmlNode extends Object implements IXmlNode
Simple XMLNode used to read elements from the DOM Parser. The XMLNode is a recursive (hierarchical) structure.

XMLNode is a wrapper around the standard org.w3c.dom.Node interface.

This cannot be used to create new nodes for use with the XMLDOMGenerator, use XMLNewElement for that.

Since:
5.0
Author:
IdJ

  • Constructor Details

    • XmlNode

      public XmlNode(Document doc)
      Create from a DOM Document, represents root element.
      Parameters:
      doc - the parsed XML document node

    • XmlNode

      public XmlNode(Document doc, boolean trimvalues)
      Create from a DOM Document, represents root element.
      Parameters:
      doc - the parsed XML document node
      trimvalues - true to trim all whitespace from element and attribute values, false to not trim it (default).
      Throws:
      XmlParseException

    • XmlNode

      public XmlNode(Node node)
      Create from a DOM Node, represents root element.
      Parameters:
      node - The DOM node of the root element.

    • XmlNode

      public XmlNode(Node node, boolean trimvalues)
      Create from a DOM Node, represents root element. With or without element and attribute value trimming.
      Parameters:
      node - The DOM node of the root element.
      trimvalues - Boolean indicating if white-spaces of values should be trimmed.

  • Method Details

    • createElement

      protected static IXmlNode createElement(Document xmldoc, String name, String stringValue)
      Create a new XMLNode (containing a new w3c DOM Node), optionally with a text value.
      Parameters:
      xmldoc - DOM Document where the node will be used in.
      name - tagname of the new node
      stringValue - text value of the new node, use null for no value
      Returns:
      new DOM Element

    • collectChildren

      protected static void collectChildren(IXmlNode current, String path, Collection<IXmlNode> result)

    • equals

      public boolean equals(Object x)
      Two XMLNode objects are the same if their w3c node is the same.
      Overrides:
      equals in class Object
      Parameters:
      x - The object this instance should be compared to.
      Returns:
      boolean indicating if the object is considered equal.

    • hashCode

      public int hashCode()
      hashCode needs to be overridden as well because of the equals() above.
      Overrides:
      hashCode in class Object
      Returns:
      The hash code of the XML node.

    • getName

      public String getName()
      Description copied from interface: IXmlNode
      The name of the element (usually the XML tag).
      Specified by:
      getName in interface IXmlNode
      Returns:
      The name of the element.

    • setName

      public void setName(String name) throws XmlParseException
      Description copied from interface: IXmlNode
      Change the tag name. WARNING: EXPENSIVE OPERATION ON W3C DOM TREE ELEMENTS!!!
      Specified by:
      setName in interface IXmlNode
      Parameters:
      name - new name
      Throws:
      XmlParseException - if name is null or invalid, or when trying to rename root element (sorry, not supported)

    • getNamespaceURI

      public String getNamespaceURI()
      Description copied from interface: IXmlNode
      return the URI of the node's namespace. Requires a Namespace-aware DOM parser to work, otherwise returns null
      Specified by:
      getNamespaceURI in interface IXmlNode
      Returns:
      the URI of the node's namespace.

    • getLocalName

      public String getLocalName()
      Description copied from interface: IXmlNode
      return the local node name. Requires a Namespace-aware DOM parser to work, otherwise returns null
      Specified by:
      getLocalName in interface IXmlNode
      Returns:
      the local node name.

    • getNamespacePrefix

      public String getNamespacePrefix()
      Description copied from interface: IXmlNode
      return the namespace (prefix) of the node. Requires a Namespace-aware DOM parser to work, otherwise returns null
      Specified by:
      getNamespacePrefix in interface IXmlNode
      Returns:
      the namespace (prefix) of the node.

    • lookupNamespaceURI

      public String lookupNamespaceURI(String prefix)
      Description copied from interface: IXmlNode
      Look up the namespace URI associated to the given prefix, starting from this node.
      Specified by:
      lookupNamespaceURI in interface IXmlNode
      Returns:
      the namespace uri for the prefix

    • getValue

      public String getValue()
      Description copied from interface: IXmlNode
      The text 'value' of the element -- easy shortcut to get tag values.
      Specified by:
      getValue in interface IXmlNode
      Returns:
      The value of the element.

    • getAttribute

      public String getAttribute(String attr) throws XmlParseException
      Description copied from interface: IXmlNode
      Get the value of an attribute of this element.
      Specified by:
      getAttribute in interface IXmlNode
      Parameters:
      attr - the attribute name to get the value of.
      Returns:
      the value of the attribute
      Throws:
      XmlParseException - if attribute was not found
      See Also:

    • getAttribute

      public String getAttribute(String attribute, String fallback, boolean onEmpty)
      Description copied from interface: IXmlNode
      This method looksup an optional attribute within an XML node. If the attribute was not available the fallback value is taken. In addition the onEmpty can be used to count a zero-length (after trim) string as fallback as well. 
       A node attribute specified as: attr="" will have the following results:

 node.getAttribute( "attr", "default", false ) => ""
 node.getAttribute( "attr", "default", true ) => "default"
      Specified by:
      getAttribute in interface IXmlNode
      Parameters:
      attribute - The attribute to look for in the xml node.
      fallback - The fallback value to take when the attribute was not found or when 'onEmpty' the value was empty.
      onEmpty - The onEmpty makes the getAttribute take the fallback value when the trimmed value string was empty as well, otherwise empty strings count as value.
      Returns:
      The value according to the function, which can only be null when fallback is null.

    • getAttribute

      public String getAttribute(QualifiedName qualifiedName, boolean required)
      Description copied from interface: IXmlNode
      This method looksup an optional qualified attribute within an XML node.
      Specified by:
      getAttribute in interface IXmlNode
      Parameters:
      qualifiedName - The qualified attribute to look for in the xml node.
      required - Whether or not the attribute is required to be present
      Returns:
      The attribute value, may be null when required=false

    • hasAttributes

      public boolean hasAttributes()
      Description copied from interface: IXmlNode
      Shortcut method to quickly see if there are any attributes.
      Specified by:
      hasAttributes in interface IXmlNode
      Returns:
      Boolean indicating if the node has any attributes.

    • getAttributeSafe

      public String getAttributeSafe(String attr)
      Description copied from interface: IXmlNode
      Get the value of an attribute of this element.
      Specified by:
      getAttributeSafe in interface IXmlNode
      Parameters:
      attr - the attribute name to get the value of.
      Returns:
      the value of the attribute (String), or null if the attribute doesn't exist.
      See Also:

    • getAttributeNodes

      public IXmlNode[] getAttributeNodes()
      Description copied from interface: IXmlNode
      Returns the nodes of the attributes.
      Specified by:
      getAttributeNodes in interface IXmlNode
      Returns:
      an array containing the attribute nodes.

    • getAttributes

      public Map<String,String> getAttributes()
      Description copied from interface: IXmlNode
      Get all attributes of this element, as an ATTRNAME-to-VALUE mapping. If there are no attributes, returns an empty Map. This is faster than an ordered map!
      Specified by:
      getAttributes in interface IXmlNode
      Returns:
      Map containing all the attributes names and values.

    • getTagValue

      public String getTagValue(String tagname) throws XmlParseException
      Description copied from interface: IXmlNode
      Get the value of the first element with a certain XML tag.
      Specified by:
      getTagValue in interface IXmlNode
      Parameters:
      tagname - the name of the tag
      Returns:
      the value of the first tag with the given tagname
      Throws:
      XmlParseException - if no tag was found

    • findTag

      public IXmlNode findTag(String tagname) throws XmlParseException
      Description copied from interface: IXmlNode
      Get the first element with a certain XML tag name (starting at current element).
      Specified by:
      findTag in interface IXmlNode
      Parameters:
      tagname - the name of the tag
      Returns:
      the first XMLNode with the given tagname
      Throws:
      XmlParseException - if no tag was found

    • getTagValues

      public List<String> getTagValues(String tagname)
      Description copied from interface: IXmlNode
      Make a list of the values of all elements with a certain XML tag name, recursively. The list is constructed in preorder document traversal (depth-first) (this means: in the normal top-to-bottom 'reading' sequence that you expect)
      Specified by:
      getTagValues in interface IXmlNode
      Parameters:
      tagname - the name of the tags you seek
      Returns:
      a List containing all values of the tags you seek. It will be an empty list if no tags are found.

    • getFirstElement

      public IXmlNode getFirstElement() throws XmlParseException
      Description copied from interface: IXmlNode
      Returns the first element child of this element (only one level deep). This will skip comment nodes, entity nodes, #TEXT nodes etc.
      Specified by:
      getFirstElement in interface IXmlNode
      Returns:
      the first element child of this element
      Throws:
      XmlParseException - if this element has no element children

    • getFirstChild

      public IXmlNode getFirstChild() throws XmlParseException
      Description copied from interface: IXmlNode
      Returns the first child of this element (only one level deep). This may be a comment node, entity node, #TEXT node etc. !!!!!
      Specified by:
      getFirstChild in interface IXmlNode
      Returns:
      the first child node of this element
      Throws:
      XmlParseException - if this element has no child nodes

    • findChild

      public IXmlNode findChild(String tagname) throws XmlParseException
      Description copied from interface: IXmlNode
      Finds a required XMLNode that occurs as a child (only one level deep) with the specified tagname.
      Specified by:
      findChild in interface IXmlNode
      Parameters:
      tagname - the name of the child
      Returns:
      the element that is found
      Throws:
      XmlParseException - if no child was found

    • findChild

      public IXmlNode findChild(String tagname, boolean required) throws XmlParseException
      Description copied from interface: IXmlNode
      Finds an XMLNode that occurs as a child (only one level deep) with the specified tagname.
      Specified by:
      findChild in interface IXmlNode
      Parameters:
      tagname - the name of the child
      required - true indicates that the child has to exist
      Returns:
      the element that is found, or null if nothing is found and required==false
      Throws:
      XmlParseException - if no child was found and required == true

    • findFirstChild

      protected IXmlNode findFirstChild(String tagname) throws XmlParseException
      Throws:
      XmlParseException

    • findChildren

      protected List<IXmlNode> findChildren(String tagname)

    • findElements

      protected List<IXmlNode> findElements()

    • getChildren

      public IXmlNode[] getChildren()
      Description copied from interface: IXmlNode
      This method returns all the child element nodes of the current node.
      Specified by:
      getChildren in interface IXmlNode
      Returns:
      all the child element nodes of the current node.

    • getChildren

      public IXmlNode[] getChildren(String path)
      Description copied from interface: IXmlNode
      This method returns an array containing all the children that can be found matching the specified path. When no children are available for the path, an empty array will be returned. The path may consist of multiple tags separated by a slash. For instance: 
       <node>
     <foo>
         <bar>1</bar>
     </foo>
     <foo>
         <bar>2</bar>
     </foo>
 </node>
 
 node.getChildren( "foo/bar" );
      The example above will return an array containing 2 elements (bar 1 & 2)
      Specified by:
      getChildren in interface IXmlNode
      Parameters:
      path - The XML path for which the child nodes are requested.
      Returns:
      An array containing all the children for the specified path, never null.

    • getParentSafe

      public IXmlNode getParentSafe()
      Description copied from interface: IXmlNode
      returns the parent node, or null if there is no parent.
      Specified by:
      getParentSafe in interface IXmlNode
      Returns:
      The parent node of this element, or null if no parent is present.

    • getParent

      public IXmlNode getParent() throws XmlParseException
      Description copied from interface: IXmlNode
      returns the parent node, raises XMLException if there is no parent.
      Specified by:
      getParent in interface IXmlNode
      Returns:
      The parent node of this element (never null).
      Throws:
      XmlParseException

    • getNextSibling

      public IXmlNode getNextSibling() throws XmlParseException
      Description copied from interface: IXmlNode
      Get the next sibling node, that is, the next node on the same level as this node.
      Specified by:
      getNextSibling in interface IXmlNode
      Returns:
      the next sibling element
      Throws:
      XmlParseException - if no next sibling element was found.

    • getNextSiblingSafe

      public IXmlNode getNextSiblingSafe()
      Description copied from interface: IXmlNode
      Get the next sibling node, that is, the next node on the same level as this node.
      Specified by:
      getNextSiblingSafe in interface IXmlNode
      Returns:
      the next sibling element, or null if no next sibling is found.

    • findTags

      protected List<IXmlNode> findTags(String tagname)
      Make a list of all XMLNodes with a certain XML tag name, recursively. The list is constructed in preorder document traversal (depth-first). (this means: in the normal top-to-bottom 'reading' sequence that you expect)
      Parameters:
      tagname - the name of the tags you seek
      Returns:
      a List containing all XMLNodes with the tag name. It will be an empty list if no tags are found.

    • getNodeType

      protected short getNodeType()

    • getW3CRootNode

      protected Node getW3CRootNode()

    • getW3CDocument

      protected Document getW3CDocument()

    • addChild

      protected void addChild(XmlNode existingChild, XmlNode newChild, boolean before) throws XmlParseException
      Add a sibling child next to a given existing child (of this node).
      Parameters:
      existingChild - existing child node to add a new node next to
      newChild - new node to add
      before - set to true if you want to insert before existing child, otherwise the new sibling is inserted after it
      Throws:
      XmlParseException - when the child node doesn't exist or when you try to create invalid XML

    • addChild

      protected void addChild(XmlNode child) throws XmlParseException
      Add a new child at the end of the existing child nodes of this node.
      Parameters:
      child - new child element
      Throws:
      XmlParseException - when you try to create invalid XML

    • removeChild

      protected void removeChild(XmlNode childNode) throws XmlParseException
      remove a child node.
      Parameters:
      childNode - node to remove
      Throws:
      XmlParseException - if the child node didn't exist

    • removeAllChildren

      protected void removeAllChildren()
      remove all child nodes.

    • replaceChild

      protected void replaceChild(XmlNode oldChild, XmlNode newChild)
      replace a child with a new child.
      Parameters:
      oldChild - child node to replace
      newChild - child node to replace with
      Throws:
      XmlParseException - if the child node did not exist, or if you try to create invalid XML

    • toString

      public String toString()
      * Get some readable info on a DOM node - for debugging private String node2String(Node n) { if (n != null) { String type; switch (n.getNodeType()) { case Node.ELEMENT_NODE: type = "ELEMENT"; break; case Node.ATTRIBUTE_NODE: type = "ATTRIBUTE"; break; case Node.TEXT_NODE: type = "TEXT"; break; case Node.CDATA_SECTION_NODE: type = "CDATA_SECTION"; break; case Node.ENTITY_REFERENCE_NODE: type = "ENTITYREF"; break; case Node.ENTITY_NODE: type = "ENTITY"; break; case Node.PROCESSING_INSTRUCTION_NODE: type = "PROCESSING"; break; case Node.COMMENT_NODE: type = "COMMENT"; break; case Node.DOCUMENT_NODE: type = "DOCUMENT"; break; case Node.DOCUMENT_TYPE_NODE: type = "DOCTYPE"; break; case Node.DOCUMENT_FRAGMENT_NODE: type = "DOCFRAGMENT"; break; case Node.NOTATION_NODE: type = "NOTATION"; break; default: type = "??"; break; } return n.getNodeName() + " type=" + type + " #children=" + n.getChildNodes().getLength() + " value=" + n.getNodeValue(); } else return "null"; }
      Overrides:
      toString in class Object

    • createXMLNode

      protected IXmlNode createXMLNode(String name, String stringValue)
      Create a new XMLNode (containing a new w3c DOM Node), optionally with a text value.
      Parameters:
      name - tagname of the new node
      stringValue - text value of the new node, use null for no value
      Returns:
      new DOM Element

    • getChild

      public IXmlNode getChild(String path) throws XmlException
      Description copied from interface: IXmlNode
      This method will return the child node indicated by the path. When the path refers to multiple child elements, this method will raise an exception.
      Specified by:
      getChild in interface IXmlNode
      Parameters:
      path - XML path identifying a single child node.
      Returns:
      The child node for the specified path.
      Throws:
      XmlException - This exception is thrown when multiple or no node at all are/is found matching the path.

    • getChild

      protected IXmlNode getChild(String path, boolean safe) throws XmlException
      Throws:
      XmlException

    • getChildSafe

      public IXmlNode getChildSafe(String path) throws XmlException
      Description copied from interface: IXmlNode
      This method will return the child node indicated by the path. When the path refers to multiple child elements, this method will raise an exception.
      Specified by:
      getChildSafe in interface IXmlNode
      Parameters:
      path - XML path identifying a single child node.
      Returns:
      The child node for the specified path.
      Throws:
      XmlException - This exception is thrown when multiple nodes are found matching the path.

    • toXmlFragment

      public String toXmlFragment()
      Description copied from interface: IXmlNode
      Easy way to create an XML string for this element and the children. Indent starts at 0. The toXMLfragment method operating on a StringBuffer is faster and better suited when creating only a part of a larger document. This method returns a string and was designed to get the "final" representation. It uses whitespace indentation for pretty printing.
      Specified by:
      toXmlFragment in interface IXmlNode
      Returns:
      String containing the XML of this element and children.

    • toXmlfragment

      protected void toXmlfragment(StringBuffer buffer, int i, Node node, boolean useIndentation)