Module org.tquadrat.foundation.xml

Package org.tquadrat.foundation.xml.builder

Interface XMLDocument

All Superinterfaces:

Document<XMLElement>

All Known Implementing Classes:

XMLDocumentImpl

@ClassVersion(sourceVersion="$Id: XMLDocument.java 1071 2023-09-30 01:49:32Z tquadrat $")
@API(status=STABLE,
     since="0.0.5")
public sealed interface XMLDocument
extends Document<XMLElement>
permits XMLDocumentImpl

The definition for an XML document.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: XMLDocument.java 1071 2023-09-30 01:49:32Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

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

⁠

Method Summary

Modifier and Type	Method	Description
default XMLDocument	addChild(XMLElement child)	Adds a child to the root element of this document.
default XMLDocument	addComment(CharSequence comment)	Adds a comment to the root element of this document.
default XMLDocument	addDocumentComment(CharSequence comment)	Adds a comment to the document itself.
default XMLDocument	addPredefinedMarkup(CharSequence markup)	Adds predefined XML markup to the root element of this document.
default XMLDocument	addProcessingInstruction(ProcessingInstruction processingInstruction)	Adds a processing instruction to this document.
default XMLDocument	setAttribute(String name, boolean flag)	Sets the attribute with the given name to the root element of this document. The method uses Boolean.toString(boolean) to convert the provided flag to a String.
default XMLDocument	setAttribute(String name, double number)	Sets the attribute with the given name to the root element of this document. The method uses Double.toString(double) to convert the provided number to a String.
default XMLDocument	setAttribute(String name, int number)	Sets the attribute with the given name to the root element of this document. The method uses Integer.toString(int) to convert the provided number to a String.
default XMLDocument	setAttribute(String name, long number)	Sets the attribute with the given name to the root element of this document. The method uses Long.toString(long) to convert the provided number to a String.
default <E extends Enum<E>> XMLDocument	setAttribute(String name, E enumValue)	Sets the attribute with the given name to the root element of this document. The method uses Enum.name() to convert the provided value to a String.
default XMLDocument	setAttribute(String name, Boolean flag)	Sets the attribute with the given name to the root element of this document. The method uses Boolean.toString() to convert the provided flag to a String.
default XMLDocument	setAttribute(String name, CharSequence value)	Sets the attribute with the given name to the root element of this document.
default XMLDocument	setAttribute(String name, CharSequence value, Optional<? extends CharSequence> append)	Sets the attribute with the given name to the root element of this document.
default XMLDocument	setAttribute(String name, Number number)	Sets the attribute with the given name to the root element of this document. The method uses Object.toString() to convert the provided number to a String.
default XMLDocument	setAttribute(String name, Instant date)	Sets the attribute with the given name to the root element of this document. The method uses Instant.toString() to convert the provided number to a String.
default XMLDocument	setAttribute(String name, LocalDate date)	Sets the attribute with the given name to the root element of this document. The method uses LocalDate.toString() to convert the provided number to a String.
default XMLDocument	setAttribute(String name, LocalDateTime date)	Sets the attribute with the given name to the root element of this document. The method uses LocalDateTime.toString() to convert the provided number to a String.
default XMLDocument	setAttribute(String name, ZonedDateTime date)	Sets the attribute with the given name to the root element of this document. The method uses ZonedDateTime.toString() to convert the provided number to a String.
default XMLDocument	setAttributeIfNotEmpty(String name, CharSequence value)	Sets the attribute with the given name to the root element of this document if the provided value is not empty. The method uses StringUtils.isNotEmpty(CharSequence) to test if the given value is empty.
default XMLDocument	setAttributeIfNotEmpty(String name, Optional<? extends CharSequence> optional)	Sets the attribute with the given name to the root element of this document if the provided value is not empty.
default XMLDocument	setId(String id)	Sets the id for the root element of this document. The value will be validated using the method that is provided by a call to XMLBuilderUtils.getNMTokenValidator().
default XMLDocument	setNamespace(String identifier)	Sets the given namespace to the root element of this document.
default XMLDocument	setNamespace(String prefix, String identifier)	Sets the given namespace to the root element of this document. The given prefix is validated using the method that is provided by XMLBuilderUtils.getPrefixValidator().
default XMLDocument	setNamespace(String prefix, URI identifier)	Sets the given namespace to the root element of this document. The given prefix is validated using the method that is provided by XMLBuilderUtils.getPrefixValidator().
default XMLDocument	setNamespace(URI identifier)	Sets the given namespace to the root element of this document.
default XMLDocument	setNamespace(Namespace namespace)	Sets the given namespace to the root element of this document.

Methods inherited from interface org.tquadrat.foundation.xml.builder.spi.Document

getAttribute, getAttributes, getChildren, getElementName, getNamespaces, getRootElement, toString

Method Details

addChild

default XMLDocument addChild(XMLElement child)
                      throws IllegalArgumentException,
IllegalStateException

Adds a child to the root element of this document.

Parameters:

child - The child to add.

Returns:

This instance.

Throws:

IllegalArgumentException - The child is not allowed for the root element of this document, or the root element does not allow adding children at all.

IllegalStateException - The child has already a parent that is not the root XML element.

addComment

default XMLDocument addComment(CharSequence comment)
                        throws IllegalArgumentException

Adds a comment to the root element of this document.

Parameters:

comment - The comment to add.

Returns:

This instance.

Throws:

IllegalArgumentException - The root element does not allow adding comments.

addDocumentComment

default XMLDocument addDocumentComment(CharSequence comment)
                                throws IllegalArgumentException

Adds a comment to the document itself.

Parameters:

comment - The comment to add.

