Module org.tquadrat.foundation.xml

Package org.tquadrat.foundation.xml.builder.spi

Class AttributeSupport

java.lang.Object

org.tquadrat.foundation.xml.builder.spi.NamespaceSupport

org.tquadrat.foundation.xml.builder.spi.AttributeSupport

@ClassVersion(sourceVersion="$Id: AttributeSupport.java 1071 2023-09-30 01:49:32Z tquadrat $")
@API(status=MAINTAINED,
     since="0.0.5")
public final class AttributeSupport
extends NamespaceSupport

This class provides the support for attributes to elements.

For some SGML elements, their attributes should be ordered in a given sequence, either because of convenience or because of deficits of the parser processing them.

This class provides a specific comparator for each named element that can be configured by the user.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

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

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.xml.builder.spi.AttributeSupport"

⁠

Field Summary

Fields

Modifier and Type	Field	Description
private static final Comparator<String>	DEFAULT_COMPARATOR	The default comparator that is used for attribute ordering if no other comparator is provided.
static final Comparator<String>	ID_ALWAYS_FIRST_COMPARATOR	A Comparator that ensures that "xml:id" is always the first attribute.
private final Map<String,String>	m_Attributes	The attributes for the element.
private final boolean	m_CheckValid	Flag that indicates whether the validity of attributes should be checked.
private Comparator<String>	m_Comparator	The comparator that determines the sequence for the attributes of the owning element.
private final Collection<String>	m_ValidAttributes	The valid attributes for owning element.

Constructor Summary

Constructors

Constructor	Description
AttributeSupport(Element owner)	Creates a new AttributeSupport instance that checks whether attributes are valid to be added.
AttributeSupport(Element owner, boolean checkValid)	Creates a new AttributeSupport instance.
AttributeSupport(Element owner, boolean checkValid, Comparator<String> sortOrder)	Creates a new AttributeSupport instance.
AttributeSupport(Element owner, Comparator<String> sortOrder)	Creates a new AttributeSupport instance that checks whether attributes are valid to be added.

Method Summary

Modifier and Type	Method	Description
final boolean	checksIfValid()	Returns a flag that indicates whether an extended validity check is performed on attributes before adding them.
final boolean	checkValid(String attribute)	Checks whether an attribute with the given name is valid for the owning element.
final Optional<String>	getAttribute(String name)	Returns the value for the attribute with the given name.
final Map<String,String>	getAttributes()	Provides read access to the attributes.
final Comparator<String>	getSortOrder()	Returns the attribute sort order.
final void	registerAttributes(String... attributes)	Registers the valid attributes for the owning element.
final void	registerSequence(String... attributes)	Registers an attribute sequence for the owning element; this modifies any sort order that was previously set.
final Collection<String>	retrieveValidAttributes()	Returns the list of the registered attributes.
final Optional<String>	setAttribute(String name, CharSequence value, Optional<? extends CharSequence> append)	Sets the attribute with the given name.
final void	setSortOrder(Comparator<String> sortOrder)	Sets the comparator that determines the sequence of the attributes for the owning element.
final String	toString(int indentationLevel, boolean prettyPrint)	Returns the attributes and their values, together with the namespaces, as a single formatted string.

Methods inherited from class org.tquadrat.foundation.xml.builder.spi.NamespaceSupport

getNamespaces, getOwner, setNamespace, setNamespace, setNamespace, setNamespace, setNamespace

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_COMPARATOR

private static final Comparator<String> DEFAULT_COMPARATOR

The default comparator that is used for attribute ordering if no other comparator is provided.

ID_ALWAYS_FIRST_COMPARATOR

public static final Comparator<String> ID_ALWAYS_FIRST_COMPARATOR

A Comparator that ensures that "xml:id" is always the first attribute.

m_Attributes

private final Map<String,String> m_Attributes

The attributes for the element.

m_CheckValid

private final boolean m_CheckValid

Flag that indicates whether the validity of attributes should be checked.

m_Comparator

private Comparator<String> m_Comparator

The comparator that determines the sequence for the attributes of the owning element.

m_ValidAttributes

private final Collection<String> m_ValidAttributes

The valid attributes for owning element.

Constructor Details

AttributeSupport

public AttributeSupport(Element owner)

Creates a new AttributeSupport instance that checks whether attributes are valid to be added.

Parameters:

owner - The element that owns this AttributeSupport instance.

AttributeSupport

public AttributeSupport(Element owner,
 boolean checkValid)

Creates a new AttributeSupport instance.

Parameters:

owner - The element that owns this AttributeSupport instance.

checkValid - true when the validity of attributes should be checked, false if all attributes can be added.

AttributeSupport

public AttributeSupport(Element owner,
 Comparator<String> sortOrder)

Creates a new AttributeSupport instance that checks whether attributes are valid to be added.

Parameters:

owner - The element that owns this AttributeSupport instance.

sortOrder - The comparator that determines the sort order for the attribute of the owning element.

AttributeSupport

public AttributeSupport(Element owner,
 boolean checkValid,
 Comparator<String> sortOrder)

Creates a new AttributeSupport instance.

Parameters:

owner - The element that owns this AttributeSupport instance.

checkValid - true when the validity of attributes should be checked, false if all attributes can be added.

sortOrder - The comparator that determines the sort order for the attribute of the owning element.

Method Details

checkValid

public final boolean checkValid(String attribute)
                         throws InvalidXMLNameException

Checks whether an attribute with the given name is valid for the owning element.

The attribute is valid if there is a respective entry in the list of valid attributes, or when checksIfValid() returns false.

Parameters:

attribute - The name of the attribute.

Returns:

true if the attribute is valid for the given element, false otherwise.

Throws:

InvalidXMLNameException - The attribute name is invalid.

checksIfValid

public final boolean checksIfValid()

Returns a flag that indicates whether an extended validity check is performed on attributes before adding them.

Returns:

true if extended validation are performed, false if attribute can be added.

See Also:

• setAttribute(String, CharSequence, Optional)

getAttribute

public final Optional<String> getAttribute(String name)

Returns the value for the attribute with the given name.

Parameters:

name - The attribute name.

Returns:

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

getAttributes

public final Map<String,String> getAttributes()

Provides read access to the attributes.

Returns:

A reference to the attributes.

getSortOrder

public final Comparator<String> getSortOrder()

Returns the attribute sort order.

Returns:

The comparator that determines the attribute's sequence.

registerAttributes

public final void registerAttributes(String... attributes)

Registers the valid attributes for the owning element.

Nothing happens if 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.

registerSequence

public final void registerSequence(String... attributes)

Registers an attribute sequence for the owning 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.

retrieveValidAttributes

public final Collection<String> retrieveValidAttributes()

Returns the list of the registered attributes.

Returns:

The registered attributes.

setAttribute

public final Optional<String> 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().

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:

An instance of Optional that holds the former value of the attribute; will be Optional.empty() if the element did not have an attribute with the given name before.

Throws:

IllegalArgumentException - The attribute name is invalid or the attribute is not valid for the element that owns this instance of AttributeSupport.

setSortOrder

public final void setSortOrder(Comparator<String> sortOrder)

Sets the comparator that determines the sequence of the attributes for the owning element.

Parameters:

sortOrder - The comparator.

toString

public final String toString(int indentationLevel,
 boolean prettyPrint)

Returns the attributes and their values, together with the namespaces, as a single formatted string.

Overrides:

toString in class NamespaceSupport

Parameters:

indentationLevel - The indentation level.

prettyPrint - The pretty print flag.

Returns:

The attributes string.