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

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