XML (Norconex Commons Lang 2.0.2 API)

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

Author:

Pascal Essiembre

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class XML.Builder

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

Constructor Summary

Constructors
Constructor and Description
`XML(File file)` Parse an XML file into an XML document, without consideration for namespaces.
`XML(Node node)` Creates an XML with the given node.
`XML(Path 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)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`XML`	`addDelimitedElementList(String name, List<?> values)` Adds a list of values as a new element after joining them with a comma (CSV).
`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`	`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.
`List<XML>`	`addElementList(String tagName, List<?> values)`
`XML`	`addElementList(String parentTagName, String tagName, List<?> values)`
`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`	`addElementMap(String parentTagName, String tagName, String attributeName, Map<?,?> map)` Adds a `Map` as a series of elements with a parent element wrapping that group.
`XML`	`addXML(Reader xml)`
`XML`	`addXML(String xml)`
`XML`	`addXML(XML xml)`
`static void`	`assertWriteRead(IXMLConfigurable xmlConfigurable, String elementName)` Convenience class for testing that a `IXMLConfigurable` instance can be written, and read into an new instance that is equal as per `Object.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).
`boolean`	`contains(String xpathExpression)`
`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)`
`<T> List<Class<T>>`	`getClassList(String xpathExpression)` Gets values as a list of files.
`<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, List<E> defaultValues)` Gets a list of enum constants after splitting the matching node value(s) on commas (CSV).
`<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.
`<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, List<T> defaultValues)` Gets a list of 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.
`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, List<String> defaultValues)` 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.
`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`.
`<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.
`<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()`
`File`	`getFile(String xpathExpression)` Gets a file, assuming the node value is a file system path.
`File`	`getFile(String xpathExpression, File defaultValue)` Gets a file, assuming the node value is a file system path.
`List<File>`	`getFileList(String xpathExpression)` Gets values as a list of files.
`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.
`Path`	`getPath(String xpathExpression)` Gets a path, assuming the node value is a file system path.
`Path`	`getPath(String xpathExpression, Path defaultValue)` Gets a path, assuming the node value is a file system path.
`List<Path>`	`getPathList(String xpathExpression)` Gets values as a list of paths.
`List<Path>`	`getPathList(String xpathExpression, List<Path> defaultValue)` Gets values as a list of paths.
`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.
`URL`	`getURL(String xpathExpression)`
`URL`	`getURL(String xpathExpression, URL defaultValue)`
`List<URL>`	`getURLList(String xpathExpression)`
`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()`
`Writer`	`getXMLWriter()`
`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`	`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)`
`static XPath`	`newXPath()`
`static XPathExpression`	`newXPathExpression(String expression)`
`static XML.Builder`	`of(File file)`
`static XML.Builder`	`of(InputStream is)`
`static XML.Builder`	`of(Node node)`
`static XML.Builder`	`of(Path path)`
`static XML.Builder`	`of(Reader reader)`
`static XML.Builder`	`of(String xml)`
`static XML.Builder`	`of(String rootElementName, Object object)`
`<T> T`	`parseXML(String xpathExpression, Function<XML,T> parser)`
`<T> T`	`parseXML(String xpathExpression, Function<XML,T> parser, T defaultValue)`
`<T> List<T>`	`parseXMLList(String xpathExpression, Function<XML,T> parser)`
`<T> List<T>`	`parseXMLList(String xpathExpression, 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)`
`List<XMLValidationError>`	`populate(Object targetObject)` Populates supplied object with this XML.
`List<XMLValidationError>`	`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`	`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, List<?> values)` Sets a list of values as an attribute after joining them with a comma (CSV).
`XML`	`setDelimitedAttributeList(String name, String delim, List<?> values)` Sets a list of values as an attribute after joining them with the given delimiter.
`XML`	`setTextContent(Object textContent)` Sets the 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).
`List<XMLValidationError>`	`validate()` Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute.
`List<XMLValidationError>`	`validate(Class<?> clazz)` Validates this XML for classes having an XSD schema attached, and logs any error/warnings.
`List<XMLValidationError>`	`validate(Object obj)` Validates this XML for objects having an XSD schema attached, and logs any error/warnings.
`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, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Constructor Detail
  - 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 assumed to be 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)
```
  - XML
```
public XML(Node node)
```
    Creates an XML with the given node.
    
    Parameters:
    
    node - the node representing the XML
- Method Detail
  - isEnabled
```
public boolean isEnabled()
```
  - isDisabled
```
public boolean isDisabled()
```
  - toNode
```
public Node toNode()
```
  - 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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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
  - populate
```
public List<XMLValidationError> 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 IXMLConfigurable or JAXB.
    
    Performs XML validation if the target object has an associated schema.
    
    Parameters:
    
    xpathExpression - XPath expression
    
    targetObject - object to populate with this XML
    
    Returns:
    
    validation errors of an empty list if none (never null)
  - populate
