Package org.dlese.dpc.xml.schema

Class DocMap

java.lang.Object
org.dlese.dpc.xml.schema.DocMap
public class DocMap extends Object
DocMap wraps a dom4j Document providing get and put methods for use with a Map-Backed Action form. Also supports document operations such as creating, inserting and removing nodes.
Author:
ostwald

  • Constructor Summary

    Constructors
    Constructor
    Description
    DocMap(org.dom4j.Document doc)
    Constructor for the DocMap object
    DocMap(org.dom4j.Document doc, SchemaHelper schemaHelper)
    Constructor for the DocMap object

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    addElement(org.dom4j.Element e, String encodedReferencePath)
    Called from metadata controller to add an element at a specific place in the document.
    org.dom4j.Node
    createNewNode(String xpath)
    Creates a new node at the location specified by the xpath, creating all the necessary nodes along the path in the process.
    org.dom4j.Node
    createNewSiblingNode(String xpath)
    Creates new node that is a sibling of the node at provided xpath
    Object
    get(String key)
    Given an encoded xpath, return the value of the referred to node
    org.dom4j.Document
    getDocument()
    Gets the document attribute of the DocMap object
    int
    getSiblingCount(String xpath)
    finds the like-named siblings of the node specified by xpath.
    boolean
    hasChildren(String xpath)
    Return true if the specified node is an Element and has either a sub-element, or an attribute (even if they are empty), OR content.
    void
    insertElement(org.dom4j.Element element, org.dom4j.Element parent, String targetPath)
    Insert the given element into parent using targetPath for placement information (insertion point is immediatlely following the node identified by targetPath).
    boolean
    isEmpty(String xpath)
    Returns true if an element (recursively) has no textual content, no children, and no attributes with values.
    boolean
    nodeExists(String xpath)
    Returns true if there is a node at specified xpath
    void
    orderSequenceElements(org.dom4j.Element parent)
    Put sequence elements in the order specified by the sequence compositor.
    protected final void
    prtln(String s)
    Description of the Method
    protected final void
    prtlnErr(String s)
    NOT YET DOCUMENTED
    void
    put(Object key, Object val)
    Updates the Document by setting the Text of the Node at the specified xpath.
    void
    remove(String xpath)
    removes a node from the dom4j Document.
    void
    removeElement(String encodedXPath)
    Removes the element at specified path
    boolean
    removeSiblings(String xpath)
    Remove a node and all it's siblings (having the same element name) from the parent node.
    List
    selectNodes(String xpath)
    Get list of all nodes selected by provided xpath
    org.dom4j.Node
    selectSingleNode(String xpath)
    Gets first node at proviced xpath
    void
    smartPut(String xpath, String value)
    Tests xpath against provided schema (via SchemaHelper) before putting value, creating a new Node if one is not found at xpath.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DocMap

      public DocMap(org.dom4j.Document doc)
      Constructor for the DocMap object
      Parameters:
      doc - Description of the Parameter

    • DocMap

      public DocMap(org.dom4j.Document doc, SchemaHelper schemaHelper)
      Constructor for the DocMap object
      Parameters:
      doc - NOT YET DOCUMENTED
      schemaHelper - NOT YET DOCUMENTED

  • Method Details

    • getDocument

      public org.dom4j.Document getDocument()
      Gets the document attribute of the DocMap object
      Returns:
      The document value

    • selectNodes

      public List selectNodes(String xpath)
      Get list of all nodes selected by provided xpath
      Parameters:
      xpath - the xpath
      Returns:
      list of nodes

    • selectSingleNode

      public org.dom4j.Node selectSingleNode(String xpath)
      Gets first node at proviced xpath
      Parameters:
      xpath - Description of the Parameter
      Returns:
      Description of the Return Value

    • nodeExists

      public boolean nodeExists(String xpath)
      Returns true if there is a node at specified xpath
      Parameters:
      xpath - xpath to node
      Returns:
      true if node exists at xpath

    • get

      public Object get(String key)
      Given an encoded xpath, return the value of the referred to node
      Parameters:
      key - xpath encoded as necessary for use in jsp
      Returns:
      text of the node referred to by the xpath or an empty string if the node cannot be found

    • put

      public void put(Object key, Object val)
      Updates the Document by setting the Text of the Node at the specified xpath. If there is no node at the specified path, a new one is created.

      ISSUE: what if there is no value (one way this happens is when there is a field in the form but no value is supplied by user. In this case we shouldn't bother creating a new node because there is no value to insert. But what if there was formerly a value and the user has deleted it? if the node is an Element, then should that element be deleted? (The user should be warned first!) if the node is an attribute, then should that attribute be deleted? (the user won't be warned, since this does not have the "ripple" effect that deleting an element can have. (maybe the user should be warned only if the element has children with values).

      Parameters:
      key - unencoded xpath
      val - value to assign to node at xpath

    • smartPut

      public void smartPut(String xpath, String value) throws Exception
      Tests xpath against provided schema (via SchemaHelper) before putting value, creating a new Node if one is not found at xpath.
      Parameters:
      xpath - NOT YET DOCUMENTED
      value - NOT YET DOCUMENTED
      Throws:
      Exception - NOT YET DOCUMENTED

    • hasChildren

      public boolean hasChildren(String xpath)
      Return true if the specified node is an Element and has either a sub-element, or an attribute (even if they are empty), OR content.
      Parameters:
      xpath - xpath to the node to be evaluated for children
      Returns:
      true if sub-elements, or attributes, false otherwise or if node is not an Element

    • isEmpty

      public boolean isEmpty(String xpath)
      Returns true if an element (recursively) has no textual content, no children, and no attributes with values.

      Note: returns FALSE if no node exists at the given path.

      Parameters:
      xpath - Description of the Parameter
      Returns:
      true if empty, false if any errors are encountered

    • remove

      public void remove(String xpath)
      removes a node from the dom4j Document.
      Parameters:
      xpath - Description of the Parameter

    • removeSiblings

      public boolean removeSiblings(String xpath) throws Exception
      Remove a node and all it's siblings (having the same element name) from the parent node. One way to do this would be to clear the contents of the parent node, but i'm not sure this is safe. so instead we will find all nodes matching the "deindexed" xpath and then remove them individually.
      Parameters:
      xpath - xpath to an enumeration node
      Returns:
      true if successful
      Throws:
      Exception - if unable to remove siblings

    • getSiblingCount

      public int getSiblingCount(String xpath)
      finds the like-named siblings of the node specified by xpath.
      Parameters:
      xpath - an xpath to a specific node
      Returns:
      the total number of siblings with the same element name (including the node specified by the xpath)

    • addElement

      public boolean addElement(org.dom4j.Element e, String encodedReferencePath)
      Called from metadata controller to add an element at a specific place in the document. The xpath specified by encodedReferencePath provides an insertion point for the new element. Namely, we want to insert the new element immdediately following the encodedReferencePath.
      Parameters:
      e - The feature to be added to the Element attribute
      encodedReferencePath - The feature to be added to the Element attribute
      Returns:
      NOT YET DOCUMENTED

    • insertElement

      public void insertElement(org.dom4j.Element element, org.dom4j.Element parent, String targetPath) throws Exception
      Insert the given element into parent using targetPath for placement information (insertion point is immediatlely following the node identified by targetPath).
      Parameters:
      element - element to be inserted
      parent - parent in which to insert element
      targetPath - specifies insertion point
      Throws:
      Exception - NOT YET DOCUMENTED

    • orderSequenceElements

      public void orderSequenceElements(org.dom4j.Element parent)
      Put sequence elements in the order specified by the sequence compositor.
      Parameters:
      parent - NOT YET DOCUMENTED

    • removeElement

      public void removeElement(String encodedXPath)
      Removes the element at specified path
      Parameters:
      encodedXPath - xpath encoded by jsp

    • createNewSiblingNode

      public org.dom4j.Node createNewSiblingNode(String xpath) throws Exception
      Creates new node that is a sibling of the node at provided xpath
      Parameters:
      xpath - xpath to existing node
      Returns:
      newly created sibling node
      Throws:
      Exception - if a new node cannot be created

    • createNewNode

      public org.dom4j.Node createNewNode(String xpath) throws Exception
      Creates a new node at the location specified by the xpath, creating all the necessary nodes along the path in the process.

      When schemaHelper is present and the path specifies an Element, then a new element is created by SchemaHelper.getNewElement. Otherwise, the newly created Element (or Attribute) is empty.

      Parameters:
      xpath - location of new node to be created
      Returns:
      dom4j Node (either an Attribute or an Element)
      Throws:
      Exception - if unable to create a new node at xpath

    • prtlnErr

      protected final void prtlnErr(String s)
      NOT YET DOCUMENTED
      Parameters:
      s - NOT YET DOCUMENTED

    • prtln

      protected final void prtln(String s)
      Description of the Method
      Parameters:
      s - Description of the Parameter