Module org.tquadrat.foundation.xml

Package org.tquadrat.foundation.xml.builder

Class XMLBuilderUtils

java.lang.Object

org.tquadrat.foundation.xml.builder.XMLBuilderUtils

@UtilityClass
@ClassVersion(sourceVersion="$Id: XMLBuilderUtils.java 1101 2024-02-18 00:18:48Z tquadrat $")
@API(status=STABLE,
     since="0.0.5")
public final class XMLBuilderUtils
extends Object

A collection of XML related utility methods and factory methods for XML elements.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: XMLBuilderUtils.java 1101 2024-02-18 00:18:48Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.xml.builder.XMLBuilderUtils"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	XMLBuilderUtils.Validator	The (default) validators.
static class	XMLBuilderUtils.ValidatorChangeEvent	The EventObject for changes to the validator configuration.
static interface	XMLBuilderUtils.ValidatorChangeListener	The interface for listeners to XMLBuilderUtils.ValidatorChangeEvents

Field Summary

Fields

Modifier and Type	Field	Description
private static final AtomicReference<Predicate<CharSequence>>	m_AttributeNameValidator	The method that validates an XML attribute name.
private static final AtomicReference<Predicate<CharSequence>>	m_ElementNameValidator	The method that validates an XML element name.
private static final Pattern	m_NMTokenPattern	The pattern that is used to validate a nmtoken.
private static final AtomicReference<Predicate<CharSequence>>	m_NMTokenValidator	The method that validates an XML nmtoken.
private static final AtomicReference<Predicate<CharSequence>>	m_PrefixValidator	The method that validates an XML namespace prefix.
private static final Collection<WeakReference<XMLBuilderUtils.ValidatorChangeListener>>	m_ValidatorChangeListeners	The validator change listeners.
private static final Pattern	m_XMLNamePattern	The pattern that is used to validate an XML name.
private static final String	XML_NAME_FirstChar	The regular expression for a valid start character of an XML name.
private static final String	XML_NAME_OtherChar	The regular expression for a character that is valid for an XML after the first character.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	XMLBuilderUtils()	No instance allowed for this class.

Method Summary

