Module net.luis.utils
Package net.luis.utils.io.data.xml

Class XmlElements

java.lang.Object
net.luis.utils.io.data.xml.XmlElements
public class XmlElements extends Object
Represents a collection of xml elements.
The class provides methods to query, add, remove, and get elements.

The collection can be either an object or an array.
If the collection has exactly one element, it's undefined whether it's an object or an array.
In this case, the next element which is added will determine the type of the collection.

In the case this is an object collection, the keys of the elements must be unique.
If an element with a key that already exists is added, an exception will be thrown.

In the case this is an array collection, the keys of the elements must be the same.
If an element with a key that is different from the existing elements is added, an exception will be thrown.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final SequencedMap<String,List<XmlElement>>
    elements
    The elements of the collection.

  • Constructor Summary

    Constructors
    Constructor
    Description
    XmlElements()
    Constructs a new, empty xml elements collection.
    XmlElements(@NotNull List<? extends XmlElement> elements)
    Constructs a new xml elements collection with the given elements.
    This constructor will determine the type of the collection based on the elements.
    XmlElements(@NotNull Map<String,? extends XmlElement> elements)
    Constructs a new xml elements collection with the given elements.
    This constructor will determine the type of the collection based on the elements.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(@NotNull XmlElement element)
    Adds the given element to the collection.
    void
    addContainer(@NotNull XmlContainer container)
    Adds the given container to the collection.
    void
    addValue(@NotNull XmlValue value)
    Adds the given value to the collection.
    void
    clear()
    Removes all elements from the collection.
    boolean
    containsElement(@Nullable XmlElement element)
    Checks if this collection contains the given element considering the type.
    boolean
    containsName(@Nullable String name)
    Checks if this collection contains an element with the given name.
    @NotNull @Unmodifiable Collection<XmlElement>
    elements()
    Returns an unmodifiable collection of all elements in the collection considering the type.
    boolean
    equals(Object o)
     
    @Nullable XmlElement
    get(int index)
    Returns the element with the given index from the collection.
    This method should only be used if the collection is an array.
    @Nullable XmlElement
    get(@Nullable String name)
    Returns the element with the given name from the collection.
    This method should only be used if the collection is an object.
    @NotNull @Unmodifiable List<XmlElement>
    getAsArray()
    Returns the elements of the collection as an unmodifiable list.
    This method should only be used if the collection is an array.
    @NotNull XmlContainer
    getAsContainer(int index)
    Returns the element with the given index from the collection as a container.
    This method should only be used if the collection is an array.
    @NotNull XmlContainer
    getAsContainer(@Nullable String name)
    Returns the element with the given name from the collection as a container.
    This method should only be used if the collection is an object.
    @NotNull @Unmodifiable Map<String,XmlElement>
    getAsObject()
    Returns the elements of the collection as an unmodifiable map.
    This method should only be used if the collection is an object.
    @NotNull XmlValue
    getAsValue(int index)
    Returns the element with the given index from the collection as a value.
    This method should only be used if the collection is an array.
    @NotNull XmlValue
    getAsValue(@Nullable String name)
    Returns the element with the given name from the collection as a value.
    This method should only be used if the collection is an object.
    int
    hashCode()
     
    boolean
    isArray()
    Checks whether the collection is an array.
    An array is a collection with exactly one key and multiple elements.
    boolean
    isEmpty()
    Checks if this collection contains no elements.
    boolean
    isObject()
    Checks whether the collection is an object.
    An object is a collection with multiple keys.
    Each key has exactly one element.
    boolean
    isUndefined()
    Checks whether the collection is undefined.
    @NotNull @Unmodifiable Set<String>
    nameSet()
    Returns an unmodifiable set of all element names in the collection.
    boolean
    remove(int index)
    Removes the element with the given index from the collection.
    This method should only be used if the collection is an array.
    boolean
    remove(@Nullable String name)
    Removes the element with the given name from the collection.
    This method should only be used if the collection is an object.
    boolean
    remove(@NotNull XmlElement element)
    Removes the given element from the collection considering the type.
    int
    size()
    Returns the number of elements in the collection considering the type.
    String
    toString()
     
    @NotNull String
    toString(@NotNull XmlConfig config)
    Returns a string representation of the collection using the given xml config.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

  • Constructor Details

    • XmlElements

      public XmlElements()
      Constructs a new, empty xml elements collection.

    • XmlElements

      public XmlElements(@NotNull @NotNull List<? extends XmlElement> elements)
      Constructs a new xml elements collection with the given elements.
      This constructor will determine the type of the collection based on the elements.
      Parameters:
      elements - The elements to add to the collection
      Throws:
      NullPointerException - If the elements are null
      XmlTypeException - If the elements are not valid for the collection type

    • XmlElements

      public XmlElements(@NotNull @NotNull Map<String,? extends XmlElement> elements)
      Constructs a new xml elements collection with the given elements.
      This constructor will determine the type of the collection based on the elements.
      Parameters:
      elements - The elements to add to the collection
      Throws:
      NullPointerException - If the elements are null
      XmlTypeException - If the elements are not valid for the collection type

  • Method Details

    • isUndefined

      public boolean isUndefined()
      Checks whether the collection is undefined.
      Returns:
      True if the collection is neither an object nor an array, false otherwise

    • isArray

      public boolean isArray()
      Checks whether the collection is an array.
      An array is a collection with exactly one key and multiple elements.
      Returns:
      True if the collection is an array, false otherwise

    • isObject

      public boolean isObject()
      Checks whether the collection is an object.
      An object is a collection with multiple keys.
      Each key has exactly one element.
      Returns:
      True if the collection is an object, false otherwise

    • size

      public int size()
      Returns the number of elements in the collection considering the type.
      Returns:
      The size of the collection

    • isEmpty

      public boolean isEmpty()
      Checks if this collection contains no elements.
      Returns:
      True if the collection is empty, false otherwise

    • containsName

      public boolean containsName(@Nullable @Nullable String name)
      Checks if this collection contains an element with the given name.
      Parameters:
      name - The name of the element to check for
      Returns:
      True if the collection contains an element with the given name, false otherwise

    • containsElement

      public boolean containsElement(@Nullable @Nullable XmlElement element)
      Checks if this collection contains the given element considering the type.
      Parameters:
      element - The element to check for
      Returns:
      True if the collection contains the given element, false otherwise

    • nameSet

      @NotNull public @NotNull @Unmodifiable Set<String> nameSet()
      Returns an unmodifiable set of all element names in the collection.
      Returns:
      The set of element names

    • elements

      @NotNull public @NotNull @Unmodifiable Collection<XmlElement> elements()
      Returns an unmodifiable collection of all elements in the collection considering the type.
      Returns:
      The collection of elements

    • add

      public void add(@NotNull @NotNull XmlElement element)
      Adds the given element to the collection.
      Parameters:
      element - The element to add
      Throws:
      NullPointerException - If the element is null
      XmlTypeException - If the element is not valid for the collection type

    • addContainer

      public void addContainer(@NotNull @NotNull XmlContainer container)
      Adds the given container to the collection.
      Parameters:
      container - The container to add
      Throws:
      NullPointerException - If the container is null
      XmlTypeException - If the container is not valid for the collection type

    • addValue

      public void addValue(@NotNull @NotNull XmlValue value)
      Adds the given value to the collection.
      Parameters:
      value - The value to add
      Throws:
      NullPointerException - If the value is null
      XmlTypeException - If the value is not valid for the collection type

    • remove

      public boolean remove(@NotNull @NotNull XmlElement element)
      Removes the given element from the collection considering the type.
      Parameters:
      element - The element to remove
      Returns:
      True if the element was removed, false otherwise
      Throws:
      NullPointerException - If the element is null

    • remove

      public boolean remove(@Nullable @Nullable String name)
      Removes the element with the given name from the collection.
      This method should only be used if the collection is an object.
      Parameters:
      name - The name of the element to remove
      Returns:
      True if an element was removed, false otherwise
      Throws:
      XmlTypeException - If the collection is an array

    • remove

      public boolean remove(int index)
      Removes the element with the given index from the collection.
      This method should only be used if the collection is an array.
      Parameters:
      index - The index of the element to remove
      Returns:
      True if an element was removed, false otherwise
      Throws:
      XmlTypeException - If the collection is an object

    • clear

      public void clear()
      Removes all elements from the collection.

    • get

      @Nullable public @Nullable XmlElement get(@Nullable @Nullable String name)
      Returns the element with the given name from the collection.
      This method should only be used if the collection is an object.
      Parameters:
      name - The name of the element to get
      Returns:
      The element with the given name or null if no element with the name exists
      Throws:
      XmlTypeException - If the collection is an array
      See Also:

    • getAsContainer

      @NotNull public @NotNull XmlContainer getAsContainer(@Nullable @Nullable String name)
      Returns the element with the given name from the collection as a container.
      This method should only be used if the collection is an object.
      Parameters:
      name - The name of the element to get
      Returns:
      The element with the given name as a container
      Throws:
      XmlTypeException - If the collection is an array or the element is not a container
      NoSuchXmlElementException - If no element with the given name exists
      See Also:

    • getAsValue

      @NotNull public @NotNull XmlValue getAsValue(@Nullable @Nullable String name)
      Returns the element with the given name from the collection as a value.
      This method should only be used if the collection is an object.
      Parameters:
      name - The name of the element to get
      Returns:
      The element with the given name as a value
      Throws:
      XmlTypeException - If the collection is an array or the element is not a value
      NoSuchXmlElementException - If no element with the given name exists
      See Also:

    • get

      @Nullable public @Nullable XmlElement get(int index)
      Returns the element with the given index from the collection.
      This method should only be used if the collection is an array.
      Parameters:
      index - The index of the element to get
      Returns:
      The element with the given index or null if no element with the index exists
      Throws:
      XmlTypeException - If the collection is an object

    • getAsContainer

      @NotNull public @NotNull XmlContainer getAsContainer(int index)
      Returns the element with the given index from the collection as a container.
      This method should only be used if the collection is an array.
      Parameters:
      index - The index of the element to get
      Returns:
      The element with the given index as a container
      Throws:
      XmlTypeException - If the collection is an object
      NoSuchXmlElementException - If no element with the given index exists
      See Also:

    • getAsValue

      @NotNull public @NotNull XmlValue getAsValue(int index)
      Returns the element with the given index from the collection as a value.
      This method should only be used if the collection is an array.
      Parameters:
      index - The index of the element to get
      Returns:
      The element with the given index as a value
      Throws:
      XmlTypeException - If the collection is an object
      NoSuchXmlElementException - If no element with the given index exists
      See Also:

    • getAsArray

      @NotNull public @NotNull @Unmodifiable List<XmlElement> getAsArray()
      Returns the elements of the collection as an unmodifiable list.
      This method should only be used if the collection is an array.
      Returns:
      The elements of the collection
      Throws:
      XmlTypeException - If the collection is an object

    • getAsObject

      @NotNull public @NotNull @Unmodifiable Map<String,XmlElement> getAsObject()
      Returns the elements of the collection as an unmodifiable map.
      This method should only be used if the collection is an object.
      Returns:
      The elements of the collection
      Throws:
      XmlTypeException - If the collection is an array

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toString

      @NotNull public @NotNull String toString(@NotNull @NotNull XmlConfig config)
      Returns a string representation of the collection using the given xml config.
      Parameters:
      config - The xml config to use
      Returns:
      The string representation of the collection
      Throws:
      NullPointerException - If the xml config is null