ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.xmlconfig
Class DOMUtils

java.lang.Object
  extended by umontreal.iro.lecuyer.xmlconfig.DOMUtils

public class DOMUtils
extends Object

Provides utility methods to build indented DOM documents intended to be converted to XML files. When using the DOM API to build a document, one must manually insert spaces and end-of-lines, otherwise a one-line XML file will be produced if the document is converted to a stream using a JAXP transformer. JAXP does not give access to a flexible automatic indentation facility when using its transformer factory; parameters for this feature are specific to the XML transformer implementation. This class provides helper methods capable of automatically adding some indentations and easing the constructing of the most common DOM elements.


Method Summary
static void addArray2DToElement(Element el, Object array2D, String[] rowNames, int spc)
           
static void addArrayToElement(Element el, Object array, String[] rowNames, int spc)
           
static Element addNestedArray2DElement(Node parent, String name, Object array2D, int spc)
          Equivalent to addNestedArray2DElement (parent, name, array2D, null, spc).
static Element addNestedArray2DElement(Node parent, String name, Object array2D, String[] rowNames, int spc)
          Creates a new element with name name, with the contents of the 2D array array2D, and adds it to node parent.
static Element addNestedArrayElement(Node parent, String name, Object array, int spc)
          Equivalent to addNestedArrayElement (parent, name, array, null, spc).
static Element addNestedArrayElement(Node parent, String name, Object array, String[] rowNames, int spc)
          Creates a new element with name name, with the contents of the array array, and adds it to node parent.
static Comment addNestedComment(Node parent, String text, int spc)
          Creates a comment node in the element parent, with text text, using spc spaces per indentation level.
static Element addNestedElement(Node parent, String name, boolean empty, int spc)
          This method is similar to addNestedTextElement(org.w3c.dom.Node, java.lang.String, java.lang.String, int) except that the created element with tag name name will not have nested text by default.
static Element addNestedTextElement(Node parent, String name, String text, int spc)
          Adds the nested element with tag name name and with nested text text to the parent node parent.
static void addNestedTextToElement(Element el, String text)
           
static void endElement(Element el, int spc)
          Terminates the nested element el.
static String formatNodeName(Node node)
          Formats a string representing the name of this node node in the XML document, in a XPath-like format.
static String formatNodeValue(Node node, int maxLength)
          Formats the value of the node node with maximal string length maxLength.
static String getIndent(Node node, int spc)
          Returns a string of spaces to indent future nested elements of node, using spc spaces for each indentation level.
static int getNodeIndex(Node node)
          Returns the index of the child node node for its parent.
static boolean nodeHasSiblings(Node node)
          Determines if the node node has at least one sibling.
static void reindent(Node node, int spc)
          Adds newlines and whitespaces for the node node to be indented in an XML output file.
static void unindent(Node node)
          Suppresses any indenting text node from the DOM node node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getIndent

public static String getIndent(Node node,
                               int spc)
Returns a string of spaces to indent future nested elements of node, using spc spaces for each indentation level.

If node or its owner document are null or if the node is a document, the empty string is returned. Otherwise, a string of spc spaces is appended to the indentation that would be computed for the parent of node.

Parameters:
node - the node whose children must be indented.
spc - the number of spaces for each indentation level.
Returns:
the string of spaces.
Throws:
IllegalArgumentException - if spc is negative.

addNestedTextElement

public static Element addNestedTextElement(Node parent,
                                           String name,
                                           String text,
                                           int spc)
Adds the nested element with tag name name and with nested text text to the parent node parent. In the parent node, a text node whose contents is generated using getIndent(org.w3c.dom.Node, int) is added if spc is greater than 0. A new element is constructed and added to the parent. If spc is greater than 0, a text node containing a newline character is added to the parent. In the created element a text node containing text is added and the element is returned.

Parameters:
parent - the parent node.
name - the tag name of the new element.
text - the nested text.
spc - the number of spaces for each indentation level.
Returns:
the newly-created element.