Returns:

This instance.

Throws:

IllegalArgumentException - The document does not allow adding comments.

addPredefinedMarkup

default XMLDocument addPredefinedMarkup(CharSequence markup)
                                 throws IllegalArgumentException

Adds predefined XML markup to the root element of this document. The given markup will not be validated, it just may not be null. So the caller is responsible that it will be proper XML.

As the markup may be formatted differently (or not formatted at all), the pretty printed output may be distorted when this is used.

Parameters:

markup - The XML markup.

Returns:

This instance.

Throws:

IllegalArgumentException - The root element does not allow adding children at all.

addProcessingInstruction

default XMLDocument addProcessingInstruction(ProcessingInstruction processingInstruction)
                                      throws IllegalArgumentException,
IllegalStateException

Adds a processing instruction to this document.

Parameters:

processingInstruction - The procession instruction to add.

Returns:

This instance.

Throws:

IllegalArgumentException - This document does not allow adding processing instructions.

IllegalStateException - The processing instruction has already a parent.

setAttribute

default XMLDocument setAttribute(String name,
 boolean flag)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Boolean.toString(boolean) to convert the provided flag to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

flag - The attribute's value.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 Boolean flag)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Boolean.toString() to convert the provided flag to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

flag - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 CharSequence value)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

Parameters:

name - The name of the attribute; the name is case-sensitive.

value - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 CharSequence value,
 Optional<? extends CharSequence> append)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

Parameters:

name - The name of the attribute; the name is case-sensitive.

value - The attribute's value; if null the attribute will be removed.

append - If not empty, the new value will be appended on an already existing one, and this sequence is used as the separator.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 double number)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Double.toString(double) to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

number - The attribute's value.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default <E extends Enum<E>> XMLDocument setAttribute(String name,
 E enumValue)
                                              throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Enum.name() to convert the provided value to a String.

Type Parameters:

E - The concrete enum type of value.

Parameters:

name - The name of the attribute; the name is case-sensitive.

enumValue - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 Instant date)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Instant.toString() to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

date - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 int number)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Integer.toString(int) to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

number - The attribute's value.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 LocalDate date)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses LocalDate.toString() to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

date - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 LocalDateTime date)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses LocalDateTime.toString() to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

date - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 long number)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Long.toString(long) to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

number - The attribute's value.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 Number number)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses Object.toString() to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

number - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttribute

default XMLDocument setAttribute(String name,
 ZonedDateTime date)
                          throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document.

The method uses ZonedDateTime.toString() to convert the provided number to a String.

Parameters:

name - The name of the attribute; the name is case-sensitive.

date - The attribute's value; if null the attribute will be removed.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttributeIfNotEmpty

default XMLDocument setAttributeIfNotEmpty(String name,
 CharSequence value)
                                    throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document if the provided value is not empty.

The method uses StringUtils.isNotEmpty(CharSequence) to test if the given value is empty.

Parameters:

name - The name of the attribute.

value - The value for the attribute; can be null.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setAttributeIfNotEmpty

default XMLDocument setAttributeIfNotEmpty(String name,
 Optional<? extends CharSequence> optional)
                                    throws IllegalArgumentException

Sets the attribute with the given name to the root element of this document if the provided value is not empty.

Parameters:

name - The name of the attribute.

optional - The value for the attribute.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

setId

default XMLDocument setId(String id)
                   throws IllegalArgumentException

Sets the id for the root element of this document.

The value will be validated using the method that is provided by a call to XMLBuilderUtils.getNMTokenValidator().

Parameters:

id - The id.

Returns:

This instance.

Throws:

IllegalArgumentException - The attribute is not allowed for the root element, or the root element does not allow attributes at all.

See Also:

• CommonConstants.XMLATTRIBUTE_Id

setNamespace

default XMLDocument setNamespace(String identifier)
                          throws IllegalArgumentException,
URISyntaxException

Sets the given namespace to the root element of this document.

Parameters:

identifier - The namespace identifier.

Returns:

This instance.

Throws:

IllegalArgumentException - Namespaces are not allowed for this element.

URISyntaxException - The provided URI String is invalid.

setNamespace

default XMLDocument setNamespace(URI identifier)
                          throws IllegalArgumentException

Sets the given namespace to the root element of this document.

Parameters:

identifier - The namespace identifier.

Returns:

This instance.

Throws:

IllegalArgumentException - Namespaces are not allowed for this element.

setNamespace

default XMLDocument setNamespace(String prefix,
 String identifier)
                          throws IllegalArgumentException,
URISyntaxException

Sets the given namespace to the root element of this document.

The given prefix is validated using the method that is provided by XMLBuilderUtils.getPrefixValidator().

Parameters:

prefix - The namespace prefix.

identifier - The namespace identifier.

Returns:

This instance.

Throws:

IllegalArgumentException - Namespaces are not allowed for this element.

URISyntaxException - The provided URI String is invalid.

setNamespace

default XMLDocument setNamespace(String prefix,
 URI identifier)
                          throws IllegalArgumentException

Sets the given namespace to the root element of this document.

The given prefix is validated using the method that is provided by XMLBuilderUtils.getPrefixValidator().

Parameters:

prefix - The namespace prefix.

identifier - The namespace identifier.

Returns:

This instance.

Throws:

IllegalArgumentException - Namespaces are not allowed for this element.

setNamespace

default XMLDocument setNamespace(Namespace namespace)
                          throws IllegalArgumentException

Sets the given namespace to the root element of this document.

Parameters:

namespace - The namespace.

Returns:

This instance.

Throws:

IllegalArgumentException - Namespaces are not allowed for this element.