Modifier and Type	Method	Description
static final void	addValidatorChangeListener(XMLBuilderUtils.ValidatorChangeListener listener)	Adds a validator change listener.
static final ProcessingInstruction	composeXMLHeader(Charset encoding, boolean standalone)	Composes the ProcessingInstruction for the XML file header.
static final ProcessingInstruction	createProcessingInstruction(String elementName)	Creates a ProcessingInstruction.
static final ProcessingInstruction	createProcessingInstruction(String elementName, CharSequence data)	Creates a ProcessingInstruction.
static final ProcessingInstruction	createProcessingInstruction(XMLDocument parent, String elementName)	Creates a ProcessingInstruction.
static final ProcessingInstruction	createProcessingInstruction(XMLDocument parent, String elementName, CharSequence data)	Creates a ProcessingInstruction.
static final XMLDocument	createXMLDocument()	Creates an XML document that will not have an explicit doc type, the root element will be <root>
static final XMLDocument	createXMLDocument(String elementName)	Creates an XML document that uses the given element name for the root element.
static final XMLDocument	createXMLDocument(XMLElement rootElement)	Creates an XML document that uses the given element for the root element.
static final XMLDocument	createXMLDocument(XMLElement rootElement, boolean standalone)	Creates an XML document that uses the given element for the root element.
static final XMLDocument	createXMLDocument(XMLElement rootElement, Charset encoding, String name, URI uri)	Creates an XML document that uses the given element for the root element with the given encoding and DTD.
static final XMLDocument	createXMLDocument(XMLElement rootElement, Charset encoding, URI uri)	Creates an XML document that uses the given element for the root element with the given encoding and DTD.
static final XMLElement	createXMLElement(String elementName)	Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments. The given element name is validated using the method that is provided by getElementNameValidator(). The new element allows attributes and children, but will not validate them.
static final XMLElement	createXMLElement(String elementName, CharSequence text)	Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments, and add the given text.
static final XMLElement	createXMLElement(String elementName, XMLDocument parent)	Creates an XML element for the given tag and adds it as child to the given document. The given element name is validated using the method that is provided by getElementNameValidator(). The new element allows attributes and children, but will not validate them.
static final XMLElement	createXMLElement(String elementName, XMLDocument parent, CharSequence text)	Creates an XML element for the given tag and with the given text, and adds it as child to the given document. The given element name is validated using the method that is provided by getElementNameValidator(). The new element allows attributes and children, but will not validate them.
static final XMLElement	createXMLElement(String elementName, XMLElement parent)	Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments, and adds it as child to the given parent. The given element name is validated using the method that is provided by getElementNameValidator(). The new element allows attributes and children, but will not validate them.
static final XMLElement	createXMLElement(String elementName, XMLElement parent, CharSequence text)	Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments, adds the given text, and adds it as child to the given parent. The given element name is validated using the method that is provided by getElementNameValidator(). The new element allows attributes and children, but will not validate them.
static void	escapeXML(Appendable appendable, CharSequence input)	Escapes the characters in a String using XML entities and writes them to an Appendable. For example: "bread" & "butter" becomes: &quot;bread&quot; &amp; &quot;butter&quot;. Delegates to StringUtils.escapeXML(Appendable,CharSequence).
static String	escapeXML(CharSequence input)	Escapes the characters in a String using XML entities. For example: "bread" & "butter" becomes: &quot;bread&quot; &amp; &quot;butter&quot;. Delegates to StringUtils.escapeXML(CharSequence).
static final Predicate<CharSequence>	getAttributeNameValidator()	Returns the method to validate attribute names.
static final Predicate<CharSequence>	getElementNameValidator()	Returns the method to validate element names.
static final Predicate<CharSequence>	getNMTokenValidator()	Returns the method to validate nmtokens.
static final Predicate<CharSequence>	getPrefixValidator()	Returns the method to validate prefixes.
private static final boolean	isValidAttributeName(CharSequence attributeName)	The default implementation for an attribute name validator.
private static final boolean	isValidElementName(CharSequence elementName)	The default implementation for an element name validator.
private static final boolean	isValidNMToken(CharSequence nmtoken)	The default implementation for an NMToken validator.
private static final boolean	isValidPrefix(CharSequence prefix)	The default implementation for a prefix validator.
static final void	removeValidatorChangeListener(XMLBuilderUtils.ValidatorChangeListener listener)	Removes the given validator change listener.
static final void	restoreDefaultValidators()	Sets the validators back to the default configuration.
static final void	setAttributeNameValidator(Predicate<CharSequence> validator)	Sets the method to validate attribute names.
static final void	setElementNameValidator(Predicate<CharSequence> validator)	Sets the method to validate element names.
static final void	setNMTokenValidator(Predicate<CharSequence> validator)	Sets the method to validate nmtokens.
static final void	setPrefixValidator(Predicate<CharSequence> validator)	Sets the method to validate prefixes.
static final String	stripXMLComments(CharSequence input)	Strips HTML or XML comments from the given String.
static final void	unescapeXML(Appendable appendable, CharSequence input)	Unescapes an XML String containing XML entity escapes to a String containing the actual Unicode characters corresponding to the escapes and writes it to the given Appendable. If an entity is unrecognised, it is left alone, and inserted verbatim into the result string. e.g.
static final String	unescapeXML(CharSequence input)	Unescapes an XML string containing XML entity escapes to a string containing the actual Unicode characters corresponding to the escapes. If an entity is unrecognised, it is left alone, and inserted verbatim into the result string. e.g.

Methods inherited from class java.lang.Object

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

Field Details

XML_NAME_FirstChar

private static final String XML_NAME_FirstChar

The regular expression for a valid start character of an XML name. Usually, the colon (':') is also allowed, but for namespace aware parsers, this is used as the separator between the namespace prefix and the name itself.

See Also:

• Constant Field Values

XML_NAME_OtherChar

private static final String XML_NAME_OtherChar

The regular expression for a character that is valid for an XML after the first character. Usually, the colon (':') is also allowed, but for namespace aware parsers, this is used as the separator between the namespace prefix and the name itself.

See Also:

• Constant Field Values

m_ValidatorChangeListeners

private static final Collection<WeakReference<XMLBuilderUtils.ValidatorChangeListener>> m_ValidatorChangeListeners

The validator change listeners.

m_AttributeNameValidator

private static final AtomicReference<Predicate<CharSequence>> m_AttributeNameValidator

The method that validates an XML attribute name.

m_ElementNameValidator

private static final AtomicReference<Predicate<CharSequence>> m_ElementNameValidator

The method that validates an XML element name.

m_NMTokenPattern

private static final Pattern m_NMTokenPattern

The pattern that is used to validate a nmtoken.

m_NMTokenValidator

private static final AtomicReference<Predicate<CharSequence>> m_NMTokenValidator

The method that validates an XML nmtoken.