addNestedTextToElement

public static void addNestedTextToElement(Element el,
                                          String text)

addNestedElement

public static Element addNestedElement(Node parent,
                                       String name,
                                       boolean empty,
                                       int spc)
This method is similar to addNestedTextElement(org.w3c.dom.Node, java.lang.String, java.lang.String, int) except that the created element with tag name name will not have nested text by default. If empty is true, no child node is added in the element. Otherwise, a newline is added if spc is greater than 0. This newline is added assuming that the new element will contain other elements.

Parameters:
parent - the parent node.
name - the tag name of the new element.
empty - if the element will be empty.
spc - the number of spaces for each level of indentation.
Returns:
the created element.

addNestedComment

public static Comment addNestedComment(Node parent,
                                       String text,
                                       int spc)
Creates a comment node in the element parent, with text text, using spc spaces per indentation level. Before the created and returned comment node, the method adds a text node containing the string returned by getIndent(org.w3c.dom.Node, int) to the parent. After the comment node, it adds a text node containing a newline if spc is greater than 0. In the comment text, any spaces or newlines at the beginning and the end of the string is removed. After each newline, the method adds the string returned by getIndent(org.w3c.dom.Node, int) folloed by spc spaces.

Parameters:
parent - the parent node.
text - the text of the comment.
spc - the number of spaces for each indentation level.
Returns:
the created comment node.

addNestedArrayElement

public static Element addNestedArrayElement(Node parent,
                                            String name,
                                            Object array,
                                            String[] rowNames,
                                            int spc)
Creates a new element with name name, with the contents of the array array, and adds it to node parent. It outputs an array intended to be read by ArrayParam.

The method uses addNestedElement(org.w3c.dom.Node, java.lang.String, boolean, int) to create the element and for each element in the array, it creates a row subelement containing the value. Before adding the row i using addNestedTextElement(org.w3c.dom.Node, java.lang.String, java.lang.String, int), if rowNames[i] is non-null, a comment containing rowNames[i] is added using addNestedComment(org.w3c.dom.Node, java.lang.String, int). Elements are extracted from the array using Array.get(java.lang.Object, int) and converted to String using StringConvert.numberToString(Number) for numeric types, and Object.toString() for other types. The given array must not contain null values. If an element in the array appears several times consecutively, as tested by Object.equals(java.lang.Object), a repeat attribute is added to the corresponding row subelement instead of repeating the value.

Parameters:
parent - the parent node.
name - the name of the created element.
array - the array being formatted.
rowNames - an array containing a name for each array element, or null.
spc - the number of spaces for each indentation level.
Returns:
the created array element.
Throws:
IllegalArgumentException - if array is not an instance of an array class.

addArrayToElement

public static void addArrayToElement(Element el,
                                     Object array,
                                     String[] rowNames,
                                     int spc)

addNestedArrayElement

public static Element addNestedArrayElement(Node parent,
                                            String name,
                                            Object array,
                                            int spc)
Equivalent to addNestedArrayElement (parent, name, array, null, spc). This adds an array element with no comments describing rows.

Parameters:
parent - the parent node.
name - the name of the created element.
array - the array being formatted.
spc - the number of spaces for each indentation level.
Returns:
the created array element.
Throws:
IllegalArgumentException - if array is not an instance of an array class.

addNestedArray2DElement

public static Element addNestedArray2DElement(Node parent,
                                              String name,
                                              Object array2D,
                                              String[] rowNames,
                                              int spc)
Creates a new element with name name, with the contents of the 2D array array2D, and adds it to node parent. It outputs a 2D array intended to be read by ArrayParam2D.

