Package com.norconex.commons.lang.xml

# Class Xml

java.lang.Object
com.norconex.commons.lang.xml.Xml

All Implemented Interfaces:
  `Iterable<XmlCursor>`

public class Xml extends Object implements Iterable<XmlCursor>

XML DOM wrapper facilitating node querying and automatically creating, validating, and populating classes from/to XML, with support for `XmlConfigurable` and `JAXB`.

## XML syntax and white spaces

Some white spaces in element text may be removed when parsed. To keep them, add the XML standard attribute `xml:space="preserve"` to your element. For instance, the following ensures the four spaces are kept when parsed:

       <example xml:space="preserve">    </example>

Empty tags are interpreted as having an empty strings while self-closing tags have their value interpreted as `null`. Non-existing tags have no effect (when loading over an object, that object current value should remain unchanged).

Checked exceptions are wrapped into an `XmlException`.

Since:
  2.0.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `Xml.Builder`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Xml(File file)`
  Parse an XML file into an XML document, without consideration for namespaces.
  `Xml(Reader reader)`
  Parse an XML stream into an XML document, without consideration for namespaces.
  `Xml(String xml)`
  Parse an XML string into an XML document, without consideration for namespaces.
  `Xml(String rootElement, Object obj)`
  Creates a new XML with the supplied root element (i.e., tag name), and populate it with the supplied object.
  `Xml(Path file)`
  Parse an XML file into an XML document, without consideration for namespaces.
  `Xml(Node node)`
  Creates an XML with the given DOM node.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Xml`
  `addDelimitedElementList(String name, String delim, List<?> values)`
  Adds a list of values as a new element after joining them with the given delimiter.
  `Xml`
  `addDelimitedElementList(String name, List<?> values)`
  Adds a list of values as a new element after joining them with a comma (CSV).
  `Xml`
  `addElement(String tagName)`
  Adds an empty child element to this XML root element.
  `Xml`
  `addElement(String tagName, Object value)`
  Adds a child element to this XML root element.
  `Xml`
  `addElementList(@NonNull String parentTagName, String tagName, List<?> values)`
  Adds a list of values under a new parent tag name to the current XML and return the added list.
  `List<Xml>`
  `addElementList(String tagName, List<?> values)`
  Adds a list of values to the current XML and return the added list.
  `Xml`
  `addElementMap(String parentTagName, String tagName, String attributeName, Map<?,?> map)`
  Adds a `Map` as a series of elements with a parent element wrapping that group.
  `List<Xml>`
  `addElementMap(String tagName, String attributeName, Map<?,?> map)`
  Adds a `Map` as a series of elements without a parent element wrapping that group.
  `Xml`
  `addXML(Xml xml)`
  `Xml`
  `addXML(Reader xml)`
  `Xml`
  `addXML(String xml)`
  `static void`
  `assertWriteRead(Object object, String elementName)`
  Convenience class for testing that an object annotated with JAXB `XmlRootElement` or implementing `XmlConfigurable` (or both) can be written, and read back into an new instance that is equal as per `equals(Object)`.
  `void`
  `checkDeprecated(String deprecatedXPath, boolean throwException)`
  Checks whether a deprecated configuration entry (without replacement) was specified and log a warning or throw an `XmlException`.
  `void`
  `checkDeprecated(String deprecatedXPath, String replacement, boolean throwException)`
  Checks whether a deprecated configuration entry was specified and log a warning or throw an `XmlException`.
  `Xml`
  `clear()`
  Clears this XML by removing all its attributes and elements (i.e., making it an empty tag).
  `Xml`
  `computeElementIfAbsent(String tagName, Function<String,Object> function)`
  Computes and adds the element returned by the provided function if an element with the same name is not already present, else, return the existing one.
  `boolean`
  `contains(String xpathExpression)`
  `boolean`
  `equals(Object obj)`
  `void`
  `forEach(String xpathExpression, Consumer<Xml> action)`
  If the given expression matches one or more elements, consume those element one by one.
  `<T> T`
  `get(String xpathExpression, Class<T> type)`
  Gets the matching element/attribute, converted from string to the given type.
  `<T> T`
  `get(String xpathExpression, Class<T> type, T defaultValue)`
  Gets the matching element/attribute, converted from string to the given type.
  `Boolean`
  `getBoolean(String xpathExpression)`
  `Boolean`
  `getBoolean(String xpathExpression, Boolean defaultValue)`
  `Charset`
  `getCharset(String xpathExpression)`
  `Charset`
  `getCharset(String xpathExpression, Charset defaultValue)`
  `Class<?>`
  `getClass(String xpathExpression)`
  `<T> Class<T>`
  `getClass(String xpathExpression, Class<T> defaultValue)`
  `final <T> List<Class<T>>`
  `getClassList(String xpathExpression)`
  Gets values as a list of files.
  `final <T> List<Class<? extends T>>`
  `getClassList(String xpathExpression, List<Class<? extends T>> defaultValue)`
  Gets values as a list of files.
  `Long`
  `getDataSize(String xpathExpression)`
  Gets the size of a data expression, in bytes (e.g., 2KB, 1GiB, 3 megabytes, etc).
  `Long`
  `getDataSize(String xpathExpression, DataUnit targetUnit, Long defaultValue)`
  Gets the size of a data expression, in the specified target unit (e.g., 2KB, 1GiB, 3 megabytes, etc).
  `Long`
  `getDataSize(String xpathExpression, Long defaultValue)`
  Gets the size of a data expression, in bytes (e.g., 2KB, 1GiB, 3 megabytes, etc).
  `<E extends Enum<E>>
  List<E>`
  `getDelimitedEnumList(String xpathExpression, Class<E> enumClass, String delimRegex, List<E> defaultValues)`
  Gets a list of enum constants after splitting the matching node value(s) with the given delimiter regular expression.
  `<E extends Enum<E>>
  List<E>`
  `getDelimitedEnumList(String xpathExpression, Class<E> enumClass, List<E> defaultValues)`
  Gets a list of enum constants after splitting the matching node value(s) on commas (CSV).
  `<T> List<T>`
  `getDelimitedList(String xpathExpression, Class<T> type)`
  Gets a list of the given type after splitting the matching node value(s) on commas (CSV).
  `<T> List<T>`
  `getDelimitedList(String xpathExpression, Class<T> type, String delimRegex)`
  Gets a list of given type after splitting the matching node value(s) with the given delimiter regular expression.
  `<T> List<T>`
  `getDelimitedList(String xpathExpression, Class<T> type, String delimRegex, List<? extends T> defaultValues)`
  Gets a list of given type after splitting the matching node value(s) with the given delimiter regular expression.
  `<T> List<T>`
  `getDelimitedList(String xpathExpression, Class<T> type, List<T> defaultValues)`
  Gets a list of given type after splitting the matching node value(s) on commas (CSV).
  `List<String>`
  `getDelimitedStringList(String xpathExpression)`
  Gets a list of strings after splitting the matching node value(s) on commas (CSV).
  `List<String>`
  `getDelimitedStringList(String xpathExpression, String delimRegex)`
  Gets a list of strings after splitting the matching node value(s) with the given delimiter regular expression.
  `List<String>`
  `getDelimitedStringList(String xpathExpression, String delimRegex, List<String> defaultValues)`
  Gets a list of strings after splitting the matching node value(s) with the given delimiter regular expression.
  `List<String>`
  `getDelimitedStringList(String xpathExpression, List<String> defaultValues)`
  Gets a list of strings after splitting the matching node value(s) on commas (CSV).
  `Dimension`
  `getDimension(String xpathExpression)`
  `Dimension`
  `getDimension(String xpathExpression, Dimension defaultValue)`
  `DocumentBuilderFactory`
  `getDocumentBuilderFactory()`
  `Double`
  `getDouble(String xpathExpression)`
  `Double`
  `getDouble(String xpathExpression, Double defaultValue)`
  `Duration`
  `getDuration(String xpathExpression)`
  Gets a duration which can exists as a numerical value or a textual representation of a duration as per `DurationParser`.
  `Duration`
  `getDuration(String xpathExpression, Duration defaultValue)`
  Gets a duration which can exists as a numerical value or a textual representation of a duration as per `DurationParser`.
  `Long`
  `getDurationMillis(String xpathExpression)`
  Gets a duration in milliseconds which can exists as a numerical value or a textual representation of a duration as per `DurationParser`.
  `Long`
  `getDurationMillis(String xpathExpression, Long defaultValue)`
  Gets a duration in milliseconds which can exists as a numerical value or a textual representation of a duration as per `DurationParser`.
  `final <E extends Enum<E>>
  E`
  `getEnum(String xpathExpression, Class<E> enumClass)`
  Gets an Enum constant matching one of the constants in the provided Enum class, ignoring case.
  `final <E extends Enum<E>>
  E`
  `getEnum(String xpathExpression, Class<E> enumClass, E defaultValue)`
  Gets an Enum constant matching one of the constants in the provided Enum class, ignoring case.
  `<E extends Enum<E>>
  List<E>`
  `getEnumList(String xpathExpression, Class<E> enumClass, List<E> defaultValues)`
  Gets a list of enum constants.
  `ErrorHandler`
  `getErrorHandler()`
  `final File`
  `getFile(String xpathExpression)`
  Gets a file, assuming the node value is a file system path.
  `final File`
  `getFile(String xpathExpression, File defaultValue)`
  Gets a file, assuming the node value is a file system path.
  `final List<File>`
  `getFileList(String xpathExpression)`
  Gets values as a list of files.
  `final List<File>`
  `getFileList(String xpathExpression, List<File> defaultValue)`
  Gets values as a list of files.
  `Float`
  `getFloat(String xpathExpression)`
  `Float`
  `getFloat(String xpathExpression, Float defaultValue)`
  `Integer`
  `getInteger(String xpathExpression)`
  `Integer`
  `getInteger(String xpathExpression, Integer defaultValue)`
  `<T> List<? extends T>`
  `getList(String xpathExpression, Class<T> type)`
  Gets the matching list of elements/attributes, converted from string to the given type.
  `<T> List<? extends T>`
  `getList(String xpathExpression, Class<T> type, List<? extends T> defaultValues)`
  Gets the matching list of elements/attributes, converted from string to the given type.
  `Locale`
  `getLocale(String xpathExpression)`
  `Locale`
  `getLocale(String xpathExpression, Locale defaultValue)`
  `Long`
  `getLong(String xpathExpression)`
  `Long`
  `getLong(String xpathExpression, Long defaultValue)`
  `String`
  `getName()`
  `Node`
  `getNode()`
  `Node`
  `getNode(String xpathExpression)`
  `<T> T`
  `getObject(String xpathExpression)`
  Creates a new instance of the class represented by the "class" attribute on the node matching the expression.
  `<T> T`
  `getObject(String xpathExpression, T defaultObject)`
  Creates a new instance of the class represented by the "class" attribute on the node matching the expression.
  `<T> T`
  `getObjectImpl(Class<?> type, String xpathExpression)`
  Creates a new instance of the class represented by the "class" attribute on the node matching the expression.
  `<T> T`
  `getObjectImpl(Class<?> type, String xpathExpression, T defaultObject)`
  Creates a new instance of the class represented by the "class" attribute on the node matching the expression.
  `<T> List<T>`
  `getObjectList(String xpathExpression)`
  Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression.
  `<T> List<T>`
  `getObjectList(String xpathExpression, List<T> defaultObjects)`
  Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression.
  `<T> List<T>`
  `getObjectListImpl(Class<?> type, String xpathExpression)`
  Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression.
  `<T> List<T>`
  `getObjectListImpl(Class<?> type, String xpathExpression, List<T> defaultObjects)`
  Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression.
  `final Path`
  `getPath(String xpathExpression)`
  Gets a path, assuming the node value is a file system path.
  `final Path`
  `getPath(String xpathExpression, Path defaultValue)`
  Gets a path, assuming the node value is a file system path.
  `final List<Path>`
  `getPathList(String xpathExpression)`
  Gets values as a list of paths.
  `final List<Path>`
  `getPathList(String xpathExpression, List<Path> defaultValue)`
  Gets values as a list of paths.
  `Pattern`
  `getPattern(String xpathExpression)`
  Gets a regular expression pattern.
  `Pattern`
  `getPattern(String xpathExpression, Pattern defaultValue)`
  Gets a regular expression pattern.
  `String`
  `getString(String xpathExpression)`
  `String`
  `getString(String xpathExpression, String defaultValue)`
  `List<String>`
  `getStringList(String xpathExpression)`
  Gets the matching list of elements/attributes as strings.
  `List<String>`
  `getStringList(String xpathExpression, List<String> defaultValues)`
  Gets the matching list of elements/attributes as strings.
  `Map<String,String>`
  `getStringMap(String xpathList, String xpathKey, String xpathValue)`
  Gets the matching map of elements/attributes as strings.
  `Map<String,String>`
  `getStringMap(String xpathList, String xpathKey, String xpathValue, Map<String,String> defaultValues)`
  Gets the matching map of elements/attributes as strings.
  `String`
  `getTextContent()`
  Gets this XML direct text content, if any, joining multiple text nodes by a space separator.
  `final URL`
  `getURL(String xpathExpression)`
  `final URL`
  `getURL(String xpathExpression, URL defaultValue)`
  `final List<URL>`
  `getURLList(String xpathExpression)`
  `final List<URL>`
  `getURLList(String xpathExpression, List<URL> defaultValue)`
  `Xml`
  `getXML(String xpathExpression)`
  Gets the xml subset matching the xpath expression.
  `List<Xml>`
  `getXMLList(String xpathExpression)`
  Gets the XML subsets matching the xpath expression.
  `EnhancedXmlStreamWriter`
  `getXMLStreamWriter()`
  Deprecated.
  `Writer`
  `getXMLWriter()`
  `boolean`
  `hasAttributes()`
  Gets whether this XML element has any attributes.
  `boolean`
  `hasChildElements()`
  Gets whether this XML element has any child elements.
  `int`
  `hashCode()`
  `boolean`
  `hasTextContent()`
  Gets whether this XML has any text content.
  `void`
  `ifXML(String xpathExpression, Consumer<Xml> then)`
  If the given expression matches an element, consume that element.
  `Xml`
  `insertAfter(Xml newXML)`
  Inserts a new XML node after this one, as a sibling of a shared parent.
  `Xml`
  `insertBefore(Xml newXML)`
  Inserts a new XML node before this one, as a sibling of a shared parent.
  `boolean`
  `isDisabled()`
  `boolean`
  `isElementPresent(String xpathExpression)`
  Gets whether the given expression matches an existing element.
  `boolean`
  `isEmpty()`
  Gets whether this XML is empty.
  `boolean`
  `isEnabled()`
  `static boolean`
  `isJAXB(Object obj)`
  `static boolean`
  `isXMLConfigurable(Object obj)`
  `Iterator<XmlCursor>`
  `iterator()`
  Returns an `Iterator` of `XmlCursor` from this XML, in sequential order.
  `static Iterator<XmlCursor>`
  `iterator(Object obj)`
  Returns an `Iterator` of `XmlCursor` from the supplied XML object, in sequential order.
  `String`
  `join(String delim, List<?> values)`
  Deprecated.
  Will be removed or visibility reduced in a future release.
  `static XPath`
  `newXPath()`
  Deprecated.
  Use `XpathUtil.newXPath()` instead
  `static XPathExpression`
  `newXPathExpression(String expression)`
  Deprecated.
  Use `XpathUtil.newXPathExpression(String)` instead
  `static Xml.Builder`
  `of(File file)`
  `static Xml.Builder`
  `of(InputStream is)`
  `static Xml.Builder`
  `of(Reader reader)`
  `static Xml.Builder`
  `of(String xml)`
  `static Xml.Builder`
  `of(String rootElementName, Object object)`
  `static Xml.Builder`
  `of(Path path)`
  `static Xml.Builder`
  `of(Node node)`
  `<T> T`
  `parseXML(String xpathExpression, @NonNull Function<Xml,T> parser)`
  `<T> T`
  `parseXML(String xpathExpression, @NonNull Function<Xml,T> parser, T defaultValue)`
  `<T> List<T>`
  `parseXMLList(String xpathExpression, @NonNull Function<Xml,T> parser)`
  `<T> List<T>`
  `parseXMLList(String xpathExpression, @NonNull Function<Xml,T> parser, List<T> defaultValue)`
  `<K, V> Map<K,V>`
  `parseXMLMap(String xpathExpression, Function<Xml,Map.Entry<K,V>> parser)`
  `<K, V> Map<K,V>`
  `parseXMLMap(String xpathExpression, Function<Xml,Map.Entry<K,V>> parser, Map<K,V> defaultValue)`
  `void`
  `populate(Object targetObject)`
  Populates supplied object with this XML.
  `void`
  `populate(Object targetObject, String xpathExpression)`
  Populates supplied object with the XML matching the given expression.
  `Xml`
  `remove()`
  Removes itself from its XML parent (if any).
  `Xml`
  `removeAttribute(String name)`
  Removes an attribute on this XML element.
  `Xml`
  `removeElement(String tagName)`
  Removes an element from this XML.
  `Xml`
  `removeTextContent()`
  Removes this XML direct text content, without impact on attributes and child elements and their content.
  `Xml`
  `rename(String newName)`
  Rename this XML (element tag name).
  `Xml`
  `replace(Xml replacement)`
  Replaces the current XML with the provided one.
  `Xml`
  `setAttribute(String name, Object value)`
  Sets an attribute on this XML element, converting the supplied object to a string (enums are also converted to lowercase).
  `Xml`
  `setAttributes(Map<String,?> attribs)`
  Sets attributes on this XML element.
  `Xml`
  `setDelimitedAttributeList(String name, String delim, List<?> values)`
  Sets a list of values as an attribute after joining them with the given delimiter.
  `Xml`
  `setDelimitedAttributeList(String name, List<?> values)`
  Sets a list of values as an attribute after joining them with a comma (CSV).
  `Xml`
  `setTextContent(Object textContent)`
  Sets the direct text content of an XML element.
  `Stream<XmlCursor>`
  `stream()`
  Returns a `Stream` of `XmlCursor` from this XML, in sequential order.
  `static Stream<XmlCursor>`
  `stream(Object obj)`
  Returns a `Stream` of `XmlCursor` from the supplied XML object, in sequential order.
  `Node`
  `toNode()`
  `<T> T`
  `toObject()`
  Creates a new instance of the class represented by the "class" attribute on this XML root node.
  `<T> T`
  `toObject(T defaultObject)`
  Creates a new instance of the class represented by the "class" attribute on the given node.
  `<T> T`
  `toObjectImpl(Class<?> type)`
  Creates a new instance of the class represented by the "class" attribute on this XML root node.
  `<T> T`
  `toObjectImpl(Class<?> type, T defaultObject)`
  Creates a new instance of the class represented by the "class" attribute on the given node.
  `Reader`
  `toReader()`
  Creates a new `Reader` from a `Node`.
  `String`
  `toString()`
  Gets a string representation of this XML.
  `String`
  `toString(int indent)`
  Gets a string representation of this XML.
  `Xml`
  `unwrap()`
  Unwraps this XML by removing the root tag and keeping its child element (and its nested element).
  `void`
  `validate()`
  Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute.
  `void`
  `validate(Class<?> clazz)`
  Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute.
  `void`
  `validate(Object obj)`
  Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute.
  `Xml`
  `wrap(String parentName)`
  Wraps this XML by adding a parent element around it.
  `void`
  `write(File file)`
  `void`
  `write(File file, int indent)`
  `void`
  `write(Writer writer)`
  `void`
  `write(Writer writer, int indent)`

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Constructor Details

  - ### Xml

    public Xml(Path file)

    Parse an XML file into an XML document, without consideration for namespaces.

    Parameters:
      `file` - the XML file to parse
    See Also:
      - `of(Path)`

  - ### Xml

    public Xml(File file)

    Parse an XML file into an XML document, without consideration for namespaces.

    Parameters:
      `file` - the XML file to parse
    See Also:
      - `of(File)`

  - ### Xml

    public Xml(Reader reader)

    Parse an XML stream into an XML document, without consideration for namespaces.

    Parameters:
      `reader` - the XML stream to parse
    See Also:
      - `of(Reader)`

  - ### Xml

    public Xml(String xml)

    Parse an XML string into an XML document, without consideration for namespaces.

    The supplied "xml" string can either be a well-formed XML or a string without angle brackets. When the later is supplied, it is interpreted as the XML root element name (for a fresh XML).

    Parameters:
      `xml` - the XML string to parse
    See Also:
      - `of(String)`

  - ### Xml

    public Xml(String rootElement, Object obj)
    Creates a new XML with the supplied root element (i.e., tag name), and populate it with the supplied object.
    Parameters:
      `rootElement` - XML root element name
      `obj` - the object to populate this XML with.
    See Also:
      - `of(String, Object)`

  - ### Xml

    public Xml(Node node)

    Creates an XML with the given DOM node.

    Parameters:
      `node` - the node representing the XML