m_PrefixValidator

private static final AtomicReference<Predicate<CharSequence>> m_PrefixValidator

The method that validates an XML namespace prefix.

m_XMLNamePattern

private static final Pattern m_XMLNamePattern

The pattern that is used to validate an XML name.

Constructor Details

XMLBuilderUtils

private XMLBuilderUtils()

No instance allowed for this class.

Method Details

addValidatorChangeListener

@API(status=STABLE,
     since="0.0.5")
public static final void addValidatorChangeListener(XMLBuilderUtils.ValidatorChangeListener listener)

Adds a validator change listener.

Parameters:

listener - The listener.

composeXMLHeader

@API(status=STABLE,
     since="0.0.5")
public static final ProcessingInstruction composeXMLHeader(Charset encoding,
 boolean standalone)

Composes the ProcessingInstruction for the XML file header.

Parameters:

encoding - The encoding for the resulting document.

standalone - true if the XML document is standalone, false if not.

Returns:

The new processing instruction.

createProcessingInstruction

@API(status=STABLE,
     since="0.0.5")
public static final ProcessingInstruction createProcessingInstruction(String elementName)

Creates a ProcessingInstruction.

Parameters:

elementName - The name for the processing instruction.

Returns:

The new processing instruction.

createProcessingInstruction

@API(status=STABLE,
     since="0.0.5")
public static final ProcessingInstruction createProcessingInstruction(XMLDocument parent,
 String elementName)

Creates a ProcessingInstruction.

Parameters:

parent - The document that owns the new procession instruction.

elementName - The name for the processing instruction.

Returns:

The new processing instruction.

createProcessingInstruction

@API(status=STABLE,
     since="0.0.5")
public static final ProcessingInstruction createProcessingInstruction(String elementName,
 CharSequence data)

Creates a ProcessingInstruction.

Parameters:

elementName - The name for the processing instruction.

data - The data for the processing instruction.

Returns:

The new processing instruction.

createProcessingInstruction

@API(status=STABLE,
     since="0.0.5")
public static final ProcessingInstruction createProcessingInstruction(XMLDocument parent,
 String elementName,
 CharSequence data)

Creates a ProcessingInstruction.

Parameters:

parent - The document that owns the new procession instruction.

elementName - The name for the processing instruction.

data - The data for the processing instruction.

Returns:

The new processing instruction.

createXMLDocument

@API(status=STABLE,
     since="0.0.5")
public static final XMLDocument createXMLDocument()

Creates an XML document that will not have an explicit doc type, the root element will be <root>. The encoding is defined as UTF-8.

Basically, this document would have the DTD

<!ELEMENT root ANY>

.

The root element allows attributes and children, but will not validate them. It also allows text.

Returns:

The new XML document.

createXMLDocument

@API(status=STABLE,
     since="0.0.5")
public static final XMLDocument createXMLDocument(String elementName)

Creates an XML document that uses the given element name for the root element.

The given element name is validated using the method that is provided by getElementNameValidator().

The created root element allows attributes and children, but will not validate them. It also allows text.

Parameters:

elementName - The element name.

Returns:

The new XML document.

createXMLDocument

@API(status=STABLE,
     since="0.0.5")
public static final XMLDocument createXMLDocument(XMLElement rootElement)

Creates an XML document that uses the given element for the root element.

Parameters:

rootElement - The root element.

Returns:

The new XML document.

createXMLDocument

@API(status=STABLE,
     since="0.0.5")
public static final XMLDocument createXMLDocument(XMLElement rootElement,
 boolean standalone)

Creates an XML document that uses the given element for the root element.

Parameters:

rootElement - The root element.

standalone - true for a standalone document, false otherwise.

Returns:

The new XML document.

createXMLDocument

@API(status=STABLE,
     since="0.0.5")
public static final XMLDocument createXMLDocument(XMLElement rootElement,
 Charset encoding,
 String name,
 URI uri)

Creates an XML document that uses the given element for the root element with the given encoding and DTD.

Parameters:

rootElement - The root element for this document.

encoding - The encoding for the new XML document.

name - The name for the DTD.

uri - The URI for the DTD.

Returns:

The new XML document.

createXMLDocument

@API(status=STABLE,
     since="0.0.5")
public static final XMLDocument createXMLDocument(XMLElement rootElement,
 Charset encoding,
 URI uri)

Creates an XML document that uses the given element for the root element with the given encoding and DTD.

Parameters:

rootElement - The root element for this document.

encoding - The encoding for the new XML document.

