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

Class 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 Detail

      • 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 Detail

      • 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

      • 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 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:
        IXmlNode.getAttribute(String)

      • 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

      • 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.

      • 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.

      • 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 a 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)