de.caff.io.xml

Class XmlTool

java.lang.Object

de.caff.io.xml.XmlTool

public class XmlTool
extends java.lang.Object

Helper methods for XML handling.

This provides methods for both SAX and DOM handling.

Author:

Rammi

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	RELEASE_DATE The current version of the library.
static java.lang.String	XML_ATTR_VERSION Version attribute which should be used in a lot of cases.

Method Summary

Modifier and Type	Method and Description
static int	checkTagAndVersion(org.w3c.dom.Element element, java.lang.String tag, int maxVersion) Check that the given element has a defined tag name and contains an integer version attribute which is not higher than a given number.
static int	checkTagAndVersion(org.w3c.dom.Element element, java.lang.String tag, int minVersion, int maxVersion) Check that the given element has a defined tag name and contains an integer version attribute which is inside a given range.
static boolean	getBooleanValue(org.w3c.dom.Element element, java.lang.String attributeName) Get a boolean value from an attribute.
static boolean	getBooleanValue(org.w3c.dom.Element element, java.lang.String attributeName, boolean fallback) Get an optional boolean value from an attribute.
static boolean	getBooleanValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName) Get a boolean value from an attribute.
static boolean	getBooleanValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, boolean fallback) Get an optional boolean value from an attribute.
static java.util.List<org.w3c.dom.Element>	getChildElements(org.w3c.dom.Element element, java.lang.String tagName) Get the child elements with a given name.
static Indexable<org.w3c.dom.Element>	getChildren(org.w3c.dom.Element element, java.lang.String subElementTag) Get the direct children of an element with a given tag.
static Indexable<org.w3c.dom.Element>	getChildren(org.w3c.dom.Element element, java.lang.String subElementTag, int requiredSize) Get the direct children of an element with a given tag.
static java.lang.String	getContent(org.w3c.dom.Element element, boolean forceNonEmpty) Get the text content of the given element.
static double	getDoubleValue(org.w3c.dom.Element element, java.lang.String attributeName) Get a double value from an attribute.
static double	getDoubleValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName) Get a double value from an attribute.
static double	getDoubleValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, double fallback) Get an optional double value from an attribute.
static <E extends java.lang.Enum<E>> E	getEnumValue(org.w3c.dom.Element element, java.lang.String attributeName, java.lang.Class<E> enumClass) Get an enum value from an attribute.
static <E extends java.lang.Enum<E>> E	getEnumValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, java.lang.Class<E> enumClass) Get an enum value from an attribute.
static int	getIntValue(org.w3c.dom.Element element, java.lang.String attributeName) Get an integer value from an attribute.
static int	getIntValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName) Get an integer value from an attribute.
static int	getIntValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, int fallback) Get an optional integer value from an attribute.
static org.w3c.dom.Element	getOptionalSingleChild(org.w3c.dom.Element element, java.lang.String subElementTag) Get a optional singular sub element from a given element.
static java.lang.String	getOptionalValue(org.xml.sax.Attributes attributes, java.lang.String attributeName) Get the value of an optional attribute.
static <T> T	getOptionalValue(org.xml.sax.Attributes attributes, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor) Get an unwrapped value from an attribute.
static java.lang.String	getOptionalValue(org.w3c.dom.Element element, java.lang.String attributeName) Get the value of an optional attribute of the given element.
static <T> T	getOptionalValue(org.w3c.dom.Element element, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor) Get a unwrapped value from an attribute.
static <T,E extends java.lang.Exception> T	getOptionalValueF(org.xml.sax.Attributes attributes, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor) Get a unwrapped value from an attribute.
static <T,E extends java.lang.Exception> T	getOptionalValueF(org.w3c.dom.Element element, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor) Get a unwrapped value from an attribute.
static org.w3c.dom.Element	getSingleChild(org.w3c.dom.Element element) Get the single child of an element, require that it is an element itself.
static org.w3c.dom.Element	getSingleChild(org.w3c.dom.Element element, java.lang.String subElementTag) Get a singular sub element from a given element.
static java.lang.Boolean	getTriStateValue(org.w3c.dom.Element element, java.lang.String attributeName) Get a tri-state boolean value from an attribute.
static java.lang.Boolean	getTriStateValue(org.w3c.dom.Element element, java.lang.String attributeName, java.lang.Boolean fallback) Get a tri-state optional boolean value from an attribute.
static java.lang.Boolean	getTriStateValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName) Get a tri-state boolean value from an attribute.
static java.lang.Boolean	getTriStateValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, java.lang.Boolean fallback) Get an optional tri-state boolean value from an attribute.
static java.lang.String	getValue(org.xml.sax.Attributes attributes, java.lang.String attributeName, java.lang.String defaultValue) Get the value of the attribute of the given element.
static java.lang.String	getValue(org.w3c.dom.Element element, java.lang.String attributeName) Get the value of the attribute of the given element.
static <T> T	getValue(org.w3c.dom.Element element, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor) Get a unwrapped value from an attribute.
static java.lang.String	getValue(org.w3c.dom.Element element, java.lang.String attributeName, java.lang.String defaultValue) Get the value of the attribute of the given element.
static java.lang.String	getValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName) Get the value from attributes.
static <T> T	getValue(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, java.util.function.Function<java.lang.String,? extends T> extractor) /** Get a unwrapped value from an attribute.
static <T,E extends java.lang.Exception> T	getValueF(org.w3c.dom.Element element, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor) Get a unwrapped value from an attribute.
static <T,E extends java.lang.Exception> T	getValueF(java.lang.String elementTag, org.xml.sax.Attributes attributes, java.lang.String attributeName, FragileFunction1<? extends T,E,java.lang.String> extractor) Get a unwrapped value from an attribute.
static org.w3c.dom.Document	loadFromFile(java.lang.String path) Load a document from a file or URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RELEASE_DATE

public static final java.lang.String RELEASE_DATE

The current version of the library.

XML_ATTR_VERSION

public static final java.lang.String XML_ATTR_VERSION

Version attribute which should be used in a lot of cases. Use an integer as version indicator, then it is possible to use checkTagAndVersion(Element, String, int, int) and checkTagAndVersion(Element, String, int) to run a fast version check. It is recommended to start versions with 1 which allows to usage of the shorter check method.

See Also:

Constant Field Values

Method Detail

getValue

@NotNull
public static java.lang.String getValue(@NotNull
                                                 org.w3c.dom.Element element,
                                                 @NotNull
                                                 java.lang.String attributeName)
                                          throws org.xml.sax.SAXException

Get the value of the attribute of the given element. Throw an exception if it does not exist.

Parameters:

element - element containing attribute

attributeName - name of attribute

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent

getOptionalValue

@Nullable
public static java.lang.String getOptionalValue(@NotNull
                                                          org.w3c.dom.Element element,
                                                          @NotNull
                                                          java.lang.String attributeName)

Get the value of an optional attribute of the given element.

Parameters:

element - element containing attribute

attributeName - name of attribute

Returns:

value of attribute, or null if the attribute does not exist

getValue

public static <T> T getValue(@NotNull
                             org.w3c.dom.Element element,
                             @NotNull
                             java.lang.String attributeName,
                             @NotNull
                             java.util.function.Function<java.lang.String,? extends T> extractor)
                      throws org.xml.sax.SAXException

Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.

Type Parameters:

T - result type of this method

Parameters:

element - element containing attribute

attributeName - name of attribute

extractor - converter from the textual value to the expected value type

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - when the attribute does not exist, or when the extractor throws

getValueF

public static <T,E extends java.lang.Exception> T getValueF(@NotNull
                                                            org.w3c.dom.Element element,
                                                            @NotNull
                                                            java.lang.String attributeName,
                                                            @NotNull
                                                            FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                     throws org.xml.sax.SAXException

Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-

Type Parameters:

T - result type of this method

E - exception type of extractor

Parameters:

element - element containing attribute

attributeName - name of attribute

extractor - converter from the textual value to the expected value type which may throw an exception

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - when the attribute does not exist, or when the extractor throws an exception

getOptionalValue

@Nullable
public static <T> T getOptionalValue(@NotNull
                                               org.w3c.dom.Element element,
                                               @NotNull
                                               java.lang.String attributeName,
                                               @NotNull
                                               java.util.function.Function<java.lang.String,? extends T> extractor)

Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.

Type Parameters:

T - result type of this method

Parameters:

element - element containing attribute

attributeName - name of attribute

extractor - converter from the textual value to the expected value type

Returns:

value of attribute, or null if the value does not exist

getOptionalValueF

@Nullable
public static <T,E extends java.lang.Exception> T getOptionalValueF(@NotNull
                                                                              org.w3c.dom.Element element,
                                                                              @NotNull
                                                                              java.lang.String attributeName,
                                                                              @NotNull
                                                                              FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                                       throws E extends java.lang.Exception

Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-

Type Parameters:

T - result type of this method

E - exception type of extractor

Parameters:

element - element containing attribute

attributeName - name of attribute

extractor - converter from the textual value to the expected value type

Returns:

value of attribute, or null if the value does not exist

Throws:

E - when the extractor throws an exception

E extends java.lang.Exception

getValue

@NotNull
public static java.lang.String getValue(@NotNull
                                                 org.w3c.dom.Element element,
                                                 @NotNull
                                                 java.lang.String attributeName,
                                                 @NotNull
                                                 java.lang.String defaultValue)

Get the value of the attribute of the given element. Give back a default value if it does not exist.

Parameters:

element - element containing attribute

attributeName - name of attribute

defaultValue - default value

Returns:

value of attribute, or default value

getIntValue

public static int getIntValue(@NotNull
                              org.w3c.dom.Element element,
                              @NotNull
                              java.lang.String attributeName)
                       throws org.xml.sax.SAXException

Get an integer value from an attribute.

Parameters:

element - element containing attribute

attributeName - name of attribute

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not an integer value

getDoubleValue

public static double getDoubleValue(@NotNull
                                    org.w3c.dom.Element element,
                                    @NotNull
                                    java.lang.String attributeName)
                             throws org.xml.sax.SAXException

Get a double value from an attribute. This expects double to be in US format.

Parameters:

element - element containing attribute

attributeName - name of attribute

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not a double value

getBooleanValue

public static boolean getBooleanValue(@NotNull
                                      org.w3c.dom.Element element,
                                      @NotNull
                                      java.lang.String attributeName)
                               throws org.xml.sax.SAXException

Get a boolean value from an attribute.

Parameters:

element - element containing attribute

attributeName - name of attribute

Returns:

boolean value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not a boolean value

getBooleanValue

public static boolean getBooleanValue(@NotNull
                                      org.w3c.dom.Element element,
                                      @NotNull
                                      java.lang.String attributeName,
                                      boolean fallback)
                               throws org.xml.sax.SAXException

Get an optional boolean value from an attribute.

Parameters:

element - element containing attribute

attributeName - name of attribute

fallback - default value returned if attribute is not set

Returns:

boolean value of attribute

Throws:

org.xml.sax.SAXException - if attribute is not a boolean value

getTriStateValue

@Nullable
public static java.lang.Boolean getTriStateValue(@NotNull
                                                           org.w3c.dom.Element element,
                                                           @NotNull
                                                           java.lang.String attributeName)
                                                    throws org.xml.sax.SAXException

Get a tri-state boolean value from an attribute.

Parameters:

element - element containing attribute

attributeName - name of attribute

Returns:

tri-state boolean value of attribute, null for undefined

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not a boolean value

getTriStateValue

@Nullable
public static java.lang.Boolean getTriStateValue(@NotNull
                                                           org.w3c.dom.Element element,
                                                           @NotNull
                                                           java.lang.String attributeName,
                                                           @Nullable
                                                           java.lang.Boolean fallback)
                                                    throws org.xml.sax.SAXException

Get a tri-state optional boolean value from an attribute.

Parameters:

element - element containing attribute

attributeName - name of attribute

fallback - default value returned if attribute is not set

Returns:

tri-state boolean value of attribute, null for undefined

Throws:

org.xml.sax.SAXException - if attribute is not a boolean value

getEnumValue

@NotNull
public static <E extends java.lang.Enum<E>> E getEnumValue(@NotNull
                                                                    org.w3c.dom.Element element,
                                                                    @NotNull
                                                                    java.lang.String attributeName,
                                                                    @NotNull
                                                                    java.lang.Class<E> enumClass)
                                                             throws org.xml.sax.SAXException

Get an enum value from an attribute.

Type Parameters:

E - enum type

Parameters:

element - element containing attribute

attributeName - name of attribute

enumClass - enum class

Returns:

enum of given type

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not an enum of the given type

getValue

@NotNull
public static java.lang.String getValue(@NotNull
                                                 java.lang.String elementTag,
                                                 @NotNull
                                                 org.xml.sax.Attributes attributes,
                                                 @NotNull
                                                 java.lang.String attributeName)
                                          throws org.xml.sax.SAXException

Get the value from attributes. Throw an exception if it does not exist.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent

getValue

@NotNull
public static java.lang.String getValue(@NotNull
                                                 org.xml.sax.Attributes attributes,
                                                 @NotNull
                                                 java.lang.String attributeName,
                                                 @NotNull
                                                 java.lang.String defaultValue)

Get the value of the attribute of the given element. Give back a default value if it does not exist.

Parameters:

attributes - attributes of XML element

attributeName - name of attribute

defaultValue - default value

Returns:

value of attribute, or default value

getIntValue

public static int getIntValue(@NotNull
                              java.lang.String elementTag,
                              @NotNull
                              org.xml.sax.Attributes attributes,
                              @NotNull
                              java.lang.String attributeName)
                       throws org.xml.sax.SAXException

Get an integer value from an attribute.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not an integer value

getIntValue

public static int getIntValue(@NotNull
                              java.lang.String elementTag,
                              @NotNull
                              org.xml.sax.Attributes attributes,
                              @NotNull
                              java.lang.String attributeName,
                              int fallback)
                       throws org.xml.sax.SAXException

Get an optional integer value from an attribute.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

fallback - fallback value used if attribute is not defined

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is not an integer value

getDoubleValue

public static double getDoubleValue(@NotNull
                                    java.lang.String elementTag,
                                    @NotNull
                                    org.xml.sax.Attributes attributes,
                                    @NotNull
                                    java.lang.String attributeName)
                             throws org.xml.sax.SAXException

Get a double value from an attribute. This expects double to be in US format.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not a double value

getDoubleValue

public static double getDoubleValue(@NotNull
                                    java.lang.String elementTag,
                                    @NotNull
                                    org.xml.sax.Attributes attributes,
                                    @NotNull
                                    java.lang.String attributeName,
                                    double fallback)
                             throws org.xml.sax.SAXException

Get an optional double value from an attribute. This expects double to be in US format.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

fallback - fallback value returned if attribute is not defined

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - if attribute is not a double value

getBooleanValue

public static boolean getBooleanValue(@NotNull
                                      java.lang.String elementTag,
                                      @NotNull
                                      org.xml.sax.Attributes attributes,
                                      @NotNull
                                      java.lang.String attributeName)
                               throws org.xml.sax.SAXException

Get a boolean value from an attribute.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

Returns:

boolean value of attribute

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not a boolean value

getBooleanValue

public static boolean getBooleanValue(@NotNull
                                      java.lang.String elementTag,
                                      @NotNull
                                      org.xml.sax.Attributes attributes,
                                      @NotNull
                                      java.lang.String attributeName,
                                      boolean fallback)
                               throws org.xml.sax.SAXException

Get an optional boolean value from an attribute.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

fallback - default value returned if attribute is not set

Returns:

boolean value of attribute

Throws:

org.xml.sax.SAXException - if attribute is not a boolean value

getTriStateValue

@Nullable
public static java.lang.Boolean getTriStateValue(@NotNull
                                                           java.lang.String elementTag,
                                                           @NotNull
                                                           org.xml.sax.Attributes attributes,
                                                           @NotNull
                                                           java.lang.String attributeName)
                                                    throws org.xml.sax.SAXException

Get a tri-state boolean value from an attribute.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

Returns:

tri-state boolean value of attribute, null if undefined

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not a boolean value

getTriStateValue

@Nullable
public static java.lang.Boolean getTriStateValue(@NotNull
                                                           java.lang.String elementTag,
                                                           @NotNull
                                                           org.xml.sax.Attributes attributes,
                                                           @NotNull
                                                           java.lang.String attributeName,
                                                           @Nullable
                                                           java.lang.Boolean fallback)
                                                    throws org.xml.sax.SAXException

Get an optional tri-state boolean value from an attribute.

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

fallback - default value returned if attribute is not set

Returns:

tri-state boolean value of attribute, null if undefined

Throws:

org.xml.sax.SAXException - if attribute is not a boolean value

getEnumValue

@NotNull
public static <E extends java.lang.Enum<E>> E getEnumValue(@NotNull
                                                                    java.lang.String elementTag,
                                                                    @NotNull
                                                                    org.xml.sax.Attributes attributes,
                                                                    @NotNull
                                                                    java.lang.String attributeName,
                                                                    @NotNull
                                                                    java.lang.Class<E> enumClass)
                                                             throws org.xml.sax.SAXException

Get an enum value from an attribute.

Type Parameters:

E - enum type

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

enumClass - enum class

Returns:

enum of given type

Throws:

org.xml.sax.SAXException - if attribute is non-existent or not an enum of the given type

getValue

public static <T> T getValue(@NotNull
                             java.lang.String elementTag,
                             @NotNull
                             org.xml.sax.Attributes attributes,
                             @NotNull
                             java.lang.String attributeName,
                             @NotNull
                             java.util.function.Function<java.lang.String,? extends T> extractor)
                      throws org.xml.sax.SAXException

/** Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.

Type Parameters:

T - result type of this method

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

extractor - converter from the textual value to the expected value type

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - when the attribute does not exist, or when the extractor throws

getValueF

public static <T,E extends java.lang.Exception> T getValueF(@NotNull
                                                            java.lang.String elementTag,
                                                            @NotNull
                                                            org.xml.sax.Attributes attributes,
                                                            @NotNull
                                                            java.lang.String attributeName,
                                                            @NotNull
                                                            FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                     throws org.xml.sax.SAXException

Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-

Type Parameters:

T - result type of this method

E - exception type of extractor

Parameters:

elementTag - element tag, used for errors

attributes - attributes of XML element

attributeName - name of attribute

extractor - converter from the textual value to the expected value type which throws an exception

Returns:

value of attribute

Throws:

org.xml.sax.SAXException - when the attribute does not exist, or when the extractor throws an exception

getOptionalValue

@Nullable
public static java.lang.String getOptionalValue(@NotNull
                                                          org.xml.sax.Attributes attributes,
                                                          @NotNull
                                                          java.lang.String attributeName)

Get the value of an optional attribute.

Parameters:

attributes - attributes of XML element

attributeName - name of requested attribute

Returns:

attribute value, or null if attribute is not set

getOptionalValue

@Nullable
public static <T> T getOptionalValue(@NotNull
                                               org.xml.sax.Attributes attributes,
                                               @NotNull
                                               java.lang.String attributeName,
                                               @NotNull
                                               java.util.function.Function<java.lang.String,? extends T> extractor)

Get an unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object.

Type Parameters:

T - result type of this method

Parameters:

attributes - attributes of XML element

attributeName - name of attribute

extractor - converter from the textual value to the expected value type

Returns:

value of attribute, or null if the value does not exist

getOptionalValueF

@Nullable
public static <T,E extends java.lang.Exception> T getOptionalValueF(@NotNull
                                                                              org.xml.sax.Attributes attributes,
                                                                              @NotNull
                                                                              java.lang.String attributeName,
                                                                              @NotNull
                                                                              FragileFunction1<? extends T,E,java.lang.String> extractor)
                                                                       throws E extends java.lang.Exception

Get a unwrapped value from an attribute. This assumes that the textual value of the attribute is a string in a certain format which can be converted to an object of the required type. This method allows to use an extractor which can throw an exception-

Type Parameters:

T - result type of this method

E - exception type of extractor

Parameters:

attributes - attributes of XML element

attributeName - name of attribute

extractor - converter from the textual value to the expected value type

Returns:

value of attribute, or null if the value does not exist

Throws:

E - when the extractor throws an exception

E extends java.lang.Exception

getSingleChild

@NotNull
public static org.w3c.dom.Element getSingleChild(@NotNull
                                                          org.w3c.dom.Element element)
                                                   throws org.xml.sax.SAXException

Get the single child of an element, require that it is an element itself.

Parameters:

element - parent element

Returns:

single child element

Throws:

org.xml.sax.SAXException - if there is none or more than one child, or the single child is not an element

getSingleChild

@NotNull
public static org.w3c.dom.Element getSingleChild(@NotNull
                                                          org.w3c.dom.Element element,
                                                          @NotNull
                                                          java.lang.String subElementTag)
                                                   throws org.xml.sax.SAXException

Get a singular sub element from a given element. This will throw an exception if there is no given sub elements or if there are more than one.

Parameters:

element - element containing sub element

subElementTag - name of sub element

Returns:

sub element

Throws:

org.xml.sax.SAXException - if sub element is missing or appearing more than once

getOptionalSingleChild

@Nullable
public static org.w3c.dom.Element getOptionalSingleChild(@NotNull
                                                                   org.w3c.dom.Element element,
                                                                   @NotNull
                                                                   java.lang.String subElementTag)
                                                            throws org.xml.sax.SAXException

Get a optional singular sub element from a given element. This will throw an exception if there are more than one.

Parameters:

element - element containing sub element

subElementTag - name of sub element

Returns:

sub element, null if there is none

Throws:

org.xml.sax.SAXException - if sub element is missing or appearing more than once

getChildren

@NotNull
public static Indexable<org.w3c.dom.Element> getChildren(@NotNull
                                                                  org.w3c.dom.Element element,
                                                                  @NotNull
                                                                  java.lang.String subElementTag)
                                                           throws org.xml.sax.SAXException

Get the direct children of an element with a given tag.

Parameters:

element - element for which children are requested

subElementTag - sub element tag

Returns:

indexable view of the elements

Throws:

org.xml.sax.SAXException - if the required size is non-negative and not matched

See Also:

getChildren(Element, String, int)

getChildren

@NotNull
public static Indexable<org.w3c.dom.Element> getChildren(@NotNull
                                                                  org.w3c.dom.Element element,
                                                                  @NotNull
                                                                  java.lang.String subElementTag,
                                                                  int requiredSize)
                                                           throws org.xml.sax.SAXException

Get the direct children of an element with a given tag.

Parameters:

element - element for which children are requested

subElementTag - sub element tag

requiredSize - required and checked size if non-negative, ignored if negative

Returns:

indexable view of the elements

Throws:

org.xml.sax.SAXException - if the required size is non-negative and not matched

getContent

@NotNull
public static java.lang.String getContent(@NotNull
                                                   org.w3c.dom.Element element,
                                                   boolean forceNonEmpty)
                                            throws org.xml.sax.SAXException

Get the text content of the given element. This will throw an exception if the element does not have any content, or if it has sub elements.

Parameters:

element - element containing content

forceNonEmpty - force that element tag is not empty, i.e. <tag/%gt;?

Returns:

content of element

Throws:

org.xml.sax.SAXException - if there are other nodes than text or attribute, or if forceContent is true and the element uses an empty element tag

getChildElements

@NotNull
public static java.util.List<org.w3c.dom.Element> getChildElements(@NotNull
                                                                            org.w3c.dom.Element element,
                                                                            @NotNull
                                                                            java.lang.String tagName)

Get the child elements with a given name.

Parameters:

element - element for which child elements are requested

tagName - tag name of requested children

Returns:

list of child elements using the given tag name

loadFromFile

@NotNull
public static org.w3c.dom.Document loadFromFile(@NotNull
                                                         java.lang.String path)
                                                  throws javax.xml.parsers.ParserConfigurationException,
                                                         java.io.IOException,
                                                         org.xml.sax.SAXException

Load a document from a file or URL.

Parameters:

path - path of XML file

Returns:

document contained in file

Throws:

javax.xml.parsers.ParserConfigurationException - on parser config errors

java.io.IOException - on read errors

org.xml.sax.SAXException - on format errors

checkTagAndVersion

public static int checkTagAndVersion(@NotNull
                                     org.w3c.dom.Element element,
                                     @NotNull
                                     java.lang.String tag,
                                     int maxVersion)
                              throws org.xml.sax.SAXException

Check that the given element has a defined tag name and contains an integer version attribute which is not higher than a given number. This method assumes that the minimal version number is 1.

Parameters:

element - element to check

tag - required tag name of the element

maxVersion - required maximal version of the element

Returns:

the actual version found

Throws:

org.xml.sax.SAXException - if element has another tag name, no integer version attribute, or if the version is too high

checkTagAndVersion

public static int checkTagAndVersion(@NotNull
                                     org.w3c.dom.Element element,
                                     @NotNull
                                     java.lang.String tag,
                                     int minVersion,
                                     int maxVersion)
                              throws org.xml.sax.SAXException

Check that the given element has a defined tag name and contains an integer version attribute which is inside a given range.

Parameters:

element - element to check

tag - required tag name of the element

minVersion - required minimal version of the element

maxVersion - required maximal version of the element

Returns:

the actual version found

Throws:

org.xml.sax.SAXException - if element has another tag name, no integer version attribute, or if the version is too high