de.caff.io.xml

## Class XmlTool

- java.lang.Object
- - de.caff.io.xml.XmlTool

-     public class XmlTool
      extends java.lang.Object

  Helper methods for XML handling.

  This provides methods for both SAX and DOM handling.

  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `RELEASE_DATE` The current version of the library.
    `static java.lang.String` | `XML_ATTR_VERSION` Version attribute which should be used in a lot of cases.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `checkTagAndVersion(org.w3c.dom.Element element, java.lang.String tag, int maxVersion)` Check that the given element has a defined tag name and contains an integer `version` attribute which is not higher than a given number.
    `static int` | `checkTagAndVersion(org.w3c.dom.Element element, java.lang.String tag, int minVersion, int maxVersion)` Check that the given element has a defined tag name and contains an integer `version` attribute which is inside a given range.
    `static boolean` | `getBooleanValue(org.w3c.dom.Element element, java.lang.String attributeName)` Get a boolean value from an attribute.
    `static boolean` | `getBooleanValue(org.w3c.dom.Element element, java.lang.String attributeName, boolean fallback)` Get an optional boolean value from an attribute.
    `static boolean` | `getBooleanValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName)` Get a boolean value from an attribute.
    `static boolean` | `getBooleanValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, boolean fallback)` Get an optional boolean value from an attribute.
    `static java.util.List<org.w3c.dom.Element>` | `getChildElements(org.w3c.dom.Element element, java.lang.String tagName)` Get the child elements with a given name.
    `static Indexable<org.w3c.dom.Element>` | `getChildren(org.w3c.dom.Element element, java.lang.String subElementTag)` Get the direct children of an element with a given tag.
    `static Indexable<org.w3c.dom.Element>` | `getChildren(org.w3c.dom.Element element, java.lang.String subElementTag, int requiredSize)` Get the direct children of an element with a given tag.
    `static java.lang.String` | `getContent(org.w3c.dom.Element element, boolean forceNonEmpty)` Get the text content of the given element.
    `static double` | `getDoubleValue(org.w3c.dom.Element element, java.lang.String attributeName)` Get a double value from an attribute.
    `static double` | `getDoubleValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName)` Get a double value from an attribute.
    `static double` | `getDoubleValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, double fallback)` Get an optional double value from an attribute.
    `static <E extends java.lang.Enum<E>> E` | `getEnumValue(org.w3c.dom.Element element, java.lang.String attributeName, java.lang.Class<E> enumClass)` Get an enum value from an attribute.
    `static <E extends java.lang.Enum<E>> E` | `getEnumValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, java.lang.Class<E> enumClass)` Get an enum value from an attribute.
    `static int` | `getIntValue(org.w3c.dom.Element element, java.lang.String attributeName)` Get an integer value from an attribute.
    `static int` | `getIntValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName)` Get an integer value from an attribute.
    `static int` | `getIntValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, int fallback)` Get an optional integer value from an attribute.
    `static org.w3c.dom.Element` | `getOptionalSingleChild(org.w3c.dom.Element element, java.lang.String subElementTag)` Get a optional singular sub element from a given element.
    `static java.lang.String` | `getOptionalValue(org.xml.sax.Attributes attributes, java.lang.String attributeName)` Get the value of an optional attribute.
    `static <T> T` | `getOptionalValue(org.xml.sax.Attributes attributes, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor)` Get an unwrapped value from an attribute.
    `static java.lang.String` | `getOptionalValue(org.w3c.dom.Element element, java.lang.String attributeName)` Get the value of an optional attribute of the given element.
    `static <T> T` | `getOptionalValue(org.w3c.dom.Element element, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor)` Get a unwrapped value from an attribute.
    `static <T,E extends java.lang.Exception> T` | `getOptionalValueF(org.xml.sax.Attributes attributes, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor)` Get a unwrapped value from an attribute.
    `static <T,E extends java.lang.Exception> T` | `getOptionalValueF(org.w3c.dom.Element element, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor)` Get a unwrapped value from an attribute.
    `static org.w3c.dom.Element` | `getSingleChild(org.w3c.dom.Element element)` Get the single child of an element, require that it is an element itself.
    `static org.w3c.dom.Element` | `getSingleChild(org.w3c.dom.Element element, java.lang.String subElementTag)` Get a singular sub element from a given element.
    `static java.lang.Boolean` | `getTriStateValue(org.w3c.dom.Element element, java.lang.String attributeName)` Get a tri-state boolean value from an attribute.
    `static java.lang.Boolean` | `getTriStateValue(org.w3c.dom.Element element, java.lang.String attributeName, java.lang.Boolean fallback)` Get a tri-state optional boolean value from an attribute.
    `static java.lang.Boolean` | `getTriStateValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName)` Get a tri-state boolean value from an attribute.
    `static java.lang.Boolean` | `getTriStateValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, java.lang.Boolean fallback)` Get an optional tri-state boolean value from an attribute.
    `static java.lang.String` | `getValue(org.xml.sax.Attributes attributes, java.lang.String attributeName, java.lang.String defaultValue)` Get the value of the attribute of the given element.
    `static java.lang.String` | `getValue(org.w3c.dom.Element element, java.lang.String attributeName)` Get the value of the attribute of the given element.
    `static <T> T` | `getValue(org.w3c.dom.Element element, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor)` Get a unwrapped value from an attribute.
    `static java.lang.String` | `getValue(org.w3c.dom.Element element, java.lang.String attributeName, java.lang.String defaultValue)` Get the value of the attribute of the given element.
    `static java.lang.String` | `getValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName)` Get the value from attributes.
    `static <T> T` | `getValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor)` /** Get a unwrapped value from an attribute.
    `static <T,E extends java.lang.Exception> T` | `getValueF(org.w3c.dom.Element element, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor)` Get a unwrapped value from an attribute.
    `static <T,E extends java.lang.Exception> T` | `getValueF(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor)` Get a unwrapped value from an attribute.
    `static org.w3c.dom.Document` | `loadFromFile(java.io.File path)` Load a document from a file.
    `static org.w3c.dom.Document` | `loadFromFile(java.lang.String path)` Load a document from a file or URL.
    `static org.w3c.dom.Document` | `loadFromSource(org.xml.sax.InputSource inputSource)` Load a document from a generic input source.
    `static org.w3c.dom.Document` | `loadFromText(java.lang.String xmlText)` Load a document from a text string.

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

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

- - ### Field Detail

    - #### RELEASE_DATE

          public static final java.lang.String RELEASE_DATE

      The current version of the library.

    - #### XML_ATTR_VERSION

          public static final java.lang.String XML_ATTR_VERSION

      Version attribute which should be used in a lot of cases. Use an integer as version indicator, then it is possible to use checkTagAndVersion(Element, String, int, int) and checkTagAndVersion(Element, String, int) to run a fast version check. It is recommended to start versions with `1` which allows to usage of the shorter check method.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getValue

          @NotNull
          public static java.lang.String getValue(@NotNull
                                                           org.w3c.dom.Element element,
                                                           @NotNull
                                                           java.lang.String attributeName)
                                                    throws org.xml.sax.SAXException

      Get the value of the attribute of the given element. Throw an exception if it does not exist.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent

    - #### getOptionalValue

          @Nullable
          public static java.lang.String getOptionalValue(@NotNull
                                                                    org.w3c.dom.Element element,
                                                                    @NotNull
                                                                    java.lang.String attributeName)

      Get the value of an optional attribute of the given element.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
      Returns:
        value of attribute, or `null` if the attribute does not exist

    - #### getValue

          public static <T> T getValue(@NotNull
                                       org.w3c.dom.Element element,
                                       @NotNull
                                       java.lang.String attributeName,
                                       @NotNull
                                       java.util.function.Function<java.lang.String,? extends T> extractor)
                                throws org.xml.sax.SAXException

      Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.
      Type Parameters:
        `T` - result type of this method
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - when the attribute does not exist, or when the extractor throws

    - #### getValueF

          public static <T,E extends java.lang.Exception> T getValueF(@NotNull
                                                                      org.w3c.dom.Element element,
                                                                      @NotNull
                                                                      java.lang.String attributeName,
                                                                      @NotNull
                                                                      FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                               throws org.xml.sax.SAXException

      Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-
      Type Parameters:
        `T` - result type of this method
        `E` - exception type of extractor
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type which may throw an exception
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - when the attribute does not exist, or when the extractor throws an exception

    - #### getOptionalValue

          @Nullable
          public static <T> T getOptionalValue(@NotNull
                                                         org.w3c.dom.Element element,
                                                         @NotNull
                                                         java.lang.String attributeName,
                                                         @NotNull
                                                         java.util.function.Function<java.lang.String,? extends T> extractor)

      Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.
      Type Parameters:
        `T` - result type of this method
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type
      Returns:
        value of attribute, or `null` if the value does not exist

    - #### getOptionalValueF

          @Nullable
          public static <T,E extends java.lang.Exception> T getOptionalValueF(@NotNull
                                                                                        org.w3c.dom.Element element,
                                                                                        @NotNull
                                                                                        java.lang.String attributeName,
                                                                                        @NotNull
                                                                                        FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                                                 throws E extends java.lang.Exception

      Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-
      Type Parameters:
        `T` - result type of this method
        `E` - exception type of extractor
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type
      Returns:
        value of attribute, or `null` if the value does not exist
      Throws:
        `E` - when the extractor throws an exception
        `E extends java.lang.Exception`

    - #### getValue

          @NotNull
          public static java.lang.String getValue(@NotNull
                                                           org.w3c.dom.Element element,
                                                           @NotNull
                                                           java.lang.String attributeName,
                                                           @NotNull
                                                           java.lang.String defaultValue)

      Get the value of the attribute of the given element. Give back a default value if it does not exist.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `defaultValue` - default value
      Returns:
        value of attribute, or default value

    - #### getIntValue

          public static int getIntValue(@NotNull
                                        org.w3c.dom.Element element,
                                        @NotNull
                                        java.lang.String attributeName)
                                 throws org.xml.sax.SAXException

      Get an integer value from an attribute.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not an integer value

    - #### getDoubleValue

          public static double getDoubleValue(@NotNull
                                              org.w3c.dom.Element element,
                                              @NotNull
                                              java.lang.String attributeName)
                                       throws org.xml.sax.SAXException

      Get a double value from an attribute. This expects double to be in US format.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not a double value

    - #### getBooleanValue

          public static boolean getBooleanValue(@NotNull
                                                org.w3c.dom.Element element,
                                                @NotNull
                                                java.lang.String attributeName)
                                         throws org.xml.sax.SAXException

      Get a boolean value from an attribute.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
      Returns:
        boolean value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not a boolean value

    - #### getBooleanValue

          public static boolean getBooleanValue(@NotNull
                                                org.w3c.dom.Element element,
                                                @NotNull
                                                java.lang.String attributeName,
                                                boolean fallback)
                                         throws org.xml.sax.SAXException

      Get an optional boolean value from an attribute.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `fallback` - default value returned if attribute is not set
      Returns:
        boolean value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is not a boolean value

    - #### getTriStateValue

          @Nullable
          public static java.lang.Boolean getTriStateValue(@NotNull
                                                                     org.w3c.dom.Element element,
                                                                     @NotNull
                                                                     java.lang.String attributeName)
                                                              throws org.xml.sax.SAXException

      Get a tri-state boolean value from an attribute.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
      Returns:
        tri-state boolean value of attribute, `null` for undefined
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not a boolean value

    - #### getTriStateValue

          @Nullable
          public static java.lang.Boolean getTriStateValue(@NotNull
                                                                     org.w3c.dom.Element element,
                                                                     @NotNull
                                                                     java.lang.String attributeName,
                                                                     @Nullable
                                                                     java.lang.Boolean fallback)
                                                              throws org.xml.sax.SAXException

      Get a tri-state optional boolean value from an attribute.
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `fallback` - default value returned if attribute is not set
      Returns:
        tri-state boolean value of attribute, `null` for undefined
      Throws:
        `org.xml.sax.SAXException` - if attribute is not a boolean value

    - #### getEnumValue

          @NotNull
          public static <E extends java.lang.Enum<E>> E getEnumValue(@NotNull
                                                                              org.w3c.dom.Element element,
                                                                              @NotNull
                                                                              java.lang.String attributeName,
                                                                              @NotNull
                                                                              java.lang.Class<E> enumClass)
                                                                       throws org.xml.sax.SAXException

      Get an enum value from an attribute.
      Type Parameters:
        `E` - enum type
      Parameters:
        `element` - element containing attribute
        `attributeName` - name of attribute
        `enumClass` - enum class
      Returns:
        enum of given type
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not an enum of the given type

    - #### getValue

          @NotNull
          public static java.lang.String getValue(@NotNull
                                                           java.lang.String elementTag,
                                                           @NotNull
                                                           org.xml.sax.Attributes attributes,
                                                           @NotNull
                                                           java.lang.String attributeName)
                                                    throws org.xml.sax.SAXException

      Get the value from attributes. Throw an exception if it does not exist.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent

    - #### getValue

          @NotNull
          public static java.lang.String getValue(@NotNull
                                                           org.xml.sax.Attributes attributes,
                                                           @NotNull
                                                           java.lang.String attributeName,
                                                           @NotNull
                                                           java.lang.String defaultValue)

      Get the value of the attribute of the given element. Give back a default value if it does not exist.
      Parameters:
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `defaultValue` - default value
      Returns:
        value of attribute, or default value

    - #### getIntValue

          public static int getIntValue(@NotNull
                                        java.lang.String elementTag,
                                        @NotNull
                                        org.xml.sax.Attributes attributes,
                                        @NotNull
                                        java.lang.String attributeName)
                                 throws org.xml.sax.SAXException

      Get an integer value from an attribute.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not an integer value

    - #### getIntValue

          public static int getIntValue(@NotNull
                                        java.lang.String elementTag,
                                        @NotNull
                                        org.xml.sax.Attributes attributes,
                                        @NotNull
                                        java.lang.String attributeName,
                                        int fallback)
                                 throws org.xml.sax.SAXException

      Get an optional integer value from an attribute.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `fallback` - fallback value used if attribute is not defined
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is not an integer value

    - #### getDoubleValue

          public static double getDoubleValue(@NotNull
                                              java.lang.String elementTag,
                                              @NotNull
                                              org.xml.sax.Attributes attributes,
                                              @NotNull
                                              java.lang.String attributeName)
                                       throws org.xml.sax.SAXException

      Get a double value from an attribute. This expects double to be in US format.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not a double value

    - #### getDoubleValue

          public static double getDoubleValue(@NotNull
                                              java.lang.String elementTag,
                                              @NotNull
                                              org.xml.sax.Attributes attributes,
                                              @NotNull
                                              java.lang.String attributeName,
                                              double fallback)
                                       throws org.xml.sax.SAXException

      Get an optional double value from an attribute. This expects double to be in US format.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `fallback` - fallback value returned if attribute is not defined
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is not a double value

    - #### getBooleanValue

          public static boolean getBooleanValue(@NotNull
                                                java.lang.String elementTag,
                                                @NotNull
                                                org.xml.sax.Attributes attributes,
                                                @NotNull
                                                java.lang.String attributeName)
                                         throws org.xml.sax.SAXException

      Get a boolean value from an attribute.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
      Returns:
        boolean value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not a boolean value

    - #### getBooleanValue

          public static boolean getBooleanValue(@NotNull
                                                java.lang.String elementTag,
                                                @NotNull
                                                org.xml.sax.Attributes attributes,
                                                @NotNull
                                                java.lang.String attributeName,
                                                boolean fallback)
                                         throws org.xml.sax.SAXException

      Get an optional boolean value from an attribute.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `fallback` - default value returned if attribute is not set
      Returns:
        boolean value of attribute
      Throws:
        `org.xml.sax.SAXException` - if attribute is not a boolean value

    - #### getTriStateValue

          @Nullable
          public static java.lang.Boolean getTriStateValue(@NotNull
                                                                     java.lang.String elementTag,
                                                                     @NotNull
                                                                     org.xml.sax.Attributes attributes,
                                                                     @NotNull
                                                                     java.lang.String attributeName)
                                                              throws org.xml.sax.SAXException

      Get a tri-state boolean value from an attribute.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
      Returns:
        tri-state boolean value of attribute, `null` if undefined
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not a boolean value

    - #### getTriStateValue

          @Nullable
          public static java.lang.Boolean getTriStateValue(@NotNull
                                                                     java.lang.String elementTag,
                                                                     @NotNull
                                                                     org.xml.sax.Attributes attributes,
                                                                     @NotNull
                                                                     java.lang.String attributeName,
                                                                     @Nullable
                                                                     java.lang.Boolean fallback)
                                                              throws org.xml.sax.SAXException

      Get an optional tri-state boolean value from an attribute.
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `fallback` - default value returned if attribute is not set
      Returns:
        tri-state boolean value of attribute, `null` if undefined
      Throws:
        `org.xml.sax.SAXException` - if attribute is not a boolean value

    - #### getEnumValue

          @NotNull
          public static <E extends java.lang.Enum<E>> E getEnumValue(@NotNull
                                                                              java.lang.String elementTag,
                                                                              @NotNull
                                                                              org.xml.sax.Attributes attributes,
                                                                              @NotNull
                                                                              java.lang.String attributeName,
                                                                              @NotNull
                                                                              java.lang.Class<E> enumClass)
                                                                       throws org.xml.sax.SAXException

      Get an enum value from an attribute.
      Type Parameters:
        `E` - enum type
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `enumClass` - enum class
      Returns:
        enum of given type
      Throws:
        `org.xml.sax.SAXException` - if attribute is non-existent or not an enum of the given type

    - #### getValue

          public static <T> T getValue(@NotNull
                                       java.lang.String elementTag,
                                       @NotNull
                                       org.xml.sax.Attributes attributes,
                                       @NotNull
                                       java.lang.String attributeName,
                                       @NotNull
                                       java.util.function.Function<java.lang.String,? extends T> extractor)
                                throws org.xml.sax.SAXException

      /** Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.
      Type Parameters:
        `T` - result type of this method
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - when the attribute does not exist, or when the extractor throws

    - #### getValueF

          public static <T,E extends java.lang.Exception> T getValueF(@NotNull
                                                                      java.lang.String elementTag,
                                                                      @NotNull
                                                                      org.xml.sax.Attributes attributes,
                                                                      @NotNull
                                                                      java.lang.String attributeName,
                                                                      @NotNull
                                                                      FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                               throws org.xml.sax.SAXException

      Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-
      Type Parameters:
        `T` - result type of this method
        `E` - exception type of extractor
      Parameters:
        `elementTag` - element tag, used for errors
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type which throws an exception
      Returns:
        value of attribute
      Throws:
        `org.xml.sax.SAXException` - when the attribute does not exist, or when the extractor throws an exception

    - #### getOptionalValue

          @Nullable
          public static java.lang.String getOptionalValue(@NotNull
                                                                    org.xml.sax.Attributes attributes,
                                                                    @NotNull
                                                                    java.lang.String attributeName)

      Get the value of an optional attribute.
      Parameters:
        `attributes` - attributes of XML element
        `attributeName` - name of requested attribute
      Returns:
        attribute value, or `null` if attribute is not set

    - #### getOptionalValue

          @Nullable
          public static <T> T getOptionalValue(@NotNull
                                                         org.xml.sax.Attributes attributes,
                                                         @NotNull
                                                         java.lang.String attributeName,
                                                         @NotNull
                                                         java.util.function.Function<java.lang.String,? extends T> extractor)

      Get an unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.
      Type Parameters:
        `T` - result type of this method
      Parameters:
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type
      Returns:
        value of attribute, or `null` if the value does not exist

    - #### getOptionalValueF

          @Nullable
          public static <T,E extends java.lang.Exception> T getOptionalValueF(@NotNull
                                                                                        org.xml.sax.Attributes attributes,
                                                                                        @NotNull
                                                                                        java.lang.String attributeName,
                                                                                        @NotNull
                                                                                        FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                                                 throws E extends java.lang.Exception

      Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-
      Type Parameters:
        `T` - result type of this method
        `E` - exception type of extractor
      Parameters:
        `attributes` - attributes of XML element
        `attributeName` - name of attribute
        `extractor` - converter from the textual value to the expected value type
      Returns:
        value of attribute, or `null` if the value does not exist
      Throws:
        `E` - when the extractor throws an exception
        `E extends java.lang.Exception`

    - #### getSingleChild

          @NotNull
          public static org.w3c.dom.Element getSingleChild(@NotNull
                                                                    org.w3c.dom.Element element)
                                                             throws org.xml.sax.SAXException

      Get the single child of an element, require that it is an element itself.
      Parameters:
        `element` - parent element
      Returns:
        single child element
      Throws:
        `org.xml.sax.SAXException` - if there is none or more than one child, or the single child is not an element

    - #### getSingleChild

          @NotNull
          public static org.w3c.dom.Element getSingleChild(@NotNull
                                                                    org.w3c.dom.Element element,
                                                                    @NotNull
                                                                    java.lang.String subElementTag)
                                                             throws org.xml.sax.SAXException

      Get a singular sub element from a given element. This will throw an exception if there is no given sub elements or if there are more than one.
      Parameters:
        `element` - element containing sub element
        `subElementTag` - name of sub element
      Returns:
        sub element
      Throws:
        `org.xml.sax.SAXException` - if sub element is missing or appearing more than once

    - #### getOptionalSingleChild

          @Nullable
          public static org.w3c.dom.Element getOptionalSingleChild(@NotNull
                                                                             org.w3c.dom.Element element,
                                                                             @NotNull
                                                                             java.lang.String subElementTag)
                                                                      throws org.xml.sax.SAXException

      Get a optional singular sub element from a given element. This will throw an exception if there are more than one.
      Parameters:
        `element` - element containing sub element
        `subElementTag` - name of sub element
      Returns:
        sub element, `null` if there is none
      Throws:
        `org.xml.sax.SAXException` - if sub element is missing or appearing more than once

    - #### getChildren

          @NotNull
          public static Indexable<org.w3c.dom.Element> getChildren(@NotNull
                                                                            org.w3c.dom.Element element,
                                                                            @NotNull
                                                                            java.lang.String subElementTag)
                                                                     throws org.xml.sax.SAXException

      Get the direct children of an element with a given tag.
      Parameters:
        `element` - element for which children are requested
        `subElementTag` - sub element tag
      Returns:
        indexable view of the elements
      Throws:
        `org.xml.sax.SAXException` - if the required size is non-negative and not matched
      See Also:
        `getChildren(Element, String, int)`

    - #### getChildren

          @NotNull
          public static Indexable<org.w3c.dom.Element> getChildren(@NotNull
                                                                            org.w3c.dom.Element element,
                                                                            @NotNull
                                                                            java.lang.String subElementTag,
                                                                            int requiredSize)
                                                                     throws org.xml.sax.SAXException

      Get the direct children of an element with a given tag.
      Parameters:
        `element` - element for which children are requested
        `subElementTag` - sub element tag
        `requiredSize` - required and checked size if non-negative, ignored if negative
      Returns:
        indexable view of the elements
      Throws:
        `org.xml.sax.SAXException` - if the required size is non-negative and not matched

    - #### getContent

          @NotNull
          public static java.lang.String getContent(@NotNull
                                                             org.w3c.dom.Element element,
                                                             boolean forceNonEmpty)
                                                      throws org.xml.sax.SAXException

      Get the text content of the given element. This will throw an exception if the element does not have any content, or if it has sub elements.
      Parameters:
        `element` - element containing content
        `forceNonEmpty` - force that element tag is not empty, i.e. <tag/%gt;?
      Returns:
        content of element
      Throws:
        `org.xml.sax.SAXException` - if there are other nodes than text or attribute, or if `forceContent` is `true` and the element uses an empty element tag

    - #### getChildElements

          @NotNull
          public static java.util.List<org.w3c.dom.Element> getChildElements(@NotNull
                                                                                      org.w3c.dom.Element element,
                                                                                      @NotNull
                                                                                      java.lang.String tagName)

      Get the child elements with a given name.
      Parameters:
        `element` - element for which child elements are requested
        `tagName` - tag name of requested children
      Returns:
        list of child elements using the given tag name

    - #### loadFromSource

          @NotNull
          public static org.w3c.dom.Document loadFromSource(@NotNull
                                                                     org.xml.sax.InputSource inputSource)
                                                              throws javax.xml.parsers.ParserConfigurationException,
                                                                     java.io.IOException,
                                                                     org.xml.sax.SAXException

      Load a document from a generic input source.
      Parameters:
        `inputSource` - inputSource, providing XML data in text form
      Returns:
        document contained the source
      Throws:
        `javax.xml.parsers.ParserConfigurationException` - on parser config errors
        `java.io.IOException` - on read errors
        `org.xml.sax.SAXException` - on format errors

    - #### loadFromFile

          @NotNull
          public static org.w3c.dom.Document loadFromFile(@NotNull
                                                                   java.lang.String path)
                                                            throws javax.xml.parsers.ParserConfigurationException,
                                                                   java.io.IOException,
                                                                   org.xml.sax.SAXException

      Load a document from a file or URL.
      Parameters:
        `path` - path of XML file
      Returns:
        document contained in file
      Throws:
        `javax.xml.parsers.ParserConfigurationException` - on parser config errors
        `java.io.IOException` - on read errors
        `org.xml.sax.SAXException` - on format errors

    - #### loadFromFile

          @NotNull
          public static org.w3c.dom.Document loadFromFile(@NotNull
                                                                   java.io.File path)
                                                            throws javax.xml.parsers.ParserConfigurationException,
                                                                   java.io.IOException,
                                                                   org.xml.sax.SAXException

      Load a document from a file.
      Parameters:
        `path` - path of XML file
      Returns:
        document contained in file
      Throws:
        `javax.xml.parsers.ParserConfigurationException` - on parser config errors
        `java.io.IOException` - on read errors
        `org.xml.sax.SAXException` - on format errors

    - #### loadFromText

          @NotNull
          public static org.w3c.dom.Document loadFromText(@NotNull
                                                                   java.lang.String xmlText)
                                                            throws javax.xml.parsers.ParserConfigurationException,
                                                                   java.io.IOException,
                                                                   org.xml.sax.SAXException

      Load a document from a text string.
      Parameters:
        `xmlText` - textual representation of XML data
      Returns:
        document contained in data
      Throws:
        `javax.xml.parsers.ParserConfigurationException` - on parser config errors
        `java.io.IOException` - on read errors
        `org.xml.sax.SAXException` - on format errors

    - #### checkTagAndVersion

          public static int checkTagAndVersion(@NotNull
                                               org.w3c.dom.Element element,
                                               @NotNull
                                               java.lang.String tag,
                                               int maxVersion)
                                        throws org.xml.sax.SAXException

      Check that the given element has a defined tag name and contains an integer `version` attribute which is not higher than a given number. This method assumes that the minimal version number is `1`.
      Parameters:
        `element` - element to check
        `tag` - required tag name of the element
        `maxVersion` - required maximal version of the element
      Returns:
        the actual version found
      Throws:
        `org.xml.sax.SAXException` - if element has another tag name, no integer version attribute, or if the version is too high

    - #### checkTagAndVersion

          public static int checkTagAndVersion(@NotNull
                                               org.w3c.dom.Element element,
                                               @NotNull
                                               java.lang.String tag,
                                               int minVersion,
                                               int maxVersion)
                                        throws org.xml.sax.SAXException

      Check that the given element has a defined tag name and contains an integer `version` attribute which is inside a given range.
      Parameters:
        `element` - element to check
        `tag` - required tag name of the element
        `minVersion` - required minimal version of the element
        `maxVersion` - required maximal version of the element
      Returns:
        the actual version found
      Throws:
        `org.xml.sax.SAXException` - if element has another tag name, no integer version attribute, or if the version is too high