uri - The URI for the DTD.

Returns:

The new XML document.

createXMLElement

@API(status=STABLE,
     since="0.0.5")
public static final XMLElement createXMLElement(String elementName)

Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments.

The given element name is validated using the method that is provided by getElementNameValidator().

The new element allows attributes and children, but will not validate them. It also allows text.

Parameters:

elementName - The element name.

Returns:

The new XML element.

createXMLElement

@API(status=STABLE,
     since="0.0.5")
public static final XMLElement createXMLElement(String elementName,
 CharSequence text)

Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments, and add the given text.

The given element name is validated using the method that is provided by getElementNameValidator().

The new element allows attributes and children, but will not validate them. It also allows text (obviously).

Parameters:

elementName - The element name.

text - The text for the new element.

Returns:

The new XML element.

createXMLElement

@API(status=STABLE,
     since="0.0.5")
public static final XMLElement createXMLElement(String elementName,
 XMLElement parent)

Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments, and adds it as child to the given parent.

The given element name is validated using the method that is provided by getElementNameValidator().

The new element allows attributes and children, but will not validate them. It also allows text.

Parameters:

elementName - The element name.

parent - The parent element.

Returns:

The new XML element.

createXMLElement

@API(status=STABLE,
     since="0.0.5")
public static final XMLElement createXMLElement(String elementName,
 XMLElement parent,
 CharSequence text)

Creates an XML element for the given element name that supports attributes, namespaces, children, text, CDATA and comments, adds the given text, and adds it as child to the given parent.

The given element name is validated using the method that is provided by getElementNameValidator().

The new element allows attributes and children, but will not validate them. It also allows text (obviously).

Parameters:

elementName - The element name.

parent - The parent element.

text - The text for the new element.

Returns:

The new XML element.

createXMLElement

@API(status=STABLE,
     since="0.0.5")
public static final XMLElement createXMLElement(String elementName,
 XMLDocument parent)

Creates an XML element for the given tag and adds it as child to the given document.

The given element name is validated using the method that is provided by getElementNameValidator().

The new element allows attributes and children, but will not validate them. It also allows text.

Parameters:

elementName - The element name.

parent - The document.

Returns:

The new XML element.

createXMLElement

@API(status=STABLE,
     since="0.0.5")
public static final XMLElement createXMLElement(String elementName,
 XMLDocument parent,
 CharSequence text)

Creates an XML element for the given tag and with the given text, and adds it as child to the given document.

The given element name is validated using the method that is provided by getElementNameValidator().

The new element allows attributes and children, but will not validate them. It also allows text (obviously).

Parameters:

elementName - The element name.

parent - The document.

text - The text for the new element.

Returns:

The new XML element.

escapeXML

@API(status=STABLE,
     since="0.0.5")
public static String escapeXML(CharSequence input)

Escapes the characters in a String using XML entities.

For example:

"bread" & "butter"

becomes:

"bread" & "butter".

Delegates to StringUtils.escapeXML(CharSequence).

Parameters:

input - The String to escape, may be null.

Returns:

A new escaped String, or null if the argument was already null.

See Also:

• unescapeXML(CharSequence)

escapeXML

@API(status=STABLE,
     since="0.0.5")
public static void escapeXML(Appendable appendable,
 CharSequence input)
                      throws IOException

Escapes the characters in a String using XML entities and writes them to an Appendable.

For example:

"bread" & "butter"

becomes:

"bread" & "butter".

Delegates to StringUtils.escapeXML(Appendable,CharSequence).

Parameters:

appendable - The appendable object receiving the escaped string.

input - The String to escape, may be null.

Throws:

NullArgumentException - The appendable is null.

IOException - when Appendable passed throws the exception from calls to the Appendable.append(char) method.

See Also:

• escapeXML(CharSequence)
• unescapeXML(CharSequence)

getAttributeNameValidator

@API(status=STABLE,
     since="0.0.5")
public static final Predicate<CharSequence> getAttributeNameValidator()

Returns the method to validate attribute names.

Returns:

The validator method.

getElementNameValidator

@API(status=STABLE,
     since="0.0.5")
public static final Predicate<CharSequence> getElementNameValidator()

Returns the method to validate element names.

Returns:

The validator method.

getNMTokenValidator

@API(status=STABLE,
     since="0.0.5")
public static final Predicate<CharSequence> getNMTokenValidator()

Returns the method to validate nmtokens.

Returns:

The validator method.

getPrefixValidator

@API(status=STABLE,
     since="0.0.5")
