Package com.norconex.commons.lang.xml

Class XML

java.lang.Object
com.norconex.commons.lang.xml.XML
All Implemented Interfaces:
Iterable<XMLCursor>
public class XML extends Object implements Iterable<XMLCursor>

XML DOM wrapper facilitating node querying and automatically creating, validating, and populating classes from/to XML, with support for 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 Details

    • XML

      public XML(Path file)

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

      Parameters:
      file - the XML file to parse
      See Also:

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

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

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

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

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

      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:

      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)