Package org.zkoss.idom.util

## Class IDOMs

- java.lang.Object
- - org.zkoss.idom.util.IDOMs

-     public class IDOMs
      extends java.lang.Object

  The iDOM relevant utilities.
  Author:
    tomyeh
  See Also:
    `Item`, `Group`

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `IDOMs()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static boolean` | `checkVersion​(Document doc, java.net.URL url)` | Returns whether the loaded document's version is correct.
    `static void` | `dumpTree​(java.io.PrintStream s, Group group)` | Print a readable tree of the specified group to the specified stream.
    `static void` | `dumpTree​(java.io.PrintWriter s, Group group)` | Print a readable tree of the specified group to the specified writer.
    `static void` | `dumpTree​(Group group)` | Print a readable tree of the specified group to System.out.
    `static Element` | `findElement​(java.util.List elems, java.lang.String name)` | Returns the first element whose sub-element called "name" has the same content as the name argument, or null if not found.
    `static void` | `format​(Element e)` | Formats the specified element for better readability by adding white spaces.
    `static Element` | `getFirstElement​(Group group)` | Returns the first child element, or null if no child element at all.
    `static java.lang.String` | `getRequiredAttributeValue​(Element e, java.lang.String attrnm)` | Returns the required attribute value.
    `static Element` | `getRequiredElement​(Element e, java.lang.String elemnm)` | Returns the required element.
    `static java.lang.String` | `getRequiredElementValue​(Element e, java.lang.String elemnm)` | Returns the required element value.
    `static java.util.Map<java.lang.String,​java.lang.String>` | `parseParams​(Element elm, java.lang.String type, java.lang.String name, java.lang.String value)` | Parses a tree of parameter elements into a map.
    `static void` | `setContents​(java.util.Collection<Element> elems, java.lang.Object val)` | Set the contents of elements.
    `static java.lang.Object` | `toContents​(java.lang.Object obj)` | Converts elements to their contents if the giving object is an element or an array or a collection of elements.
    `static java.lang.String` | `toString​(Document doc)` | Transforms a document to a string.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### IDOMs

          public IDOMs()

  - ### Method Detail

    - #### getRequiredElement

          public static final Element getRequiredElement​(Element e,
                                                         java.lang.String elemnm)
                                                  throws IllegalSyntaxException

      Returns the required element.
      Parameters:
        `elemnm` - the element name
      Throws:
        `IllegalSyntaxException`

    - #### getRequiredElementValue

          public static final java.lang.String getRequiredElementValue​(Element e,
                                                                       java.lang.String elemnm)
                                                                throws IllegalSyntaxException

      Returns the required element value.

      Note: the returned value may be an empty string (if the element contains no text at all).

      Throws:
        `IllegalSyntaxException` - if the element is not found

    - #### getRequiredAttributeValue

          public static final java.lang.String getRequiredAttributeValue​(Element e,
                                                                         java.lang.String attrnm)
                                                                  throws IllegalSyntaxException

      Returns the required attribute value.
      Throws:
        `IllegalSyntaxException` - if the element is not found

    - #### getFirstElement

          public static final Element getFirstElement​(Group group)

      Returns the first child element, or null if no child element at all.

    - #### findElement

          public static final Element findElement​(java.util.List elems,
                                                  java.lang.String name)

      Returns the first element whose sub-element called "name" has the same content as the name argument, or null if not found.
      Parameters:
        `elems` - a list of elements to look for the specified name

    - #### parseParams

          public static final java.util.Map<java.lang.String,​java.lang.String> parseParams​(Element elm,
                                                                                                 java.lang.String type,
                                                                                                 java.lang.String name,
                                                                                                 java.lang.String value)

      Parses a tree of parameter elements into a map.

      The tree of parameter elements is as follows.

           <type>
             <name>any</name>
             <vaue>any</vaue>
           </type>

      Returns:
        the map after parsed (never null). An empty map is returned if no parameter is defined. The map is in the same order of the element tree.

    - #### format

          public static void format​(Element e)

      Formats the specified element for better readability by adding white spaces.

    - #### toContents

          public static final java.lang.Object toContents​(java.lang.Object obj)

      Converts elements to their contents if the giving object is an element or an array or a collection of elements. One item of an collection might be another collection or array.

    - #### setContents

          public static final void setContents​(java.util.Collection<Element> elems,
                                               java.lang.Object val)

      Set the contents of elements. The val argument could be an array and a collection, and each item will be assigned to each of the list one-by-one.

      Unlike `toContents(java.lang.Object)`, it handles only a collection of elements -- all items must be elements.

      Parameters:
        `elems` - the collection of elements
        `val` - the value which could be an object, an array or a collection

    - #### toString

          public static final java.lang.String toString​(Document doc)
                                                 throws javax.xml.transform.TransformerConfigurationException,
                                                        javax.xml.transform.TransformerException

      Transforms a document to a string. The string is XML correct.
      Throws:
        `javax.xml.transform.TransformerConfigurationException`
        `javax.xml.transform.TransformerException`

    - #### dumpTree

          public static final void dumpTree​(Group group)

      Print a readable tree of the specified group to System.out. It is for debug purpose and the generated format is not XML. To generate XML, uses `Transformer` or `toString(org.zkoss.idom.Document)`.
      See Also:
        `toString(org.zkoss.idom.Document)`

    - #### dumpTree

          public static final void dumpTree​(java.io.PrintStream s,
                                            Group group)

      Print a readable tree of the specified group to the specified stream. It is for debug purpose and the generated format is not XML. To generate XML, uses `Transformer` or `toString(org.zkoss.idom.Document)`.
      See Also:
        `toString(org.zkoss.idom.Document)`

    - #### dumpTree

          public static final void dumpTree​(java.io.PrintWriter s,
                                            Group group)

      Print a readable tree of the specified group to the specified writer. It is for debug purpose and the generated format is not XML. To generate XML, uses `Transformer` or `toString(org.zkoss.idom.Document)`.
      See Also:
        `toString(org.zkoss.idom.Document)`

    - #### checkVersion

          public static boolean checkVersion​(Document doc,
                                             java.net.URL url)
                                      throws java.lang.Exception

      Returns whether the loaded document's version is correct.

      It assumes the version info is specified in the document in the following format:

          <version>
                  <version-class>org.zkoss.zul.Version</version-class>
                  <version-uid>3.0.0</version-uid>
          </version>

      Note: it returns true if the version info is not found.

      Parameters:
        `doc` - the document to check
        `url` - the URL used to show the readable message if the version doesn't match
      Throws:
        `java.lang.Exception`
      Since:
        3.0.0