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

Class ChildSupport

java.lang.Object
org.tquadrat.foundation.xml.builder.spi.ChildSupport
@ClassVersion(sourceVersion="$Id: ChildSupport.java 1071 2023-09-30 01:49:32Z tquadrat $") @API(status=MAINTAINED, since="0.0.5") public final class ChildSupport extends Object
This class provides the support for child elements and text to elements. As comments are also considered to be child elements, an element must have an instance of ChildSupport when it should take comments. If only comments should be allowed, the instance can be instantiated with ChildSupport( parent, false, false, false, null );.
The flag checkValid that applies to the constructors ChildSupport(Element,boolean) and ChildSupport(Element,boolean,boolean,boolean,Function) affects only child elements that are added through addChild(Element).
Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: ChildSupport.java 1071 2023-09-30 01:49:32Z tquadrat $
Since:
0.0.5
UML Diagram
UML Diagram for "org.tquadrat.foundation.xml.builder.spi.ChildSupport"⁠

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

UML Diagram for "org.tquadrat.foundation.xml.builder.spi.ChildSupport"⁠

  • Field Details

    • MSG_NoChildrenAllowed

      private static final String MSG_NoChildrenAllowed
      The message indicating that no children are allowed: "No children allowed for element \'%1$s\'".
      See Also:

    • m_AllowChildren

      private final boolean m_AllowChildren
      Flag that indicates whether child elements other than text are allowed.

    • m_AllowText

      private final boolean m_AllowText
      Flag that indicates whether text is allowed.

    • m_CheckValid

      private final boolean m_CheckValid
      Flag that indicates whether the validity of children should be checked.

    • m_Children

      private final List<Element> m_Children
      The list with the element's children.

    • m_EscapeFunction

      private final Function<CharSequence,String> m_EscapeFunction
      The escape function that is used for text elements.

    • m_Owner

      private final Element m_Owner
      The element that owns this ChildSupport instance.

    • m_ValidChildren

      private final Collection<String> m_ValidChildren
      The element names of valid children for a given element; the key for this map is the element name for the parent element.

  • Constructor Details

    • ChildSupport

      public ChildSupport(Element owner)
      Creates a new ChildSupport instance for comments only.
      Parameters:
      owner - The element that owns this ChildSupport instance.

    • ChildSupport

      public ChildSupport(Element owner, Function<CharSequence,String> escapeFunction)
      Creates a new ChildSupport instance that allows text, but no child elements.
      Parameters:
      owner - The element that owns this ChildSupport instance.
      escapeFunction - The escape function that is used to convert special characters in texts; only required when allowText is true.

    • ChildSupport

      public ChildSupport(Element owner, boolean checkValid)
      Creates a new ChildSupport instance that allows child elements, but no text.
      Parameters:
      owner - The element that owns this ChildSupport instance.
      checkValid - true whether children are checked to be allowed before they are added.

    • ChildSupport

      public ChildSupport(Element owner, boolean checkValid, boolean allowChildren, boolean allowText, Function<CharSequence,String> escapeFunction)
      Creates a new ChildSupport instance.
      Parameters:
      owner - The element that owns this ChildSupport instance.
      checkValid - true whether children are checked to be allowed before they are added.
      allowChildren - true if other elements could be added as children, false otherwise.
      allowText - true it text could be added to the element, false if not.
      escapeFunction - The escape function that is used to convert special characters in texts; only required when allowText is true.

  • Method Details

    • addCDATA

      public final void addCDATA(CharSequence text) throws IllegalOperationException
      Adds a CDATA element. As CDATA is basically text, this is controlled by the same flag as text, too.
      Parameters:
      text - The text for the CDATA sequence.
      Throws:
      IllegalOperationException - No text is allowed for the owner.

    • addChild

      public final <E extends Element> void addChild(E child) throws IllegalArgumentException, IllegalStateException, IllegalOperationException
      Adds a child.
      Type Parameters:
      E - The implementation type for the child.
      Parameters:
      child - The child to add.
      Throws:
      IllegalArgumentException - The child is not allowed for the owner of this instance of ChildSupport.
      IllegalStateException - The child has already a parent that is not the owner of this instance of ChildSupport.
      IllegalOperationException - No children allowed for this element.

    • addChildElement

      private final <E extends Element> void addChildElement(String operationName, E child) throws IllegalArgumentException, IllegalStateException, IllegalOperationException
      Adds a child element.
      Type Parameters:
      E - The implementation type for the child.
      Parameters:
      operationName - The name of the operation that was originally called.
      child - The child to add.
      Throws:
      IllegalArgumentException - The child is not allowed for the owner of this instance of ChildSupport.
      IllegalStateException - The child has already a parent that is not the owner of this instance of ChildSupport.
      IllegalOperationException - No children allowed for this element.

    • addComment

      public final void addComment(CharSequence comment)
      Adds a comment.
      Parameters:
      comment - The comment text.

    • addPredefinedMarkup

      public final void addPredefinedMarkup(CharSequence markup) throws IllegalArgumentException, IllegalOperationException

      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.

      Parameters:
      markup - The predefined markup.
      Throws:
      IllegalArgumentException - The child is not allowed for the owner of this instance of ChildSupport.
      IllegalOperationException - No children allowed for this element.

    • addText

      public final void addText(CharSequence text) throws IllegalArgumentException
      Adds text. Special characters will be escaped by the escape function given with the constructor.
      Parameters:
      text - The text.
      Throws:
      IllegalArgumentException - No text is allowed for the owner.

    • addText

      private final void addText(CharSequence text, Function<? super CharSequence,String> escapeFunction, boolean addEmpty) throws IllegalOperationException
      Adds text.
      Parameters:
      text - The text.
      escapeFunction - The function the escapes the text in compliance with the type.
      addEmpty - If true a new Text instance will be added even when the given text is empty, false means that empty text will be omitted.
      Throws:
      IllegalOperationException - No text is allowed for the owner.

    • allowsChildren

      public final boolean allowsChildren()
      Returns the flag that indicates whether this instance of ChildSupport allows other elements to be added as children.
      Returns:
      true when child elements are allowed, false if not.

    • allowsText

      public final boolean allowsText()
      Returns the flag that indicates whether this instance of ChildSupport allows that text and CDATA elements can be added.
      Returns:
      true if it is allowed to add text and CDATA, false otherwise.

    • checkValid

      private final void checkValid(Element child, String operationName) throws IllegalArgumentException, IllegalOperationException

      Checks whether a child is valid for the element that owns this ChildSupport instance.

      The child is valid either when checkValid is false, the child is a Comment or Text, m_ValidChildren does not contain an entry for the owner's element name, or the child's element name is explicitly configured. Obviously, it is not valid, when no children (other then text or comments) are allowed at all.

      Parameters:
      child - The child to check for.
      operationName - The name of the attempted operation.
      Throws:
      IllegalArgumentException - The child is not allowed for the owner.
      IllegalOperationException - No children allowed for the owner.

    • checksIfValid

      public final boolean checksIfValid()
      Returns a flag that indicates whether an extended validity check is performed on child elements before adding them.
      Returns:
      true if extended validation are performed, false if any instance of Element can be added. Also false if no children are allowed at all.
      See Also:

    • getChildren

      public final Collection<? extends Element> getChildren()
      Provides access to the children for this element; the returned collection is not modifiable.
      Returns:
      A reference the children of this element; if the element does not have children, an empty collection will be returned.

    • hasChildren

      public final boolean hasChildren()
      Returns true if the element has children, false otherwise.
      Returns:
      true if the element has children.

    • registerChildren

      public final void registerChildren(String... children)
      Registers the element names of valid child elements for the owning element.
      Note:
      • The given children will be added to the already existing ones!
      Parameters:
      children - The element names of the valid children.

    • retrieveValidChildren

      public final Collection<String> retrieveValidChildren()
      Returns the list of the registered children.
      Returns:
      The registered children.

    • toCDATA

      private static final String toCDATA(CharSequence text)
      "Escapes" the given String to a CDATA sequence.
      Parameters:
      text - The text.
      Returns:
      The CDATA sequence.

    • toString

      public final String toString(int indentationLevel, boolean prettyPrint)
      Returns the children as a single formatted string.
      Parameters:
      indentationLevel - The indentation level.
      prettyPrint - The pretty print flag.
      Returns:
      The children string.