Package com.norconex.commons.lang.xml

Class 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

    • 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​(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

      • 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()

      • getNode

        public Node getNode​(String xpathExpression)

      • getNode

        public Node getNode()

      • getString

        public String getString​(String xpathExpression)

      • 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)

      • 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)

      • getDouble

        public Double getDouble​(String xpathExpression)

      • getBoolean

        public Boolean getBoolean​(String xpathExpression)

      • getLocale

        public Locale getLocale​(String xpathExpression)

      • getCharset

        public Charset getCharset​(String xpathExpression)

      • 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​(XML xml)

      • getXMLWriter

        public Writer getXMLWriter()

      • 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)

      • 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

      • isXMLConfigurable

        public static boolean isXMLConfigurable​(Object obj)

      • isJAXB

        public static boolean isJAXB​(Object obj)

      • 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