Module org.tquadrat.foundation.xml

Package org.tquadrat.foundation.xml.builder.internal

Class XMLElementImpl

java.lang.Object

org.tquadrat.foundation.xml.builder.internal.XMLElementImpl

All Implemented Interfaces:

Element, XMLElement

Direct Known Subclasses:

XMLElementAdapter

@ClassVersion(sourceVersion="$Id: XMLElementImpl.java 1086 2024-01-05 23:18:33Z tquadrat $")
@API(status=INTERNAL,
     since="0.0.5")
public sealed class XMLElementImpl
extends Object
implements XMLElement
permits XMLElementAdapter

An implementation of XMLElement that supports attributes, namespaces, children, text, CDATA and comments.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: XMLElementImpl.java 1086 2024-01-05 23:18:33Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.xml.builder.internal.XMLElementImpl"

⁠

Nested Class Summary

Nested classes/interfaces inherited from interface org.tquadrat.foundation.xml.builder.XMLElement

XMLElement.Flags

Field Summary

Fields

Modifier and Type	Field	Description
private final AttributeSupport	m_Attributes	The attribute support.
private final ChildSupport	m_Children	The child support.
private final String	m_ElementName	The element name.
private Element	m_Parent	The parent element.

Fields inherited from interface org.tquadrat.foundation.xml.builder.XMLElement

EMPTY_XMLElement_ARRAY, NO_APPEND

Constructor Summary

Constructors

Modifier	Constructor	Description
	XMLElementImpl(String elementName)	Creates a new XMLElementImpl instance.
protected	XMLElementImpl(String elementName, Set<XMLElement.Flags> flags)	Creates a new XMLElementImpl instance.

Method Summary

Modifier and Type	Method	Description
final XMLElement	addCDATA(CharSequence text)	Adds a CDATA element to this XML element.
final <E extends XMLElement> XMLElement	addChild(E child)	Adds a child to this element.
final XMLElement	addComment(CharSequence comment)	Adds a comment.
final XMLElement	addPredefinedMarkup(CharSequence markup)	Adds predefined markup.
final XMLElement	addText(CharSequence text)	Adds text to this element.
final Optional<String>	getAttribute(String name)	Returns the value for the attribute with the given name.
Map<String,String>	getAttributes()	Provides read access to the attributes.
Collection<? extends Element>	getChildren()	Provides access to the children for this element; the returned collection is not modifiable.
final String	getElementName()	Returns the name of the element.
final Set<XMLElement.Flags>	getFlags()	Returns the flags for this element.
final Collection<Namespace>	getNamespaces()	Provides access to the namespaces for this element; the returned collection is not modifiable.
final Optional<Element>	getParent()	Returns the parent of this element.
final Comparator<String>	getSortOrder()	Returns the attribute sort order.
boolean	hasChildren()	Returns true if the element has children, false otherwise.
final void	registerAttributeSequence(String... attributes)	Registers an attribute sequence for this element
final void	registerAttributeSequence(Comparator<String> sortOrder)	Registers an attribute sequence for this element; this modifies any sort order that was previously set.
final void	registerValidAttributes(String... attributes)	Registers the valid attributes for this element. Nothing happens if AttributeSupport.checksIfValid() returns false, although a call to this method is obsolete then.
final void	registerValidChildren(String... children)	Registers the element names of valid child elements for this element.
final Collection<String>	retrieveValidAttributes()	Returns the list of the registered attributes.
final Collection<String>	retrieveValidChildren()	Returns the list of the registered children.
final XMLElement	setAttribute(String name, CharSequence value, Optional<? extends CharSequence> append)	Sets the attribute with the given name.
final XMLElement	setNamespace(String identifier)	Sets the given namespace.
final XMLElement	setNamespace(String prefix, String identifier)	Sets the given namespace.
final XMLElement	setNamespace(String prefix, URI identifier)	Sets the given namespace.
final XMLElement	setNamespace(URI identifier)	Sets the given namespace.
final XMLElement	setNamespace(Namespace namespace)	Sets the given namespace.
final <E extends Element> void	setParent(E parent)	Sets the parent for this element.
String	toString()

Methods inherited from class java.lang.Object

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

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

isBlock, toString

Methods inherited from interface org.tquadrat.foundation.xml.builder.XMLElement

addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addCDATA, addText, addText, addText, addText, addText, addText, addText, addText, addText, addText, addText, addText, addText, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributeIfNotEmpty, setAttributeIfNotEmpty, setId

Field Details

m_Attributes

private final AttributeSupport m_Attributes

The attribute support.

m_Children

private final ChildSupport m_Children

The child support.

m_ElementName

private final String m_ElementName

The element name.

m_Parent

private Element m_Parent

The parent element.

Constructor Details

XMLElementImpl

public XMLElementImpl(String elementName)

Creates a new XMLElementImpl instance.

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

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

Note:

• This constructor is mainly used by the factory methods in for on-the-fly XML generation.

Parameters:

elementName - The element name.

XMLElementImpl

protected XMLElementImpl(String elementName,
 Set<XMLElement.Flags> flags)

Creates a new XMLElementImpl instance.

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

Note:

• This constructor is used for the implementation of XML specialisations, like SVG or HTML (although this not really XML). It is made accessible through

Parameters:

elementName - The element name.

flags - The configuration flags for the new element.

See Also:

• XMLElement.Flags
• AttributeSupport.registerAttributes(String...)
• AttributeSupport.registerSequence(String...)
• ChildSupport.registerChildren(String...)

Method Details

addCDATA

public final XMLElement addCDATA(CharSequence text)
                          throws IllegalArgumentException

Adds a CDATA element to this XML element.

Specified by:

addCDATA in interface XMLElement

Parameters:

text - The text.

Returns:

This instance.

Throws:

IllegalArgumentException

addChild

public final <E extends XMLElement> XMLElement addChild(E child)
                                                 throws IllegalArgumentException,
IllegalStateException

Adds a child to this element.

Specified by:

addChild in interface XMLElement

Type Parameters:

E - The implementation type for the children.

Parameters:

child - The child to add.

Returns:

This instance.

Throws:

IllegalArgumentException - The given child is not valid for this element.

IllegalStateException - The child has already a parent that is not this element.

addComment

public final XMLElement addComment(CharSequence comment)
                            throws IllegalArgumentException

Adds a comment.

Specified by:

addComment in interface XMLElement

Parameters:

comment - The comment text.

Returns:

This instance.

Throws:

IllegalArgumentException

addPredefinedMarkup

public final XMLElement addPredefinedMarkup(CharSequence markup)
                                     throws IllegalArgumentException

Adds predefined markup.

The given markup will not be validated, it just may not be null. So the caller is responsible that it will be proper markup.

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

Specified by:

addPredefinedMarkup in interface XMLElement

Parameters:

markup - The predefined markup.

Returns:

This instance.

Throws:

IllegalArgumentException

addText

public final XMLElement addText(CharSequence text)
                         throws IllegalArgumentException

Adds text to this element. Special characters will be escaped according to the rules for the respective SGML flavour.

Specified by:

addText in interface XMLElement

Parameters:

text - The text.

Returns:

This instance.

Throws:

IllegalArgumentException

getAttribute

public final Optional<String> getAttribute(String name)

Returns the value for the attribute with the given name.

Specified by:

getAttribute in interface Element

Parameters:

name - The attribute name.

Returns:

An instance of Optional that holds the value for that attribute.

getAttributes

public Map<String,String> getAttributes()

Provides read access to the attributes.

Specified by:

getAttributes in interface Element

Returns:

A reference to the attributes.

getChildren

public Collection<? extends Element> getChildren()

Provides access to the children for this element; the returned collection is not modifiable.

Specified by:

getChildren in interface Element

Returns:

A reference to the children of this element; if the element does not have children, an empty collection will be returned.

getElementName

public final String getElementName()

Returns the name of the element.

Specified by:

getElementName in interface Element

Returns:

The name of the element.

getFlags

public final Set<XMLElement.Flags> getFlags()

Returns the flags for this element.

Specified by:

getFlags in interface XMLElement

Returns:

The flags.

See Also:

• XMLElement.Flags

getNamespaces

public final Collection<Namespace> getNamespaces()

Provides access to the namespaces for this element; the returned collection is not modifiable.

Specified by:

getNamespaces in interface Element

Returns:

A reference to the namespaces of this element; if the element does not have namespaces assigned, an empty collection will be returned.

getParent

public final Optional<Element> getParent()

Returns the parent of this element.

Specified by:

getParent in interface Element

