Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## umontreal.iro.lecuyer.xmlconfig
Class DOMUtils

    java.lang.Object
      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.

Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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