de.caff.util.xml

## Class XmlTool

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

- Deprecated.
  use the classes in the package `de.caff.io` and `de.caff.io.xml` instead.

      @Deprecated
      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` Deprecated. The current version of the library.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.util.List<org.w3c.dom.Element>` | `getChildElements(org.w3c.dom.Element element, java.lang.String tagName)` Deprecated. Get the child elements with a given name.
    `static java.lang.String` | `getContent(org.w3c.dom.Element element, boolean forceNonEmpty)` Deprecated. Get the text content of the given element.
    `static double` | `getDoubleValue(org.w3c.dom.Element element, java.lang.String attributeName)` Deprecated. Get a double value from an attribute.
    `static double` | `getDoubleValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName)` Deprecated. Get a 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)` Deprecated. 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)` Deprecated. Get an enum value from an attribute.
    `static int` | `getIntValue(org.w3c.dom.Element element, java.lang.String attributeName)` Deprecated. Get an integer value from an attribute.
    `static int` | `getIntValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName)` Deprecated. Get an integer value from an attribute.
    `static org.w3c.dom.Element` | `getOptionalSingleChild(org.w3c.dom.Element element, java.lang.String subElementName)` Deprecated. Get a optional singular sub element from a given element.
    `static <T> T` | `getOptionalValue(org.xml.sax.Attributes attributes, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor)` Deprecated. Get a unwrapped value from an attribute.
    `static java.lang.String` | `getOptionalValue(org.w3c.dom.Element element, java.lang.String attributeName)` Deprecated. 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)` Deprecated. 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)` Deprecated. 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)` Deprecated. Get a unwrapped value from an attribute.
    `static org.w3c.dom.Element` | `getSingleChild(org.w3c.dom.Element element, java.lang.String subElementName)` Deprecated. Get a singular sub element from a given element.
    `static java.lang.String` | `getValue(org.xml.sax.Attributes attributes, java.lang.String attributeName, java.lang.String defaultValue)` Deprecated. Get the value of the attribute of the given element.
    `static java.lang.String` | `getValue(org.w3c.dom.Element element, java.lang.String attributeName)` Deprecated. 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)` Deprecated. Get an unwrapped value from an attribute.
    `static java.lang.String` | `getValue(org.w3c.dom.Element element, java.lang.String attributeName, java.lang.String defaultValue)` Deprecated. 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)` Deprecated. 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)` Deprecated. /** 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)` Deprecated. 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)` Deprecated. Get a unwrapped value from an attribute.
    `static org.w3c.dom.Document` | `loadFromFile(java.lang.String path)` Deprecated. Load a document from a file or URL.

    - ### 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

      Deprecated.
      The current version of the library.

  - ### 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

      Deprecated.
      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)

      Deprecated.
      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

      Deprecated.
      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:
        `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

      Deprecated.
      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)

      Deprecated.
      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

      Deprecated.
      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)

      Deprecated.
      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

      Deprecated.
      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

      Deprecated.
      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

    - #### 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

      Deprecated.
      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

      Deprecated.
      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)

      Deprecated.
      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

      Deprecated.
      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

    - #### 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

      Deprecated.
      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

    - #### 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

      Deprecated.
      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

      Deprecated.
      /** 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

      Deprecated.
      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 <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)

      Deprecated.
      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:
        `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

      Deprecated.
      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,
                                                                    @NotNull
                                                                    java.lang.String subElementName)
                                                             throws org.xml.sax.SAXException

      Deprecated.
      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
        `subElementName` - 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 subElementName)
                                                                      throws org.xml.sax.SAXException

      Deprecated.
      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
        `subElementName` - 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

    - #### getContent

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

      Deprecated.
      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)

      Deprecated.
      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

    - #### 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

      Deprecated.
      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