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

Interface IXmlNode

  • All Known Implementing Classes:
    XmlNode
    public interface IXmlNode
    base interface for XmlElements (returned from the parsers). Not serializable because XmlElements contain a W3C DOM tree that is not serializable :-(
    Since:
    5.0
    Author:
    Idj, JH van Noorloos

    • Method Detail

      • findChild

        IXmlNode findChild​(String tagname)
            throws XmlParseException
        Finds a required XMLNode that occurs as a child (only one level deep) with the specified tagname.
        Parameters:
        tagname - the name of the child
        Returns:
        the element that is found
        Throws:
        XmlParseException - if no child was found
        XmlParseException - if more then one child was found.

      • findChild

        IXmlNode findChild​(String tagname,
                   boolean required)
            throws XmlParseException
        Finds an XMLNode that occurs as a child (only one level deep) with the specified tagname.
        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
        XmlParseException - if more then one child was found.

      • findTag

        IXmlNode findTag​(String tagname)
          throws XmlParseException
        Get the first element with a certain XML tag name (starting at current element).
        Parameters:
        tagname - the name of the tag
        Returns:
        the first XMLNode with the given tagname
        Throws:
        XmlParseException - if no tag was found

      • getAttribute

        String getAttribute​(String attribute,
                    String fallback,
                    boolean onEmpty)
        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"
        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

        String getAttribute​(QualifiedName qualifiedName,
                    boolean required)
        This method looksup an optional qualified attribute within an xml node.
        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
        Throws:
        XmlException - This exception is thrown when required=true and the qualified attribute is not present.

      • getAttributeNodes

        IXmlNode[] getAttributeNodes()
        Returns the nodes of the attributes.
        Returns:
        an array containing the attribute nodes.

      • getAttributes

        Map<String,​String> getAttributes()
        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!
        Returns:
        Map containing all the attributes names and values.

      • getAttributeSafe

        String getAttributeSafe​(String attr)
        Get the value of an attribute of this element.
        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:
        getAttribute(String)

      • getChild

        IXmlNode getChild​(String path)
           throws XmlException
        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.
        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.

      • getChildren

        IXmlNode[] getChildren​(String path)
        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)
        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.

      • getChildren

        IXmlNode[] getChildren()
        This method returns all the child element nodes of the current node.
        Returns:
        all the child element nodes of the current node.

      • getChildSafe

        IXmlNode getChildSafe​(String path)
               throws XmlException
        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.
        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.

      • getFirstChild

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

      • getFirstElement

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

      • getLocalName

        String getLocalName()
        return the local node name. Requires a Namespace-aware DOM parser to work, otherwise returns null
        Returns:
        the local node name.

      • getName

        String getName()
        The name of the element (usually the XML tag).
        Returns:
        The name of the element.

      • setName

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

      • getNamespacePrefix

        String getNamespacePrefix()
        return the namespace (prefix) of the node. Requires a Namespace-aware DOM parser to work, otherwise returns null
        Returns:
        the namespace (prefix) of the node.

      • lookupNamespaceURI

        String lookupNamespaceURI​(String prefix)
        Look up the namespace URI associated to the given prefix, starting from this node.
        Returns:
        the namespace uri for the prefix

      • getNamespaceURI

        String getNamespaceURI()
        return the URI of the node's namespace. Requires a Namespace-aware DOM parser to work, otherwise returns null
        Returns:
        the URI of the node's namespace.

      • getNextSibling

        IXmlNode getNextSibling()
                 throws XmlParseException
        Get the next sibling node, that is, the next node on the same level as this node.
        Returns:
        the next sibling element
        Throws:
        XmlParseException - if no next sibling element was found.

      • getNextSiblingSafe

        IXmlNode getNextSiblingSafe()
        Get the next sibling node, that is, the next node on the same level as this node.
        Returns:
        the next sibling element, or null if no next sibling is found.

      • getParent

        IXmlNode getParent()
        returns the parent node, raises XMLException if there is no parent.
        Returns:
        The parent node of this element (never null).

      • getParentSafe

        IXmlNode getParentSafe()
        returns the parent node, or null if there is no parent.
        Returns:
        The parent node of this element, or null if no parent is present.

      • getTagValue

        String getTagValue​(String tagname)
            throws XmlParseException
        Get the value of the first element with a certain XML tag.
        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

      • getTagValues

        List<String> getTagValues​(String tagname)
        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)
        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.

      • getValue

        String getValue()
        The text 'value' of the element -- easy shortcut to get tag values.
        Returns:
        The value of the element.

      • hasAttributes

        boolean hasAttributes()
        Shortcut method to quickly see if there are any attributes.
        Returns:
        Boolean indicating if the node has any attributes.

      • toXmlFragment

        String toXmlFragment()
        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.
        Returns:
        String containing the XML of this element and children.