```
public List<XMLValidationError> populate(Object targetObject)
```
    Populates supplied object with this XML. Takes into consideration whether the target object implements IXMLConfigurable 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
    
    Returns:
    
    validation errors or an empty list if none (never null)
  - 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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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:
    
    defaultObject - if returned object is null or undefined, returns this default object.
    
    xpathExpression - xpath expression
    
    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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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
    
    defaultObject - if returned object is null or undefined, returns this default object.
    
    xpathExpression - xpath expression
    
    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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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 IXMLConfigurable, the object created will be automatically populated by invoking the IXMLConfigurable.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
  - 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
  - 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
  - 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
  - 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
  - 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
  - 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
  - validate
```
public List<XMLValidationError> validate()
```
    Validates this XML against an XSD schema attached to the class represented in this XML root tag "class" attribute. In addition to being returned, some validation errors/warnings may be logged. The schema 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"))
    
    Returns:
    
    list of errors/warnings or empty (never null)
  - validate
```
public List<XMLValidationError> validate(Object obj)
```
    Validates this XML for objects having an XSD schema attached, and logs any error/warnings. The schema 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 to validate the XML for
    
    Returns:
    
    list of errors/warnings or empty (never null)
  - validate
```
public List<XMLValidationError> validate(Class<?> clazz)
```
    Validates this XML for classes having an XSD schema attached, and logs any error/warnings. The schema 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 to validate the XML for
    
    Returns:
    
    unmodifiable list of errors/warnings or empty (never null)
  - assertWriteRead
```
public static void assertWriteRead(IXMLConfigurable xmlConfigurable,
                                   String elementName)
```
    Convenience class for testing that a IXMLConfigurable instance can be written, and read into an new instance that is equal as per Object.equals(Object).
    
    Parameters:
    
    xmlConfigurable - the instance to test if it writes/read properly
    
    elementName - the tag name of the root element being written
    
    Throws:
    
    XMLException - Cannot save/load configuration
  - contains
```
public boolean contains(String xpathExpression)
```
  - 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
  - join
```
public String join(String delim,
                   List<?> values)
```
  - 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
  - newXPath
```
public static XPath newXPath()
```
  - newXPathExpression
```
public static XPathExpression newXPathExpression(String expression)
```
  - getNode
```
public Node getNode(String xpathExpression)
```
  - getNode
```
public Node getNode()
```
  - 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
  - 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
  - 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
  - getName
```
public String getName()
```
  - 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 or null if value is null
  - addElementList
```
public List<XML> addElementList(String tagName,
                                List<?> values)
```
  - addElementList
```
public XML addElementList(String parentTagName,
                          String tagName,
                          List<?> values)
```
  - 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 Converter). 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 Converter). 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 text content of an XML element.
    
    Parameters:
    
    textContent - text content
    
    Returns:
    
    this element
  - addXML
```
public XML addXML(Reader xml)
```
  - addXML
```
public XML addXML(String xml)
```
  - addXML
```
public XML addXML(XML xml)
```
  - getXMLWriter
```
public Writer getXMLWriter()
```
  - getXMLStreamWriter
```
public EnhancedXMLStreamWriter getXMLStreamWriter()
```
  - 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
  - replace
```
public XML replace(XML replacement)
```
    Replaces the current XML with the provided one.
    
    Parameters:
    
    replacement - replacing XML
    
    Returns:
    
    this XML, replaced
  - 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)
```
  - 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,
                      Function<XML,T> parser)
```
  - parseXML
```
public <T> T parseXML(String xpathExpression,
                      Function<XML,T> parser,
                      T defaultValue)
```
  - parseXMLList
```
public <T> List<T> parseXMLList(String xpathExpression,
                                Function<XML,T> parser)
```
  - parseXMLList
```
public <T> List<T> parseXMLList(String xpathExpression,
                                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
  - 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)
```

Class XML

XML syntax and white spaces

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

XML

XML

XML

XML

XML

XML

Method Detail

isEnabled

isDisabled

toNode

toObject

toObject

toObjectImpl

toObjectImpl

populate

populate

getObject

getObject

getObjectList

getObjectList

getObjectImpl

getObjectImpl

getObjectListImpl

getObjectListImpl

getXML

ifXML

forEach

getXMLList

toReader

toString

toString

validate

validate

validate

assertWriteRead

contains

getDelimitedStringList

getDelimitedStringList

getDelimitedStringList

getDelimitedStringList

join

getDelimitedList

getDelimitedList

getDelimitedList

getDelimitedList

newXPath

newXPathExpression

getNode

getNode

getString

getString

getStringList

getStringList

get

get

getList

getList

getStringMap

getStringMap

getInteger

getInteger

getLong

getLong

getFloat

getFloat

getDimension

getDimension

getDouble

getDouble

getBoolean

getBoolean

getLocale