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 Details

    • 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 attr) throws XmlParseException
      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
      Throws:
      XmlParseException - if attribute was not found
      See Also:

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

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