- ## Method Details

  - ### of

    public static Xml.Builder of(File file)

  - ### of

    public static Xml.Builder of(Path path)

  - ### of

    public static Xml.Builder of(Node node)

  - ### of

    public static Xml.Builder of(InputStream is)

  - ### of

    public static Xml.Builder of(Reader reader)

  - ### of

    public static Xml.Builder of(String xml)

  - ### of

    public static Xml.Builder of(String rootElementName, Object object)

  - ### populate

    public void populate(Object targetObject, String xpathExpression)

    Populates supplied object with the XML matching the given expression. If there is no match, the object does not get populated. Takes into consideration whether the target object implements `XmlConfigurable` or JAXB.

    Performs XML validation if the target object has an associated schema.

    Parameters:
      `targetObject` - object to populate with this XML
      `xpathExpression` - XPath expression

  - ### populate

    public void populate(Object targetObject)

    Populates supplied object with this XML. Takes into consideration whether the target object implements `XmlConfigurable` or JAXB.

    Performs XML validation if the target object has an associated schema.

    Invoking this method with a `null` target has no effect (returns an empty list).

    Parameters:
      `targetObject` - object to populate with this XML

  - ### toObject

    public <T> T toObject()

    Creates a new instance of the class represented by the "class" attribute on this XML root node. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML. If the class is annotated with an `XmlRootElement`, it will use JAXB to unmarshall it to an object.

    Performs XML validation if the target object has an associated schema.

    Type Parameters:
      `T` - the type of the return value
    Returns:
      a new object.
    Throws:
      `XmlValidationException` - if the XML has validation errors
      `XmlException` - if something prevented object creation

  - ### toObject

    public <T> T toObject(T defaultObject)

    Creates a new instance of the class represented by the "class" attribute on the given node. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML. If the class is annotated with an `XmlRootElement`, it will use JAXB to unmarshall it to an object.

    Performs XML validation if the target object has an associated schema.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `defaultObject` - if returned object is null or undefined, returns this default object.
    Returns:
      a new object.
    Throws:
      `XmlException` - if something prevented object creation

  - ### toObjectImpl

    public <T> T toObjectImpl(Class<?> type)

    Creates a new instance of the class represented by the "class" attribute on this XML root node. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML. If the class is annotated with an `XmlRootElement`, it will use JAXB to unmarshall it to an object.

    Other than making sure the class is a subtype of the specified super class, the main difference between method this and `toObject()` is the support for partial class names. That is, this method will scan the current class loader for a class with its name ending with the value of the "class" attribute. If more than one is found, an `XmlException` will be thrown. If you are expecting fully qualified class names, use the `toObject()` method, which is faster.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `type` - the expected class (sub)type to return
    Returns:
      a new object or `null`.
    Throws:
      `XmlValidationException` - if the XML has validation errors
      `XmlException` - if something prevented object creation

  - ### toObjectImpl

    public <T> T toObjectImpl(Class<?> type, T defaultObject)

    Creates a new instance of the class represented by the "class" attribute on the given node. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML. If the class is annotated with an `XmlRootElement`, it will use JAXB to unmarshall it to an object.

    Other than making sure the class is a subtype of the specified super class, the main difference between method this and `toObject(Object)` is the support for partial class names. That is, this method will scan the current class loader for a class with its name ending with the value of the "class" attribute. If more than one is found, an `XmlException` will be thrown. If you are expecting fully qualified class names, use the `toObject(Object)` method, which is faster.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `type` - the expected class (sub)type to return
      `defaultObject` - if returned object is null or undefined, returns this default object.
    Returns:
      a new object if not `null`, else the default object.
    Throws:
      `XmlException` - if something prevented object creation

  - ### getObject

    public <T> T getObject(String xpathExpression)

    Creates a new instance of the class represented by the "class" attribute on the node matching the expression. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should throw a `XmlException` upon error. Use a method with a default value argument to avoid throwing exceptions.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `xpathExpression` - xpath expression
    Returns:
      a new object.

  - ### getObject

    public <T> T getObject(String xpathExpression, T defaultObject)

    Creates a new instance of the class represented by the "class" attribute on the node matching the expression. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should not throw exception upon errors, but will return the default value instead (even if null). Use a method without a default value argument to get exceptions on errors.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `xpathExpression` - xpath expression
      `defaultObject` - if returned object is null or undefined, returns this default object.
    Returns:
      a new object.

  - ### getObjectList

    public <T> List<T> getObjectList(String xpathExpression, List<T> defaultObjects)

    Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression. The classes must have an empty constructor. If a class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should not throw exception upon errors, but will return the default value instead (even if null). Use a method without a default value argument to get exceptions on errors.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `xpathExpression` - xpath expression
      `defaultObjects` - if returned list is empty, returns this default list.
    Returns:
      a new object.
    Throws:
      `XmlException` - if instance cannot be created/populated

  - ### getObjectList

    public <T> List<T> getObjectList(String xpathExpression)

    Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression. The classes must have an empty constructor. If a class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should throw a `XmlException` upon error. Use a method with a default value argument to avoid throwing exceptions.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `xpathExpression` - xpath expression
    Returns:
      a new object.
    Throws:
      `XmlException` - if instance cannot be created/populated

  - ### getObjectImpl

    public <T> T getObjectImpl(Class<?> type, String xpathExpression)

    Creates a new instance of the class represented by the "class" attribute on the node matching the expression. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should throw a `XmlException` upon error. Use a method with a default value argument to avoid throwing exceptions.

    Other than making sure the class is a subtype of the specified super class, the main difference between method this and `getObject(String)` is the support for partial class names. That is, this method will scan the current class loader for a class with its name ending with the value of the "class" attribute. If more than one is found, an `XmlException` will be thrown. If you are expecting fully qualified class names, use the `getObject(String)` method, which is faster.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `type` - the expected class (sub)type to return
      `xpathExpression` - xpath expression
    Returns:
      a new object.

  - ### getObjectImpl

    public <T> T getObjectImpl(Class<?> type, String xpathExpression, T defaultObject)

    Creates a new instance of the class represented by the "class" attribute on the node matching the expression. The class must have an empty constructor. If the class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should not throw exception upon errors, but will return the default value instead (even if null). Use a method without a default value argument to get exceptions on errors.

    Other than making sure the class is a subtype of the specified super class, the main difference between method this and `getObject(String, Object)` is the support for partial class names. That is, this method will scan the current class loader for a class with its name ending with the value of the "class" attribute. If more than one is found, an `XmlException` will be thrown. If you are expecting fully qualified class names, use the `getObject(String, Object)` method, which is faster.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `type` - the expected class (sub)type to return
      `xpathExpression` - xpath expression
      `defaultObject` - if returned object is null or undefined, returns this default object.
    Returns:
      a new object.

  - ### getObjectListImpl

    public <T> List<T> getObjectListImpl(Class<?> type, String xpathExpression, List<T> defaultObjects)

    Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression. The classes must have an empty constructor. If a class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should not throw exception upon errors, but will return the default value instead (even if null). Use a method without a default value argument to get exceptions on errors.

    Other than making sure the class is a subtype of the specified super class, the main difference between method this and `getObjectList(String, List)` is the support for partial class names. That is, this method will scan the current class loader for a class with its name ending with the value of the "class" attribute. If more than one is found, an `XmlException` will be thrown. If you are expecting fully qualified class names, use the `getObjectList(String, List)` method, which is faster.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `type` - the expected class (sub)type to return
      `xpathExpression` - xpath expression
      `defaultObjects` - if returned list is empty, returns this default list.
    Returns:
      a new object.
    Throws:
      `XmlException` - if instance cannot be created/populated

  - ### getObjectListImpl

    public <T> List<T> getObjectListImpl(Class<?> type, String xpathExpression)

    Creates an instance list from classes represented by the "class" attribute on the nodes matching the expression. The classes must have an empty constructor. If a class is an instance of `XmlConfigurable`, the object created will be automatically populated by invoking the `XmlConfigurable.loadFromXML(Xml)` method, passing it the node XML.

    This method should throw a `XmlException` upon error. Use a method with a default value argument to avoid throwing exceptions.

    Other than making sure the class is a subtype of the specified super class, the main difference between method this and `getObjectList(String)` is the support for partial class names. That is, this method will scan the current class loader for a class with its name ending with the value of the "class" attribute. If more than one is found, an `XmlException` will be thrown. If you are expecting fully qualified class names, use the `getObjectList(String)` method, which is faster.

    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `type` - the expected class (sub)type to return
      `xpathExpression` - xpath expression
    Returns:
      a new object.
    Throws:
      `XmlException` - if instance cannot be created/populated

  - ### getDelimitedList

    public <T> List<T> getDelimitedList(String xpathExpression, Class<T> type)
    Gets a list of the given type after splitting the matching node value(s) on commas (CSV). Values are trimmed and blank entries removed before attempting to convert them to given type. Commas can have any spaces before or after.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `type` - target list type
    Returns:
      list of given type, never `null`

  - ### getDelimitedList

    public <T> List<T> getDelimitedList(String xpathExpression, Class<T> type, List<T> defaultValues)
    Gets a list of given type after splitting the matching node value(s) on commas (CSV). Values are trimmed and blank entries removed before attempting to convert them to given type. Commas can have any spaces before or after.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `type` - target list type
      `defaultValues` - default values if the split returns `null` or an empty list
    Returns:
      list of strings

  - ### getDelimitedList

    public <T> List<T> getDelimitedList(String xpathExpression, Class<T> type, String delimRegex)
    Gets a list of given type after splitting the matching node value(s) with the given delimiter regular expression. Values are trimmed and blank entries removed before attempting to convert them to given type.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `type` - target list type
      `delimRegex` - regular expression matching split delimiter
    Returns:
      list of strings, never `null`

  - ### getDelimitedList

    public <T> List<T> getDelimitedList(String xpathExpression, Class<T> type, String delimRegex, List<? extends T> defaultValues)
    Gets a list of given type after splitting the matching node value(s) with the given delimiter regular expression. Values are trimmed and blank entries removed before attempting to convert them to given type.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `type` - target list type
      `delimRegex` - regular expression matching split delimiter
      `defaultValues` - default values if the split returns `null` or an empty list
    Returns:
      list of strings

  - ### getXML

    public Xml getXML(String xpathExpression)
    Gets the xml subset matching the xpath expression.
    Parameters:
      `xpathExpression` - expression to match
    Returns:
      XML or `null` is xpath has no match

  - ### getXMLList

    public List<Xml> getXMLList(String xpathExpression)
    Gets the XML subsets matching the xpath expression.
    Parameters:
      `xpathExpression` - expression to match
    Returns:
      XML list, never `null`

  - ### getNode

    public Node getNode(String xpathExpression)

  - ### getNode

    public Node getNode()

  - ### toNode

    public Node toNode()

  - ### getString

    public String getString(String xpathExpression)

  - ### getString

    public String getString(String xpathExpression, String defaultValue)

  - ### getStringList

    public List<String> getStringList(String xpathExpression)
    Gets the matching list of elements/attributes as strings.
    Parameters:
      `xpathExpression` - XPath expression to the node values
    Returns:
      list of strings, never `null`

  - ### getStringList

    public List<String> getStringList(String xpathExpression, List<String> defaultValues)
    Gets the matching list of elements/attributes as strings.
    Parameters:
      `xpathExpression` - XPath expression to the node values
      `defaultValues` - default values if the expression does not match anything.
    Returns:
      list of strings

  - ### getDelimitedStringList

    public List<String> getDelimitedStringList(String xpathExpression)
    Gets a list of strings after splitting the matching node value(s) on commas (CSV). Values are trimmed and blank entries removed. Commas can have any spaces before or after.
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
    Returns:
      list of strings, never `null`

  - ### getDelimitedStringList

    public List<String> getDelimitedStringList(String xpathExpression, List<String> defaultValues)
    Gets a list of strings after splitting the matching node value(s) on commas (CSV). Values are trimmed and blank entries removed. Commas can have any spaces before or after.
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `defaultValues` - default values if the split returns `null` or an empty list
    Returns:
      list of strings

  - ### getDelimitedStringList

    public List<String> getDelimitedStringList(String xpathExpression, String delimRegex)
    Gets a list of strings after splitting the matching node value(s) with the given delimiter regular expression. Values are trimmed before being split and blank entries removed.
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `delimRegex` - regular expression matching split delimiter
    Returns:
      list of strings, never `null`

  - ### getDelimitedStringList

    public List<String> getDelimitedStringList(String xpathExpression, String delimRegex, List<String> defaultValues)
    Gets a list of strings after splitting the matching node value(s) with the given delimiter regular expression. Values are trimmed and blank entries removed.
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `delimRegex` - regular expression matching split delimiter
      `defaultValues` - default values if the split returns `null` or an empty list
    Returns:
      list of strings

  - ### getEnum

    public final <E extends Enum<E>> E getEnum(String xpathExpression, Class<E> enumClass)
    Gets an Enum constant matching one of the constants in the provided Enum class, ignoring case.
    Type Parameters:
      `E` - enum type
    Parameters:
      `xpathExpression` - XPath expression to the enum value.
      `enumClass` - target enum class
    Returns:
      an enum value or `null` if no values are matching.

  - ### getEnum

    public final <E extends Enum<E>> E getEnum(String xpathExpression, Class<E> enumClass, E defaultValue)
    Gets an Enum constant matching one of the constants in the provided Enum class, ignoring case.
    Type Parameters:
      `E` - enum type
    Parameters:
      `xpathExpression` - XPath expression to the enum value.
      `enumClass` - target enum class
      `defaultValue` - defaultValue
    Returns:
      an enum value or default value if no values are matching.

  - ### getEnumList

    public <E extends Enum<E>> List<E> getEnumList(String xpathExpression, Class<E> enumClass, List<E> defaultValues)
    Gets a list of enum constants. Values are trimmed and blank entries removed before attempting to convert them to the given enum type.
    Type Parameters:
      `E` - enum type
    Parameters:
      `xpathExpression` - XPath expression
      `enumClass` - target enum class
      `defaultValues` - default values
    Returns:
      list of enums

  - ### getDelimitedEnumList

    public <E extends Enum<E>> List<E> getDelimitedEnumList(String xpathExpression, Class<E> enumClass, List<E> defaultValues)
    Gets a list of enum constants after splitting the matching node value(s) on commas (CSV). Values are trimmed and blank entries removed before attempting to convert them to the given enum type.
    Type Parameters:
      `E` - enum type
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `enumClass` - target enum class
      `defaultValues` - default values if the split returns `null` or an empty list
    Returns:
      list of enums

  - ### getDelimitedEnumList

    public <E extends Enum<E>> List<E> getDelimitedEnumList(String xpathExpression, Class<E> enumClass, String delimRegex, List<E> defaultValues)
    Gets a list of enum constants after splitting the matching node value(s) with the given delimiter regular expression. Values are trimmed and blank entries removed before attempting to convert them to given enum type.
    Type Parameters:
      `E` - enum type
    Parameters:
      `xpathExpression` - XPath expression to the node value(s) to split
      `enumClass` - target enum class
      `delimRegex` - regular expression matching split delimiter
      `defaultValues` - default values if the split returns `null` or an empty list
    Returns:
      list of enums

  - ### getPath

    public final Path getPath(String xpathExpression)
    Gets a path, assuming the node value is a file system path.
    Parameters:
      `xpathExpression` - XPath expression to the node containing the path
    Returns:
      a path

  - ### getPath

    public final Path getPath(String xpathExpression, Path defaultValue)
    Gets a path, assuming the node value is a file system path.
    Parameters:
      `xpathExpression` - XPath expression to the node containing the path
      `defaultValue` - default path being returned if no path has been defined for the given expression.
    Returns:
      a path

  - ### getPathList

    public final List<Path> getPathList(String xpathExpression)
    Gets values as a list of paths.
    Parameters:
      `xpathExpression` - XPath expression
    Returns:
      the values

  - ### getPathList

    public final List<Path> getPathList(String xpathExpression, List<Path> defaultValue)
    Gets values as a list of paths.
    Parameters:
      `xpathExpression` - XPath expression
      `defaultValue` - default value
    Returns:
      the values

  - ### getFile

    public final File getFile(String xpathExpression)
    Gets a file, assuming the node value is a file system path.
    Parameters:
      `xpathExpression` - XPath expression to the node containing the path
    Returns:
      a File

  - ### getFile

    public final File getFile(String xpathExpression, File defaultValue)
    Gets a file, assuming the node value is a file system path.
    Parameters:
      `xpathExpression` - XPath expression to the node containing the path
      `defaultValue` - default file being returned if no file has been defined for the given expression.
    Returns:
      a File

  - ### getFileList

    public final List<File> getFileList(String xpathExpression)
    Gets values as a list of files.
    Parameters:
      `xpathExpression` - XPath expression
    Returns:
      the values

  - ### getFileList

    public final List<File> getFileList(String xpathExpression, List<File> defaultValue)
    Gets values as a list of files.
    Parameters:
      `xpathExpression` - XPath expression
      `defaultValue` - default value
    Returns:
      the values

  - ### getURL

    public final URL getURL(String xpathExpression)

  - ### getURL

    public final URL getURL(String xpathExpression, URL defaultValue)

  - ### getURLList

    public final List<URL> getURLList(String xpathExpression)

  - ### getURLList

    public final List<URL> getURLList(String xpathExpression, List<URL> defaultValue)

  - ### getInteger

    public Integer getInteger(String xpathExpression)

  - ### getInteger

    public Integer getInteger(String xpathExpression, Integer defaultValue)

  - ### getLong

    public Long getLong(String xpathExpression)

  - ### getLong

    public Long getLong(String xpathExpression, Long defaultValue)

  - ### getFloat

    public Float getFloat(String xpathExpression)

  - ### getFloat

    public Float getFloat(String xpathExpression, Float defaultValue)

  - ### getDimension

    public Dimension getDimension(String xpathExpression)

  - ### getDimension

    public Dimension getDimension(String xpathExpression, Dimension defaultValue)

  - ### getDouble

    public Double getDouble(String xpathExpression)

  - ### getDouble

    public Double getDouble(String xpathExpression, Double defaultValue)

  - ### getBoolean

    public Boolean getBoolean(String xpathExpression)

  - ### getBoolean

    public Boolean getBoolean(String xpathExpression, Boolean defaultValue)

  - ### getLocale

    public Locale getLocale(String xpathExpression)

  - ### getLocale

    public Locale getLocale(String xpathExpression, Locale defaultValue)

  - ### getCharset

    public Charset getCharset(String xpathExpression)

  - ### getCharset

    public Charset getCharset(String xpathExpression, Charset defaultValue)

  - ### getDataSize

    public Long getDataSize(String xpathExpression)
    Gets the size of a data expression, in bytes (e.g., 2KB, 1GiB, 3 megabytes, etc). Without a unit specified, the value is assumed to represent bytes.
    Parameters:
      `xpathExpression` - xpath to the element/attribute with the size
    Returns:
      size in bytes
    Since:
      2.0.0

  - ### getDataSize

    public Long getDataSize(String xpathExpression, Long defaultValue)
    Gets the size of a data expression, in bytes (e.g., 2KB, 1GiB, 3 megabytes, etc). Without a unit specified, the value is assumed to represent bytes.
    Parameters:
      `xpathExpression` - xpath to the element/attribute with the size
      `defaultValue` - default value
    Returns:
      size in bytes or default value if size is `null`
    Since:
      2.0.0

  - ### getDataSize

    public Long getDataSize(String xpathExpression, DataUnit targetUnit, Long defaultValue)
    Gets the size of a data expression, in the specified target unit (e.g., 2KB, 1GiB, 3 megabytes, etc). Without a unit specified in the value, the value is assumed to represent bytes.
    Parameters:
      `xpathExpression` - xpath to the element/attribute with the size
      `targetUnit` - the unit to convert the value into
      `defaultValue` - default value
    Returns:
      size in bytes or default value if size is `null`
    Since:
      2.0.0

  - ### getDurationMillis

    public Long getDurationMillis(String xpathExpression)
    Gets a duration in milliseconds which can exists as a numerical value or a textual representation of a duration as per `DurationParser`. If the key value is found but there are parsing errors, a `DurationParserException` will be thrown.
    Parameters:
      `xpathExpression` - xpath to the element/attribute containing the duration
    Returns:
      duration in milliseconds

  - ### getDurationMillis

    public Long getDurationMillis(String xpathExpression, Long defaultValue)
    Gets a duration in milliseconds which can exists as a numerical value or a textual representation of a duration as per `DurationParser`. If the key value is found but there are parsing errors, a `DurationParserException` will be thrown.
    Parameters:
      `xpathExpression` - xpath to the element/attribute containing the duration
      `defaultValue` - default duration
    Returns:
      duration in milliseconds

  - ### getDuration

    public Duration getDuration(String xpathExpression)
    Gets a duration which can exists as a numerical value or a textual representation of a duration as per `DurationParser`. If the duration does not exists for the given key or is blank, `null` is returned. If the key value is found but there are parsing errors, a `DurationParserException` will be thrown.
    Parameters:
      `xpathExpression` - xpath to the element/attribute containing the duration
    Returns:
      duration

  - ### getDuration

    public Duration getDuration(String xpathExpression, Duration defaultValue)
    Gets a duration which can exists as a numerical value or a textual representation of a duration as per `DurationParser`. If the duration does not exists for the given key or is blank, the default value is returned. If the key value is found but there are parsing errors, a `DurationParserException` will be thrown.
    Parameters:
      `xpathExpression` - xpath to the element/attribute containing the duration
      `defaultValue` - default duration
    Returns:
      duration

  - ### getPattern

    public Pattern getPattern(String xpathExpression)
    Gets a regular expression pattern.
    Parameters:
      `xpathExpression` - xpath to the element/attribute with the pattern
    Returns:
      pattern
    Since:
      3.0.0

  - ### getPattern

    public Pattern getPattern(String xpathExpression, Pattern defaultValue)
    Gets a regular expression pattern.
    Parameters:
      `xpathExpression` - xpath to the element/attribute with the pattern
      `defaultValue` - default value
    Returns:
      pattern
    Since:
      3.0.0

  - ### validate

    public void validate()

    Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute.

    #### Error handling

    The expected behavior when encountering validation errors is tied to the registered `ErrorHandler`. When no error handler is specified, the default is `ErrorHandlerFailer` (which throws `XmlValidationException`). Error handlers can be specified when using the builder obtained with one of the `XML.of(...)`) methods.

    The XSD schema used for validation is expected to be found at the same classpath location and have the same name as the object class, but with the ".xsd" extension.

    This method is the same as invoking `validate(getClass("@class"))`

    See Also:
      - `ErrorHandlerFailer`
      - `ErrorHandlerCapturer`
      - `ErrorHandlerLogger`

  - ### validate

    public void validate(Object obj)

    Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute.

    #### Error handling

    The expected behavior when encountering validation errors is tied to the registered `ErrorHandler`. When no error handler is specified, the default is `ErrorHandlerFailer` (which throws `XmlValidationException`). Error handlers can be specified when using the builder obtained with one of the `XML.of(...)`) methods..

    The XSD schema used for validation is expected to be found at the same classpath location and have the same name as the object class, but with the ".xsd" extension.

    This method is the same as invoking `validate(obj.getClass())`

    Parameters:
      `obj` - the object used to locate the XML schema used for validation
    See Also:
      - `ErrorHandlerFailer`
      - `ErrorHandlerCapturer`
      - `ErrorHandlerLogger`

  - ### validate

    public void validate(Class<?> clazz)

    Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute.

    #### Error handling

    The expected behavior when encountering validation errors is tied to the registered `ErrorHandler`. When no error handler is specified, the default is `ErrorHandlerFailer` (which throws `XmlValidationException`). Error handlers can be specified when using the builder obtained with one of the `XML.of(...)`) methods..

    The XSD schema used for validation is expected to be found at the same classpath location and have the same name as the object class, but with the ".xsd" extension.

    Parameters:
      `clazz` - the class with XSD schema attached, used for validation
    See Also:
      - `ErrorHandlerFailer`
      - `ErrorHandlerCapturer`
      - `ErrorHandlerLogger`

  - ### isEnabled

    public boolean isEnabled()

  - ### isDisabled

    public boolean isDisabled()

  - ### isElementPresent

    public boolean isElementPresent(String xpathExpression)
    Gets whether the given expression matches an existing element. A blank expression always returns `false`.
    Parameters:
      `xpathExpression` - expression
    Returns:
      `true` if the expression matches an element
    Since:
      3.0.0

  - ### ifXML

    public void ifXML(String xpathExpression, Consumer<Xml> then)
    If the given expression matches an element, consume that element.
    Parameters:
      `xpathExpression` - expression
      `then` - XML consumer

  - ### toReader

    public Reader toReader()
    Creates a new `Reader` from a `Node`. Do not forget to close the reader instance when you are done with it.
    Returns:
      reader
    Throws:
      `XmlException` - cannot read configuration

  - ### equals

    public boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Gets a string representation of this XML.
    Overrides:
      `toString` in class `Object`
    Returns:
      XML string
    Throws:
      `XmlException` - cannot read configuration

  - ### toString

    public String toString(int indent)
    Gets a string representation of this XML.
    Parameters:
      `indent` - whether to indent the XML
    Returns:
      XML string
    Throws:
      `XmlException` - cannot read configuration

  - ### forEach

    public void forEach(String xpathExpression, Consumer<Xml> action)
    If the given expression matches one or more elements, consume those element one by one.
    Parameters:
      `xpathExpression` - expression
      `action` - The action to be performed for each element

  - ### assertWriteRead

    public static void assertWriteRead(Object object, String elementName)
    Convenience class for testing that an object annotated with JAXB `XmlRootElement` or implementing `XmlConfigurable` (or both) can be written, and read back into an new instance that is equal as per `equals(Object)`.
    Parameters:
      `object` - the instance object to test if it written/read properly
      `elementName` - the tag name of the root element being written
    Throws:
      `XmlException` - Cannot write/read configuration or the read object is not equal to the original one that was written.

  - ### contains

    public boolean contains(String xpathExpression)

  - ### newXPath

    @Deprecated(since="3.0.0") public static XPath newXPath()
    Deprecated.
    Use `XpathUtil.newXPath()` instead
    Gets a new XPath instance from the default object model.
    Returns:
      new XPath instance

  - ### newXPathExpression

    @Deprecated(since="3.0.0") public static XPathExpression newXPathExpression(String expression)
    Deprecated.
    Use `XpathUtil.newXPathExpression(String)` instead
    Gets a new compiled `XPathExpression` from the given string.
    Parameters:
      `expression` - the XPath string
    Returns:
      compiled XPath expression

  - ### get

    public <T> T get(String xpathExpression, Class<T> type)
    Gets the matching element/attribute, converted from string to the given type.
    Type Parameters:
      `T` - target type
    Parameters:
      `xpathExpression` - XPath expression to the node value
      `type` - target class type of returned value
    Returns:
      object of given type

  - ### get

    public <T> T get(String xpathExpression, Class<T> type, T defaultValue)
    Gets the matching element/attribute, converted from string to the given type.
    Type Parameters:
      `T` - target type
    Parameters:
      `xpathExpression` - XPath expression to the node value
      `type` - target class type of returned value
      `defaultValue` - default value if the expression returns `null`
    Returns:
      object of given type

  - ### getList

    public <T> List<? extends T> getList(String xpathExpression, Class<T> type)
    Gets the matching list of elements/attributes, converted from string to the given type.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression to the node values
      `type` - target class type of returned list
    Returns:
      list of given type, never `null`

  - ### getList

    public <T> List<? extends T> getList(String xpathExpression, Class<T> type, List<? extends T> defaultValues)
    Gets the matching list of elements/attributes, converted from string to the given type.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression to the node values
      `type` - target class type of returned list
      `defaultValues` - default values if the expression returns `null` or an empty list
    Returns:
      list of given type

  - ### getStringMap

    public Map<String,String> getStringMap(String xpathList, String xpathKey, String xpathValue)
    Gets the matching map of elements/attributes as strings.
    Parameters:
      `xpathList` - XPath expression to the node list representing the map
      `xpathKey` - XPath expression to a node key
      `xpathValue` - XPath expression to a node value
    Returns:
      map of strings, never `null`

  - ### getStringMap

    public Map<String,String> getStringMap(String xpathList, String xpathKey, String xpathValue, Map<String,String> defaultValues)
    Gets the matching map of elements/attributes as strings.
    Parameters:
      `xpathList` - XPath expression to the node list representing the map
      `xpathKey` - XPath expression to a node key
      `xpathValue` - XPath expression to a node value
      `defaultValues` - default values if the expressions return `null` or an empty map
    Returns:
      map of strings, never `null` unless default value is returned and is `null`

  - ### getName

    public String getName()

  - ### computeElementIfAbsent

    public Xml computeElementIfAbsent(String tagName, Function<String,Object> function)
    Computes and adds the element returned by the provided function if an element with the same name is not already present, else, return the existing one. Passing a `null` function or `null` value returned by the function when there are no existing element will add a new empty element.
    Parameters:
      `tagName` - element name
      `function` - taking the new element name and returning the element
    Returns:
      XML of the added element, or the already existing element
    Since:
      3.0.0

  - ### addElement

    public Xml addElement(String tagName)
    Adds an empty child element to this XML root element.
    Parameters:
      `tagName` - element name
    Returns:
      XML of the added element

  - ### addElement

    public Xml addElement(String tagName, Object value)

    Adds a child element to this XML root element. If the element value is blank, and empty element is created. Otherwise, the value is handled as `of(String, Object)`

    Parameters:
      `tagName` - element name
      `value` - element value
    Returns:
      XML of the added element

  - ### addElementList

    public List<Xml> addElementList(String tagName, List<?> values)
    Adds a list of values to the current XML and return the added list. There will be one element added for each entry of the supplied list, all with the tag name supplied.
    Parameters:
      `tagName` - the tag name for each values added
      `values` - values to add
    Returns:
      the added list as a list of XML instances

  - ### addElementList

    public Xml addElementList(@NonNull @NonNull String parentTagName, String tagName, List<?> values)
    Adds a list of values under a new parent tag name to the current XML and return the added list. There will be one element added for each entry of the supplied list, all with the tag name supplied, all grouped under the parent tag supplied.
    Parameters:
      `parentTagName` - the name of the new parent tag that will hold all added values.
      `tagName` - the tag name for each values added
      `values` - values to add
    Returns:
      the XML for the parent tag

  - ### addDelimitedElementList

    public Xml addDelimitedElementList(String name, List<?> values)
    Adds a list of values as a new element after joining them with a comma (CSV). Values are trimmed and blank entries removed. Values can be of any types, as they converted to String by invoking their "toString()" method.
    Parameters:
      `name` - attribute name
      `values` - attribute values
    Returns:
      the newly added element

  - ### addDelimitedElementList

    public Xml addDelimitedElementList(String name, String delim, List<?> values)
    Adds a list of values as a new element after joining them with the given delimiter. Values are trimmed and blank entries removed. Values can be of any types, as they converted to String by invoking their "toString()" method.
    Parameters:
      `name` - attribute name
      `delim` - delimiter
      `values` - attribute values
    Returns:
      the newly added element

  - ### addElementMap

    public List<Xml> addElementMap(String tagName, String attributeName, Map<?,?> map)

    Adds a `Map` as a series of elements without a parent element wrapping that group. Map keys are defined as element attributes and the map value is the element content. The structure can be visualized like this:

         <tagName attributeName="(key)">(value)</tagName>
         <tagName attributeName="(key)">(value)</tagName>
         ...

    Map keys are assumed to be strings or single objects with supported conversion to string (see `GenericConverter`). Map values can be single values or multi-values. Arrays or collections will have their values be treated as individual elements with the same key name. In any case, single or multiple values are otherwise converted to strings just like keys.

    Parameters:
      `tagName` - name of tags for each map entries
      `attributeName` - name of the tag attribute holding the map entry key
      `map` - map to add
    Returns:
      XML of parent tag, with nested element for each map entries, or `null` if map is `null`.

  - ### addElementMap

    public Xml addElementMap(String parentTagName, String tagName, String attributeName, Map<?,?> map)

    Adds a `Map` as a series of elements with a parent element wrapping that group. Map keys are defined as element attributes and the map value is the element content. The structure can be visualized like this:

         <parentTagName>
           <tagName attributeName="(key)">(value)</tagName>
           <tagName attributeName="(key)">(value)</tagName>
           ...
         </parentTagName>

    Map keys are assumed to be strings or single objects with supported conversion to string (see `GenericConverter`). Map values can be single values or multi-values. Arrays or collections will have their values be treated as individual elements with the same key name. In any case, single or multiple values are otherwise converted to strings just like keys.

    Parameters:
      `parentTagName` - required name of map elements wrapper tag
      `tagName` - name of tags for each map entries
      `attributeName` - name of the tag attribute holding the map entry key
      `map` - map to add
    Returns:
      XML of parent tag, with nested element for each map entries, or `null` if map is `null`.

  - ### removeElement

    public Xml removeElement(String tagName)
    Removes an element from this XML.
    Parameters:
      `tagName` - element name
    Returns:
      XML of the removed element

  - ### remove

    public Xml remove()
    Removes itself from its XML parent (if any).
    Returns:
      a new instance of this removed XML or this instance if it is not attached to any parent

  - ### insertBefore

    public Xml insertBefore(Xml newXML)
    Inserts a new XML node before this one, as a sibling of a shared parent. If there is no parent to this XML, the new XML is not inserted.
    Parameters:
      `newXML` - the XML to insert
    Returns:
      a new instance of the inserted XML, or the inserted node if this node is not attached to any parent.

  - ### insertAfter

    public Xml insertAfter(Xml newXML)
    Inserts a new XML node after this one, as a sibling of a shared parent. If there is no parent to this XML, the new XML is not inserted.
    Parameters:
      `newXML` - the XML to insert
    Returns:
      a new instance of the inserted XML, or the inserted node if this node is not attached to any parent.

  - ### setAttribute

    public Xml setAttribute(String name, Object value)
    Sets an attribute on this XML element, converting the supplied object to a string (enums are also converted to lowercase). A `null` value is equivalent to not adding or removing that attribute.
    Parameters:
      `name` - attribute name
      `value` - attribute value
    Returns:
      this element

  - ### setAttributes

    public Xml setAttributes(Map<String,?> attribs)
    Sets attributes on this XML element.
    Parameters:
      `attribs` - attributes
    Returns:
      this element

  - ### setDelimitedAttributeList

    public Xml setDelimitedAttributeList(String name, List<?> values)
    Sets a list of values as an attribute after joining them with a comma (CSV). Values are trimmed and blank entries removed. Values can be of any types, as they converted to String by invoking their "toString()" method.
    Parameters:
      `name` - attribute name
      `values` - attribute values
    Returns:
      this element

  - ### setDelimitedAttributeList

    public Xml setDelimitedAttributeList(String name, String delim, List<?> values)
    Sets a list of values as an attribute after joining them with the given delimiter. Values are trimmed and blank entries removed. Values can be of any types, as they converted to String by invoking their "toString()" method.
    Parameters:
      `name` - attribute name
      `delim` - delimiter
      `values` - attribute values
    Returns:
      this element

  - ### removeAttribute

    public Xml removeAttribute(String name)
    Removes an attribute on this XML element.
    Parameters:
      `name` - attribute name
    Returns:
      this element

  - ### setTextContent

    public Xml setTextContent(Object textContent)
    Sets the direct text content of an XML element. To replace all child nodes with text, use `xml.getNode().setTextContent("my content")`. Setting `null` content is effectively the same as invoking `removeTextContent()`.
    Parameters:
      `textContent` - text content
    Returns:
      this element

  - ### getTextContent

    public String getTextContent()
    Gets this XML direct text content, if any, joining multiple text nodes by a space separator. To get all text content, including text content of child elements, use `xml.getNode().getTextContent()`.
    Returns:
      this XML text, or `null` if no text
    Since:
      3.0.0

  - ### removeTextContent

    public Xml removeTextContent()
    Removes this XML direct text content, without impact on attributes and child elements and their content.
    Returns:
      this XML without text content

  - ### addXML

    public Xml addXML(Reader xml)

  - ### addXML

    public Xml addXML(String xml)

  - ### addXML

    public Xml addXML(Xml xml)

  - ### getXMLWriter

    public Writer getXMLWriter()

  - ### getXMLStreamWriter

    @Deprecated(since="3.0.0") public EnhancedXmlStreamWriter getXMLStreamWriter()
    Deprecated.

  - ### write

    public void write(Writer writer)

  - ### write

    public void write(Writer writer, int indent)

  - ### write

    public void write(File file)

  - ### write

    public void write(File file, int indent)

  - ### unwrap

    public Xml unwrap()
    Unwraps this XML by removing the root tag and keeping its child element (and its nested element). If there are no child (i.e., nothing to unwrap), invoking this method has no effect. If there are more than one child element, this method throws an `XmlException`.
    Returns:
      this XML, unwrapped

  - ### rename

    public Xml rename(String newName)
    Rename this XML (element tag name).
    Parameters:
      `newName` - new name for this XML
    Returns:
      this XML, renamed

  - ### wrap

    public Xml wrap(String parentName)
    Wraps this XML by adding a parent element around it.
    Parameters:
      `parentName` - name of wrapping element
    Returns:
      this XML, wrapped

  - ### clear

    public Xml clear()
    Clears this XML by removing all its attributes and elements (i.e., making it an empty tag).
    Returns:
      this cleared XML

  - ### isEmpty

    public boolean isEmpty()
    Gets whether this XML is empty. An XML is considered empty if all of `hasAttributes()`, `hasChildElements()`, and `hasTextContent()` return `false`.
    Returns:
      `true` if empty
    Since:
      3.0.0

  - ### hasChildElements

    public boolean hasChildElements()
    Gets whether this XML element has any child elements.
    Returns:
      `true` if this element has at least one child element
    Since:
      3.0.0

  - ### hasAttributes

    public boolean hasAttributes()
    Gets whether this XML element has any attributes.
    Returns:
      `true` if this element has at least one attribute
    Since:
      3.0.0

  - ### hasTextContent

    public boolean hasTextContent()
    Gets whether this XML has any text content.
    Returns:
      `true` if non-`null` and non-empty.
    Since:
      3.0.0

  - ### replace

    public Xml replace(Xml replacement)
    Replaces the current XML with the provided one.
    Parameters:
      `replacement` - replacing XML
    Returns:
      this XML, replaced

  - ### getClass

    public Class<?> getClass(String xpathExpression)

  - ### getClass

    public <T> Class<T> getClass(String xpathExpression, Class<T> defaultValue)

  - ### getClassList

    public final <T> List<Class<T>> getClassList(String xpathExpression)
    Gets values as a list of files.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression
    Returns:
      the values

  - ### getClassList

    public final <T> List<Class<? extends T>> getClassList(String xpathExpression, List<Class<? extends T>> defaultValue)
    Gets values as a list of files.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `xpathExpression` - XPath expression
      `defaultValue` - default value
    Returns:
      the values

  - ### parseXML

    public <T> T parseXML(String xpathExpression, @NonNull @NonNull Function<Xml,T> parser)

  - ### parseXML

    public <T> T parseXML(String xpathExpression, @NonNull @NonNull Function<Xml,T> parser, T defaultValue)

  - ### parseXMLList

    public <T> List<T> parseXMLList(String xpathExpression, @NonNull @NonNull Function<Xml,T> parser)

  - ### parseXMLList

    public <T> List<T> parseXMLList(String xpathExpression, @NonNull @NonNull Function<Xml,T> parser, List<T> defaultValue)

  - ### parseXMLMap

    public <K, V> Map<K,V> parseXMLMap(String xpathExpression, Function<Xml,Map.Entry<K,V>> parser)

  - ### parseXMLMap

    public <K, V> Map<K,V> parseXMLMap(String xpathExpression, Function<Xml,Map.Entry<K,V>> parser, Map<K,V> defaultValue)

  - ### checkDeprecated

    public void checkDeprecated(String deprecatedXPath, String replacement, boolean throwException)
    Checks whether a deprecated configuration entry was specified and log a warning or throw an `XmlException`.
    Parameters:
      `deprecatedXPath` - xpath to the invalid entry
      `replacement` - new xpath or instructions to replace
      `throwException` - `true` to throw exception, else log a warning

  - ### checkDeprecated

    public void checkDeprecated(String deprecatedXPath, boolean throwException)
    Checks whether a deprecated configuration entry (without replacement) was specified and log a warning or throw an `XmlException`.
    Parameters:
      `deprecatedXPath` - xpath to the invalid entry
      `throwException` - `true` to throw exception, else log a warning

  - ### getErrorHandler

    public ErrorHandler getErrorHandler()

  - ### getDocumentBuilderFactory

    public DocumentBuilderFactory getDocumentBuilderFactory()

  - ### isXMLConfigurable

    public static boolean isXMLConfigurable(Object obj)

  - ### isJAXB

    public static boolean isJAXB(Object obj)

  - ### iterator

    public Iterator<XmlCursor> iterator()
    Returns an `Iterator` of `XmlCursor` from this XML, in sequential order. Invoking a "read" methods on `XmlCursor` which reads child elements will result in the iterator skipping those already read elements.
    Specified by:
      `iterator` in interface `Iterable<XmlCursor>`
    Returns:
      XML cursor iterator

  - ### stream

    public Stream<XmlCursor> stream()
    Returns a `Stream` of `XmlCursor` from this XML, in sequential order. Invoking a "read" methods on `XmlCursor` which reads child elements will result in the stream skipping those already read elements.
    Returns:
      XML cursor stream

  - ### iterator

    public static Iterator<XmlCursor> iterator(Object obj)

    Returns an `Iterator` of `XmlCursor` from the supplied XML object, in sequential order. Invoking a "read" methods on `XmlCursor` which reads child elements will result in the iterator skipping those already read elements.

    The object argument type must be one of the following:

    - `Path`
    - `File`
    - `Node`
    - `Xml`
    - `String`
    - `InputStream`
    - `Reader`
    - `XMLEventReader`
    Parameters:
      `obj` - the XML to iterate over
    Returns:
      XML cursor iterator

  - ### stream

    public static Stream<XmlCursor> stream(Object obj)

    Returns a `Stream` of `XmlCursor` from the supplied XML object, in sequential order. Invoking a "read" methods on `XmlCursor` which reads child elements will result in the stream skipping those already read elements.

    The object argument type must be one of the following:

    - `Path`
    - `File`
    - `Node`
    - `Xml`
    - `String`
    - `InputStream`
    - `Reader`
    - `XMLEventReader`
    Parameters:
      `obj` - the XML to stream
    Returns:
      XML cursor stream

  - ### join

    @Deprecated(since="3.0.0") public String join(String delim, List<?> values)
    Deprecated.
    Will be removed or visibility reduced in a future release.
    Joins multiple values using the supplied delimiter or a comma if the delimiter is `null`.
    Parameters:
      `delim` - delimiter
      `values` - the values to join
    Returns:
      joined values, as a string