public static final Predicate<CharSequence> getPrefixValidator()

Returns the method to validate prefixes.

Returns:

The validator method.

isValidAttributeName

private static final boolean isValidAttributeName(CharSequence attributeName)

The default implementation for an attribute name validator.

Parameters:

attributeName - The name to test.

Returns:

true if the given name is valid, false otherwise.

See Also:

• getAttributeNameValidator()

isValidElementName

private static final boolean isValidElementName(CharSequence elementName)

The default implementation for an element name validator.

Parameters:

elementName - The name to test.

Returns:

true if the given name is valid, false otherwise.

See Also:

• getElementNameValidator()

isValidNMToken

private static final boolean isValidNMToken(CharSequence nmtoken)

The default implementation for an NMToken validator.

Parameters:

nmtoken - The NMToken to test.

Returns:

true if the given NMToke is valid, false otherwise.

See Also:

• getNMTokenValidator()

isValidPrefix

private static final boolean isValidPrefix(CharSequence prefix)

The default implementation for a prefix validator.

Parameters:

prefix - The prefix to test.

Returns:

true if the given prefix is valid, false otherwise.

See Also:

• getPrefixValidator()

removeValidatorChangeListener

@API(status=STABLE,
     since="0.0.5")
public static final void removeValidatorChangeListener(XMLBuilderUtils.ValidatorChangeListener listener)

Removes the given validator change listener.

Parameters:

listener - The listener to remove.

restoreDefaultValidators

@API(status=STABLE,
     since="0.0.5")
public static final void restoreDefaultValidators()

Sets the validators back to the default configuration. The current validators are abandoned.

See Also:

• getAttributeNameValidator()
• getElementNameValidator()
• getNMTokenValidator()
• getPrefixValidator()
• setAttributeNameValidator(Predicate)
• setElementNameValidator(Predicate)
• setNMTokenValidator(Predicate)
• setPrefixValidator(Predicate)

setAttributeNameValidator

@API(status=STABLE,
     since="0.0.5")
public static final void setAttributeNameValidator(Predicate<CharSequence> validator)

Sets the method to validate attribute names.

Parameters:

validator - The validator method.

setElementNameValidator

@API(status=STABLE,
     since="0.0.5")
public static final void setElementNameValidator(Predicate<CharSequence> validator)

Sets the method to validate element names.

Parameters:

validator - The validator method.

setNMTokenValidator

@API(status=STABLE,
     since="0.0.5")
public static final void setNMTokenValidator(Predicate<CharSequence> validator)

Sets the method to validate nmtokens.

Parameters:

validator - The validator method.

setPrefixValidator

@API(status=STABLE,
     since="0.0.5")
public static final void setPrefixValidator(Predicate<CharSequence> validator)

Sets the method to validate prefixes.

Parameters:

validator - The validator method.

stripXMLComments

@API(status=STABLE,
     since="0.0.5")
public static final String stripXMLComments(CharSequence input)

Strips HTML or XML comments from the given String.

Delegates to StringUtils.stripXMLComments(CharSequence).

Parameters:

input - The HTML/XML string.

Returns:

The string without the comments.

unescapeXML

@API(status=STABLE,
     since="0.0.5")
public static final String unescapeXML(CharSequence input)

Unescapes an XML string containing XML entity escapes to a string containing the actual Unicode characters corresponding to the escapes.

If an entity is unrecognised, it is left alone, and inserted verbatim into the result string. e.g. ">&zzzz;x" will become ">&zzzz;x".

Delegates to StringUtils.unescapeXML(CharSequence).

Parameters:

input - The String to unescape, may be null.

Returns:

A new unescaped String, null if the given string was already null.

See Also:

• escapeXML(CharSequence)
• escapeXML(Appendable,CharSequence)

unescapeXML

@API(status=STABLE,
     since="0.0.5")
public static final void unescapeXML(Appendable appendable,
 CharSequence input)
                              throws IOException

Unescapes an XML String containing XML entity escapes to a String containing the actual Unicode characters corresponding to the escapes and writes it to the given Appendable.

If an entity is unrecognised, it is left alone, and inserted verbatim into the result string. e.g. ">&zzzz;x" will become ">&zzzz;x".

Delegates to StringUtils.unescapeXML(Appendable,CharSequence).

Parameters:

appendable - The appendable receiving the unescaped string.

input - The String to unescape, may be null.

Throws:

NullArgumentException - The writer is null.

IOException - An IOException occurred.

See Also:

• escapeXML(CharSequence)