Package com.norconex.commons.lang.xml

Class Xml

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

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

XML syntax and white spaces

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

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

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

Checked exceptions are wrapped into an XmlException.

Since:
2.0.0

  • 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 interpreted as 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)
      Creates a new XML with the supplied root element (i.e., tag name), and populate it with the supplied object.
      Parameters:
      rootElement - XML root element name
      obj - the object to populate this XML with.
      See Also:

    • Xml

      public Xml(Node node)

      Creates an XML with the given DOM node.

      Parameters:
      node - the node representing the XML

  • Method Details

    • of

      public static Xml.Builder of(File file)

    • of

      public static Xml.Builder of(Path path)

    • of

      public static Xml.Builder of(Node node)

    • of

      public static Xml.Builder of(InputStream is)

    • of

      public static Xml.Builder of(Reader reader)

    • of

      public static Xml.Builder of(String xml)

    • of

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

    • populate

      public void populate(Object targetObject, String xpathExpression)

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

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

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

    • populate

      public void populate(Object targetObject)

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

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

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

      Parameters:
      targetObject - object to populate with this XML

    • toObject

      public <T> T toObject()

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

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

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

    • toObject

      public <T> T toObject(T defaultObject)

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

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

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

    • toObjectImpl

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

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

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

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

    • toObjectImpl

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

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

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

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

    • getObject

      public <T> T getObject(String xpathExpression)

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

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

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

    • getObject

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

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

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

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

    • getObjectList

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

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

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

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

    • getObjectList

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

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

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

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

    • getObjectImpl

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

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

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

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

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

    • getObjectImpl

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

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

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

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

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

    • getObjectListImpl

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

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

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

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

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

    • getObjectListImpl

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

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

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

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

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

    • getDelimitedList

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

    • getDelimitedList

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

    • getDelimitedList

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

    • getDelimitedList

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

    • getXML

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

    • getXMLList

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

    • getNode

      public Node getNode(String xpathExpression)

    • getNode

      public Node getNode()

    • toNode

      public Node toNode()

    • getString

      public String getString(String xpathExpression)

    • getString

      public String getString(String xpathExpression, String defaultValue)

    • getStringList

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

    • getStringList

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

    • getDelimitedStringList

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

    • getDelimitedStringList

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

    • getDelimitedStringList

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

    • getDelimitedStringList

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

    • getEnum

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

    • getEnum

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

    • getEnumList

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

    • getDelimitedEnumList

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

    • getDelimitedEnumList

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

    • getPath

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

    • getPath

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

    • getPathList

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

    • getPathList

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

    • getFile

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

    • getFile

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

    • getFileList

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

    • getFileList

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

    • getURL

      public final URL getURL(String xpathExpression)

    • getURL

      public final URL getURL(String xpathExpression, URL defaultValue)

    • getURLList

      public final List<URL> getURLList(String xpathExpression)

    • getURLList

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

    • getInteger

      public Integer getInteger(String xpathExpression)

    • getInteger

      public Integer getInteger(String xpathExpression, Integer defaultValue)

    • getLong

      public Long getLong(String xpathExpression)

    • getLong

      public Long getLong(String xpathExpression, Long defaultValue)

    • getFloat

      public Float getFloat(String xpathExpression)

    • getFloat

      public Float getFloat(String xpathExpression, Float defaultValue)

    • getDimension

      public Dimension getDimension(String xpathExpression)

    • getDimension

      public Dimension getDimension(String xpathExpression, Dimension defaultValue)

    • getDouble

      public Double getDouble(String xpathExpression)

    • getDouble

      public Double getDouble(String xpathExpression, Double defaultValue)

    • getBoolean

      public Boolean getBoolean(String xpathExpression)

    • getBoolean

      public Boolean getBoolean(String xpathExpression, Boolean defaultValue)

    • getLocale

      public Locale getLocale(String xpathExpression)

    • getLocale

      public Locale getLocale(String xpathExpression, Locale defaultValue)

    • getCharset

      public Charset getCharset(String xpathExpression)

    • getCharset

      public Charset getCharset(String xpathExpression, Charset defaultValue)

    • getDataSize

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

    • getDataSize

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

    • getDataSize

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

    • getDurationMillis

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

    • getDurationMillis

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

    • getDuration

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

    • getDuration

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

    • getPattern

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

    • getPattern

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

    • validate

      public void validate()

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

      Error handling

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

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

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

      See Also:

    • validate

      public void validate(Object obj)

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

      Error handling

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

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

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

      Parameters:
      obj - the object used to locate the XML schema used for validation
      See Also:

    • validate

      public void validate(Class<?> clazz)

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

      Error handling

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

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

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

    • isEnabled

      public boolean isEnabled()

    • isDisabled

      public boolean isDisabled()

    • isElementPresent

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

    • ifXML

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

    • toReader

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

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

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

    • toString

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

    • forEach

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

    • assertWriteRead

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

    • contains

      public boolean contains(String xpathExpression)

    • newXPath

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

    • newXPathExpression

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

    • get

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

    • get

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

    • getList

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

    • getList

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

    • getStringMap

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

    • getStringMap

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

    • getName

      public String getName()

    • computeElementIfAbsent

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

    • addElement

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

    • addElement

      public Xml addElement(String tagName, Object value)

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

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

    • addElementList

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

    • addElementList

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

    • addDelimitedElementList

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

    • addDelimitedElementList

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

    • addElementMap

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

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

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

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

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

    • addElementMap

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

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

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

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

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

    • removeElement

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

    • remove

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

    • insertBefore

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

    • insertAfter

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

    • setAttribute

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

    • setAttributes

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

    • setDelimitedAttributeList

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

    • setDelimitedAttributeList

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

    • removeAttribute

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

    • setTextContent

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

    • getTextContent

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

    • removeTextContent

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

    • addXML

      public Xml addXML(Reader xml)

    • addXML

      public Xml addXML(String xml)

    • addXML

      public Xml addXML(Xml xml)

    • getXMLWriter

      public Writer getXMLWriter()

    • getXMLStreamWriter

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

    • write

      public void write(Writer writer)

    • write

      public void write(Writer writer, int indent)

    • write

      public void write(File file)

    • write

      public void write(File file, int indent)

    • unwrap

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

    • rename

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

    • wrap

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

    • clear

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

    • isEmpty

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

    • hasChildElements

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

    • hasAttributes

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

    • hasTextContent

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

    • replace

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

    • getClass

      public Class<?> getClass(String xpathExpression)

    • getClass

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

    • getClassList

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

    • getClassList

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

    • parseXML

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

    • parseXML

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

    • parseXMLList

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

    • parseXMLList

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

    • parseXMLMap

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

    • parseXMLMap

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

    • checkDeprecated

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

    • checkDeprecated

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

    • getErrorHandler

      public ErrorHandler getErrorHandler()

    • getDocumentBuilderFactory

      public DocumentBuilderFactory getDocumentBuilderFactory()

    • isXMLConfigurable

      public static boolean isXMLConfigurable(Object obj)

    • isJAXB

      public static boolean isJAXB(Object obj)

    • iterator

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

    • stream

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

    • iterator

      public static Iterator<XmlCursor> iterator(Object obj)

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

      The object argument type must be one of the following:

      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

    • join

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