The method uses addNestedElement(org.w3c.dom.Node, java.lang.String, boolean, int) to create the element and for each row in the 2D array, it creates a row subelement containing the array values. Before adding the row i using addNestedTextElement(org.w3c.dom.Node, java.lang.String, java.lang.String, int), if rowNames[i] is non-null, a comment containing rowNames[i] is added using addNestedComment(org.w3c.dom.Node, java.lang.String, int). Each row of the 2D array corresponds to a 1D array. Each row element contains a comma-separated list of array values. Each value is formatted with StringConvert.numberToString(Number) for numeric types, or Object.toString() for other types. If consecutive rows contain the same number of columns and the same elements, as tested with Object.equals(java.lang.Object), only one row element is added to represent the repeated row, using the repeat attribute.

Parameters:
parent - the parent node.
name - the name of the created element.
array2D - the 2D array being formatted.
rowNames - an array containing a name associated with each row, or null.
spc - the number of spaces for each indentation level.
Returns:
the created matrix element.
Throws:
IllegalArgumentException - if matrix is not an instance of a 2D array class.

addArray2DToElement

public static void addArray2DToElement(Element el,
                                       Object array2D,
                                       String[] rowNames,
                                       int spc)

addNestedArray2DElement

public static Element addNestedArray2DElement(Node parent,
                                              String name,
                                              Object array2D,
                                              int spc)
Equivalent to addNestedArray2DElement (parent, name, array2D, null, spc). This adds a 2D array element with no comments describing rows.

Parameters:
parent - the parent node.
name - the name of the created element.
array2D - the 2D array being formatted.
spc - the number of spaces for each indentation level.
Returns:
the created matrix element.
Throws:
IllegalArgumentException - if matrix is not an instance of a 2D array class.

endElement

public static void endElement(Element el,
                              int spc)
Terminates the nested element el. This method uses getIndent(org.w3c.dom.Node, int) to add a text node composed of spaces in the element. This allows the closing tag of the element to appear at the same indentation level as the opening tag.

Parameters:
el - the terminated element.
spc - the number of spaces for each indentation level.

unindent

public static void unindent(Node node)
Suppresses any indenting text node from the DOM node node. This recursively removes any child text node containing only newlines and spaces. After the cleanup process, the node is normalized using Node.normalize().

Parameters:
node - the node (or document) being unindented.

reindent

public static void reindent(Node node,
                            int spc)
Adds newlines and whitespaces for the node node to be indented in an XML output file. For each child element of node, an indent string obtained with getIndent (node, spc) is prepended and a newline is appended.

Parameters:
node - the node being reindented.
spc - the number of spaces for each indentation level.

formatNodeName

public static String formatNodeName(Node node)
Formats a string representing the name of this node node in the XML document, in a XPath-like format. If the given node is an attribute, the string [@name], where name is the attribute name, is appended to the return value of this method for its owner element. The format of the string for an element is given by [parent/]tagname(index), where parent is the result of this method for the parent node, tagname is the name of the element and index is the return value of getNodeIndex(org.w3c.dom.Node). If the node has no sibling, as tested by nodeHasSiblings(org.w3c.dom.Node), the index as well as the parentheses are omitted.

Parameters:
node - the node name.
Returns:
the string representation.

nodeHasSiblings

public static boolean nodeHasSiblings(Node node)
Determines if the node node has at least one sibling.

Parameters:
node - the tested node.
Returns:
true if the node has at least a previous or a next sibling, false otherwise.

getNodeIndex

public static int getNodeIndex(Node node)
Returns the index of the child node node for its parent.

Parameters:
node - the queried node.
Returns:
the index of the node.

formatNodeValue

public static String formatNodeValue(Node node,
                                     int maxLength)
Formats the value of the node node with maximal string length maxLength. The method first gets the result of node.getNodeValue() If this result is null, it returns null. Otherwise, if the length of the string is smaller than maxLength, the string is returned unchanged. Otherwise, it is truncated to maxLength and ... is appended to the result.

Parameters:
node - the node to be processed.
Returns:
the formatted value.

ContactCenters
V. 0.9.9.

To submit a bug or ask questions, send an e-mail to Richard Simard.