DLESE Tools
v1.6.0

org.dlese.dpc.xml.schema
Class DocMap

java.lang.Object
  extended by 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
DocMap(Document doc)
          Constructor for the DocMap object
DocMap(Document doc, SchemaHelper schemaHelper)
          Constructor for the DocMap object
 
Method Summary
 boolean addElement(Element e, String encodedReferencePath)
          Called from metadata controller to add an element at a specific place in the document.
 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.
 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
 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(Element element, 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(Element parent)
          Put sequence elements in the order specified by the sequence compositor.
protected  void prtln(String s)
          Description of the Method
protected  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
 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 Detail

DocMap

public DocMap(Document doc)
Constructor for the DocMap object

Parameters:
doc - Description of the Parameter

DocMap

public DocMap(Document doc,
              SchemaHelper schemaHelper)
Constructor for the DocMap object

Parameters:
doc - NOT YET DOCUMENTED
schemaHelper - NOT YET DOCUMENTED
Method Detail

getDocument

public 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 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(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(Element element,
                          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(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 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 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

DLESE Tools
v1.6.0