Package org.vast.xml

Class DOMHelper

java.lang.Object
org.vast.xml.DOMHelper
public class DOMHelper extends Object

TODO DOMHelper description TODO try to avoid calls to xerces specific classes

Since:
Nov 3, 2005

  • Field Details

    • XML_NS_URI

      public static final String XML_NS_URI
      See Also:

    • XSI_NS_URI

      public static final String XSI_NS_URI
      See Also:

    • DEFAULT_PREFIX

      public static final String DEFAULT_PREFIX
      See Also:

    • PATH_SEPARATOR

      protected static final String PATH_SEPARATOR
      See Also:

    • userPrefixTable

      protected Map<String,String> userPrefixTable
      User prefix to domain map

    • loadedDocuments

      protected Map<String,XMLDocument> loadedDocuments
      Linked documents (URI object -> XMLDocument Object)

    • mainFragment

      protected XMLFragment mainFragment
      Main Document object

    • matchingNodes

      protected XMLNodeList matchingNodes
      List of nodes returned

    • currentPath

      protected ArrayList<String> currentPath
      Current path inside the xml file being parsed.
      Paths have to be given as element names separated by /
      Namespaces are separated from the node name by ':'
      Example: "gml:feature/gml:polyline/epsg"

    • wantedPath

      protected String[] wantedPath

    • eltQName

      protected org.vast.xml.QName eltQName

    • validation

      protected boolean validation

  • Constructor Details

    • DOMHelper

      public DOMHelper()

    • DOMHelper

      public DOMHelper(String url, boolean validation) throws DOMHelperException
      Loads an existing XML document from the given URL
      Parameters:
      url -
      validation -
      Throws:
      DOMHelperException

    • DOMHelper

      public DOMHelper(InputStream inputStream, boolean validation) throws DOMHelperException
      Loads an existing XML document from the given InputStream
      Parameters:
      inputStream -
      validation -
      Throws:
      DOMHelperException

    • DOMHelper

      public DOMHelper(InputStream inputStream, boolean validation, Map<String,String> schemaLocations) throws DOMHelperException
      Loads an existing XML document from the given InputStream
      Parameters:
      inputStream -
      validation -
      schemaLocations -
      Throws:
      DOMHelperException

    • DOMHelper

      public DOMHelper(Document domDocument)
      Loads an existing document from the given DOM Document object
      Parameters:
      domDocument -

    • DOMHelper

      public DOMHelper(String docQName)
      Creates a DOMHelper on a new document with the given QName
      Parameters:
      docQName -

  • Method Details

    • createDocument

      public void createDocument(String qname)
      Creates a new Document with the given qname The new document will replace the document loaded in this DOMHelper
      Parameters:
      qname -

    • getRootElement

      public Element getRootElement()
      Returns the root element of the document
      Returns:
      Root Element Node or null if root element is not found

    • getBaseElement

      public Element getBaseElement()
      Returns the base element of the fragment attached to this reader
      Returns:
      W3C Element

    • setBaseElement

      public void setBaseElement(Element elt)
      Sets the element to use as the base when reading/writing with default methods
      Parameters:
      elt -

    • getDocument

      public Document getDocument()
      Gets the DOM Document attached to this DOMHelper
      Returns:
      DOM Document owning the main fragment

    • setDocument

      public void setDocument(Document domDocument)
      Sets the Document to wrap with this DOMHelper
      Parameters:
      domDocument -

    • getXmlDocument

      public XMLDocument getXmlDocument()
      Gets the XMLDocument attached to this DOMHelper
      Returns:
      XMLDocument

    • getXmlFragment

      public XMLFragment getXmlFragment()
      Gets the XMLFragment attached to this DOMHelper
      Returns:
      XMLFragment

    • addUserPrefix

      public void addUserPrefix(String prefix, String nsDomain)
      Add an entry to the table of user prefixes This table is used to map user prefixes to a real namespace uri
      Parameters:
      prefix -
      nsDomain -

    • addNSDeclaration

      public void addNSDeclaration(String prefix, String nsUri)

    • addSchemaLocation

      public void addSchemaLocation(String nsUri, String schemaUrl)
      Add a schema location entry (xsi:schemaLocation attribute)
      Parameters:
      nsUri - namespace URI or null is this schema is associated to the default NS
      schemaUrl - URL of the schema to use for validation

    • getNodes

      public NodeList getNodes(Node startNode, String nodePath, int nodeTypeFilter, int maxCount)
      Find all nodes matching the given path - ex: Sensor/identification
      Parameters:
      startNode - DOM Node where to start the search
      nodePath - Path of the node relative to startNode (case independent, separation char = /)
      nodeTypeFilter - type of node to look for (0 for any type)
      maxCount - maximum number of nodes to look for
      Returns:
      the NodeList of Node objects found or an Empty NodeList if no matching nodes are found

    • getElements

      public NodeList getElements(Element startElement, String nodePath)
      Find elements matching the given path - ex: Sensor.locatedUsing
      Parameters:
      startElement - DOM Node where to start the search
      nodePath - Path of the element relative to startNode (case independent, separation char = /)
      Returns:
      the NodeList of Element objects found or an Empty NodeList if no matching elements are found

    • getElements

      public NodeList getElements(String nodePath)
      Default version of the previous function with startNode = base node of document (not always the root !!)
      Parameters:
      nodePath - Path of the element in the XML tree (case independent, separation char = /)
      Returns:
      the NodeList of Element objects found or an Empty NodeList if no matching elements are found

    • getElement

      public Element getElement(Element startElement, String nodePath)
      Find the first element matching the given path
      Parameters:
      startElement - DOM Node where to start the search
      nodePath - Path of the element relative to startNode (case independent, separation char = /)
      Returns:
      the first Element object found or null if no matching element is found

    • getElement

      public Element getElement(String nodePath)
      Default version of the previous function with startNode = base node of document (not always the root !!)
      Parameters:
      nodePath - Path of the element in the XML tree (case independent, separation char = "/")
      Returns:
      the first Element object found or null if no matching nodes are found

    • getElementValue

      public String getElementValue(Element startElement, String nodePath)
      Get the value of an element from its path
      Parameters:
      startElement - DOM Node where to start the search
      nodePath - Path of the element in the XML tree (case independent, separation char = "/")
      Returns:
      Node value as a String or null if no matching element is found

    • getElementValue

      public String getElementValue(String nodePath)
      Default version of the previous function that gets the value of the first element found
      Parameters:
      nodePath - Path of the element in the XML tree (case independent, separation char = "/")
      Returns:
      Node value as a String or null if no matching element is found

    • getElementValue

      public String getElementValue(Element element)
      Default version of the getElementValue(Element, String) function. The nodePath is here set to null and thus this method simply retrieves the text content of the given Element.
      Parameters:
      element -
      Returns:
      Element text value

    • getAttributeValue

      public String getAttributeValue(Element startElement, String nodePath)
      Read the attribute value
      Parameters:
      startElement - DOM Node where to start the search
      nodePath - Path of the element relative to startNode (case independent, separation char = "/")
      Returns:
      the attribute value as a string or null if no matching attribute is found

    • getAttributeValue

      public String getAttributeValue(String nodePath)
      Default version of the previous function with startNode = base node of document (not always the root !!)
      Parameters:
      nodePath - Path of the element in the XML tree (case independent, separation char = "/")
      Returns:
      the attribute value as a String or null if no matching attribute is found

    • existElement

      public boolean existElement(Element startElement, String nodePath)
      Determine if the element corresponding to the given path exists
      Parameters:
      startElement - DOM Node where to start the search
      nodePath - Path of the element in the DOM tree (case independent, separation char = "/")
      Returns:
      true if the element is present

    • existElement

      public boolean existElement(String nodePath)
      Default version of the previous function with startNode = base node of document (not always the root !!)
      Parameters:
      nodePath - Path of the element in the XML tree (case independent, separation char = /)
      Returns:
      true if the element is present

    • existAttribute

      public boolean existAttribute(Element startElement, String nodePath)
      Determine if the attribute corresponding to the given path exists
      Parameters:
      startElement - Node where to start the search
      nodePath - Path of the attribute in the DOM tree (case independent, separation char = /)
      Returns:
      true if the attribute is present

    • existAttribute

      public boolean existAttribute(String nodePath)
      Default version of the previous function with startNode = base node of document (not always the root !!)
      Parameters:
      nodePath - Path of the attribute in the DOM tree (case independent, separation char = /)
      Returns:
      true if the attribute is present

    • hasQName

      public boolean hasQName(Node node, String qname)
      Checks if the given node has the given name This does the comparison using user prefixes
      Parameters:
      node -
      qname -
      Returns:
      true if QName matches

    • getAllElements

      public NodeList getAllElements(Element startElement, String tagName)
      Look for all the elements below the startNode with the given tag name If the XML document defines namespaces, this method requires a fully qualified element name (prefix + local name), and the prefix needs to be defined by calling addUserPrefix(prefix, ns-uri)
      Parameters:
      startElement - Node where to start the search
      tagName - Name of the nodes to look for
      Returns:
      a NodeList containing all the matching elements or an Empty NodeList if no matching elements are found

    • getAllElements

      public NodeList getAllElements(String name)
      Default version of the previous function
      with startNode = base node of document (not always the root !!)
      Parameters:
      name - String Name of the nodes to look for
      Returns:
      NodeList containing all the matching elements or an Empty NodeList if no matching elements are found

    • getAllChildElements

      public NodeList getAllChildElements(Element parentElement)
      Get all child elements of the given node (don't return any text or comment nodes !) This method will follow any xlink:href if specified.
      Parameters:
      parentElement - Node to retrieve the children from
      Returns:
      NodeList of child elements or an Empty NodeList if no children elements are found

    • getFirstChildElement

      public Element getFirstChildElement(Element parentElement)
      Get the first child of the parentNode. This method will follow any xlink:href if specified.
      Parameters:
      parentElement - Node to retrieve the children from
      Returns:
      NodeList of child elements or null if no children elements are found

    • getChildElements

      public NodeList getChildElements(Node parentNode)
      Get the child elements (only elements !!) of the parentNode This method is basic... It won't follow xlink:href
      Parameters:
      parentNode - Node to retrieve the children from
      Returns:
      NodeList of child elements or an Empty NodeList if no children elements are found

    • addNode

      public Node addNode(Node parentNode, String nodePath, int nodeType)
      Adds any type of node to the parent node
      Parameters:
      parentNode -
      nodePath -
      nodeType -
      Returns:
      the newly added Node

    • addElement

      public Element addElement(Node parentNode, String nodePath)
      Adds an element to the document at the given location relative to the parent element. This will also add all the elements given in the path if they are not yet present or if marked with a '+' prefix.
      Parameters:
      parentNode -
      nodePath -
      Returns:
      DOM Element after it has been created and appended to the DOM

    • addElement

      public Element addElement(String nodePath)
      Default version of the previous method using the base element as the parent element.
      Parameters:
      nodePath -
      Returns:
      DOM Element after it has been created and appended to the DOM

    • setNodeValue

      public void setNodeValue(Node parentNode, String val)
      Sets the text content of a node (element or atribute)
      Parameters:
      parentNode -
      val -

    • removeAllText

      protected void removeAllText(Node parent)
      Remove all text node children from the parent
      Parameters:
      parent -

    • setElementValue

      public Element setElementValue(Element parentElement, String nodePath, String val)
      Adds all necessary elements in the path and sets the text value of the leaf element to the given String.
      Parameters:
      parentElement -
      nodePath -
      val -
      Returns:
      the element to which the text node was appended

    • setElementValue

      public void setElementValue(Element elt, String val)
      Default version of previous method to add value to an element directly
      Parameters:
      elt -
      val -

    • setElementValue

      public Element setElementValue(String nodePath, String text)
      Default version of the previous method using the base element as the parent element.
      Parameters:
      nodePath -
      text -
      Returns:
      the element to which the text node was appended

    • setAttributeValue

      public void setAttributeValue(Element startElement, String nodePath, String val)
      Adds all necessary elements and the final attribute in the path and sets the text value of the attribute to the given String.
      Parameters:
      startElement -
      nodePath -
      val -

    • setAttributeValue

      public void setAttributeValue(String nodePath, String text)
      Default version of the previous method using the base element as the parent element.
      Parameters:
      nodePath -
      text -

    • setIdAttribute

      public void setIdAttribute(String nodePath, String text)
      Special method to set an id attribute value on selected element
      Parameters:
      nodePath -
      text -

    • setXsiNil

      public void setXsiNil(Element startElement, String nodePath)
      Adds the xsi:nil="true" attribute to the specified element
      Parameters:
      startElement -
      nodePath - must point to an element

    • createElement

      public Element createElement(XMLDocument parentDoc, String qname)
      Creates a new element using the underlying DOM Document.
      Parameters:
      parentDoc -
      qname - qname of the new element
      Returns:
      Newly created DOM element (owned by the main document)

    • createElement

      public Element createElement(String qname)
      Creates a new element using the main document
      Parameters:
      qname -
      Returns:
      Newly created DOM element (owned by the main document)

    • writeNode

      protected boolean writeNode(XMLDocument currentDocument, Node node, int nodeType)
      Follow the path if nodes already exist or create necessary elements
      Parameters:
      currentDocument -
      node -
      nodeType -
      Returns:

    • readNode

      protected boolean readNode(XMLDocument currentDocument, Node node, int nodeTypeFilter, int maxCount)
      This function is called recursively and look for the wanted nodes
      The matching nodes are added to the class variable 'matchingNodes'
      Parameters:
      currentDocument - XML document where the search is performed
      node - The node from which we start the search
      nodeTypeFilter - node type to be retrieved
      maxCount - maximum number of matching nodes to look for
      Returns:
      boolean true if the search is done, false otherwise

    • serialize

      public void serialize(Node node, OutputStream out, boolean pretty) throws IOException
      Helper method to serialize this DOM to a stream
      Parameters:
      node -
      out -
      pretty - set to true to indent output
      Throws:
      IOException

    • parseStream

      protected XMLFragment parseStream(InputStream inputStream, boolean addToTable, Map<String,String> schemaLocations) throws DOMHelperException
      This function parse the XML file if necessary
      Parameters:
      inputStream - Stream containing XML file we want to parse
      Returns:
      The XMLDocument object created
      Throws:
      DOMHelperException
      IOException

    • parseURI

      protected XMLFragment parseURI(String href, boolean forceReload) throws DOMHelperException
      This function parse the XML file if necessary or reuse one already loaded if available
      Parameters:
      href - link (URL#id) to the document
      forceReload - if true, force the document to reload
      Returns:
      The XMLDocument object created
      Throws:
      DOMHelperException

    • getLinkedFragment

      public XMLFragment getLinkedFragment(XMLDocument currentDocument, String idRef) throws DOMHelperException
      Returns an xml element given its ID
      Parameters:
      currentDocument - XMLDocument where to look for local IDs
      idRef - String containing the unique id (local or global with a url)
      Returns:
      Element
      Throws:
      DOMHelperException

    • getParentDocument

      public XMLDocument getParentDocument(Node node)
      Retrieve XMLDocument this element is in
      Parameters:
      node - Node
      Returns:
      XMLDocument

    • appendChild

      public Node appendChild(Node parent, String child)
      Adds a node to the end of the children list
      Parameters:
      parent - Node Parent node receiving the new child
      child - String Child node to be added
      Returns:
      Newly created DOM Node after it has bee appended to the DOM tree

    • comparePaths

      protected int comparePaths(XMLDocument currentDocument, ArrayList<String> actualPath, String[] wantedPath)
      Check if the paths are matching

      Returns -1 if the beginning of wantedPath doesn't match actualPath

      Otherwise returns the number levels still needed to reach the wantedPath
      Parameters:
      currentDocument - XMLDocument
      actualPath - Actual path in the xml tree
      wantedPath - The path we are looking for
      Returns:
      -1 or the number of levels still needed to reach the wanted node (positive integer)

    • getQName

      protected org.vast.xml.QName getQName(XMLDocument parentDoc, String qname)
      Creates a QName object from the given "prefix:name" String.
      Parameters:
      qname -
      Returns:

    • getLastAccessedNode

      public Node getLastAccessedNode()

    • writeToStreamWriter

      public void writeToStreamWriter(Element elt, XMLStreamWriter writer) throws XMLStreamException
      Writes a DOM element using the given XMLStreamWriter
      Parameters:
      elt - DOM element to write
      writer - writer object to use for serialization
      Throws:
      XMLStreamException