Returns:

An instance of Optional that holds the parent.

getSortOrder

public final Comparator<String> getSortOrder()

Returns the attribute sort order.

Returns:

The comparator that determines the attribute's sequence.

hasChildren

public boolean hasChildren()

Returns true if the element has children, false otherwise.

Specified by:

hasChildren in interface Element

Returns:

true if the element has children.

registerAttributeSequence

public final void registerAttributeSequence(String... attributes)

Registers an attribute sequence for this element; this modifies any sort order that was previously set.

The names for the attributes are not validated; in particular, it is not checked whether an attribute is listed as valid.

Parameters:

attributes - The names of the attributes in the desired sequence.

registerAttributeSequence

public final void registerAttributeSequence(Comparator<String> sortOrder)

Registers an attribute sequence for this element; this modifies any sort order that was previously set.

Parameters:

sortOrder - The sort order for the attributes.

registerValidAttributes

public final void registerValidAttributes(String... attributes)

Registers the valid attributes for this element.

Nothing happens if AttributeSupport.checksIfValid() returns false, although a call to this method is obsolete then.

Note:

• The given attributes will be added to the already existing ones!

Parameters:

attributes - The names of the valid attributes.

Throws:

InvalidXMLNameException - One of the attribute names is invalid.

registerValidChildren

public final void registerValidChildren(String... children)

Registers the element names of valid child elements for this element.

Note:

• The given children will be added to the already existing ones!

Parameters:

children - The element names of the valid children.

retrieveValidAttributes

public final Collection<String> retrieveValidAttributes()

Returns the list of the registered attributes.

Returns:

The registered attributes.

retrieveValidChildren

public final Collection<String> retrieveValidChildren()

Returns the list of the registered children.

Returns:

The registered children.

setAttribute

public final XMLElement setAttribute(String name,
 CharSequence value,
 Optional<? extends CharSequence> append)
                              throws IllegalArgumentException

Sets the attribute with the given name.

The given attribute name is validated using the method that is provided by XMLBuilderUtils.getAttributeNameValidator().

Specified by:

setAttribute in interface XMLElement

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 (XMLElement.NO_APPEND), the new value will be appended to an already existing one, and the provided char sequence is used as the separator.

Returns:

This instance.

Throws:

IllegalArgumentException - An attribute with the given name is not valid for the element

setNamespace

public final XMLElement setNamespace(String identifier)
                              throws IllegalArgumentException,
URISyntaxException

Sets the given namespace.

Specified by:

setNamespace in interface XMLElement

Parameters:

identifier - The namespace identifier.

Returns:

This instance.

Throws:

URISyntaxException - The provided URI String is invalid.

IllegalArgumentException

setNamespace

public final XMLElement setNamespace(URI identifier)
                              throws IllegalArgumentException

Sets the given namespace.

Specified by:

setNamespace in interface XMLElement

Parameters:

identifier - The namespace identifier.

Returns:

This instance.

Throws:

IllegalArgumentException

setNamespace

public final XMLElement setNamespace(String prefix,
 String identifier)
                              throws IllegalArgumentException,
URISyntaxException

Sets the given namespace.

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

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

Specified by:

setNamespace in interface XMLElement

Parameters:

prefix - The namespace prefix.

identifier - The namespace identifier.

Returns:

This instance.

Throws:

URISyntaxException - The provided URI String is invalid.

IllegalArgumentException

setNamespace

public final XMLElement setNamespace(String prefix,
 URI identifier)
                              throws IllegalArgumentException

Sets the given namespace.

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

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

Specified by:

setNamespace in interface XMLElement

Parameters:

prefix - The namespace prefix.

identifier - The namespace identifier.

Returns:

This instance.

Throws:

IllegalArgumentException

setNamespace

public final XMLElement setNamespace(Namespace namespace)
                              throws IllegalArgumentException

Sets the given namespace.

Specified by:

setNamespace in interface XMLElement

Parameters:

namespace - The namespace.

Returns:

This instance.

Throws:

IllegalArgumentException

setParent

public final <E extends Element> void setParent(E parent)

Sets the parent for this element.

Specified by:

setParent in interface Element

Specified by:

setParent in interface XMLElement

Type Parameters:

E - The implementation of Element.

Parameters:

parent - The parent.

toString

public String toString()

Overrides:

toString in class Object