Package space.arim.dazzleconf.backend

Class DataTree

java.lang.Object
space.arim.dazzleconf.backend.DataTree
Direct Known Subclasses:
DataTree.Immut, DataTree.Mut
public abstract class DataTree extends Object
A tree of in-memory configuration data. This tree is essentially a map of keys to values representing in-memory configuration data, with added metadata of line numbers and comments.

Interfacing and order

A data tree is read from and written to configuration backend. As such, it uses the keys found in the backend data, and it does NOT take into account method names or KeyMapper. It is highly recommend to use KeyMapper where appropriate to interface with key strings.

Additionally, a data tree maintains an order which is reflected in iteration operations. If created immutably, this order is fixed at creation. If built mutably, the order will be the insertion order of the elements. Note that re-inserting an existing key will not change the order.

Keys and values

Values are wrapped by DataEntry and must be one of the canonical types. Keys are represented as Object and must be one of the canonical types, excluding lists or trees.

Canonical types:

  • String
  • primitives represented by their boxed types
  • DataTree or DataList for nesting
Keys cannot be DataTree or List. These requirements are enforced at runtime, and they can be checked using validateKey(Object) and DataEntry.validateValue(Object).

Mutability

Mutability of this class is not defined. Please use DataTree.Mut or DataTree.Immut if you need mutable or immutable versions, or see the package javadoc for more information on the mutability model we use.

Equality

A data tree is equal to another if they have the same keys, and the entry at each key is equal. Order and mutability are not considered.

Note that keys may not be equal if reloading data from a backend, depending on whether that backend converts all keys to strings (e.g. "1" instead of 1). Additionally, note that DataEntry does not consider metadata, like comments or line number, in its equality contract.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    DataTree.Immut
    A data tree which is immutable.
    static final class 
    DataTree.Mut
    A data tree which can be modified.

  • Method Summary

    Modifier and Type
    Method
    Description
    final boolean
    equals(Object o)
     
    abstract void
    forEach(BiConsumer<? super @NonNull Object,? super @NonNull DataEntry> action)
    Runs an action for each key/value pair.
    abstract @Nullable DataEntry
    get(@NonNull Object key)
    Gets the entry at the specified key, or null if unset.
    final int
    hashCode()
     
    abstract @NonNull DataTree.Immut
    intoImmut()
    Gets this data tree as an immutable one.
    abstract @NonNull DataTree.Mut
    intoMut()
    Gets this data tree as a mutable one.
    boolean
    isEmpty()
    Whether this data tree is devoid of key/value pairs
    @NonNull Set<@NonNull Object>
    keySet()
    Gets all the keys in this data tree.
    int
    size()
    The number of key/value pairs in this data tree indicates its size
    final String
    toString()
     
    static boolean
    validateKey(@Nullable Object value)
    Checks whether the given object is valid as a key in the data tree.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • isEmpty

      @Pure public boolean isEmpty()
      Whether this data tree is devoid of key/value pairs
      Returns:
      true if empty

    • size

      @Pure public int size()
      The number of key/value pairs in this data tree indicates its size
      Returns:
      the size of this data tree

    • keySet

      @SideEffectFree public @NonNull Set<@NonNull Object> keySet()
      Gets all the keys in this data tree.
      Returns:
      the key set, which may be immutable

    • get

      @Pure public abstract @Nullable DataEntry get(@NonNull Object key)
      Gets the entry at the specified key, or null if unset.

      If accessing keys based on method names, it is strongly recommended to use the KeyMapper to map method names to keys. The key mapper is available during both deserialization and serialization.

      Parameters:
      key - the key
      Returns:
      the entry

    • forEach

      @SideEffectFree public abstract void forEach(BiConsumer<? super @NonNull Object,? super @NonNull DataEntry> action)
      Runs an action for each key/value pair.

      Iteration maintains the order with which this data tree was created.

      Parameters:
      action - the action

    • intoImmut

      @SideEffectFree public abstract @NonNull DataTree.Immut intoImmut()
      Gets this data tree as an immutable one.

      The data contained within this DataTree is moved to an immutable instance. The old instance may still be used, but the implementation of this method may be optimized for the case that it is not.

      If this instance is already DataTree.Immut, then it may be returned without changes.

      Returns:
      an immutable data tree

    • intoMut

      @SideEffectFree public abstract @NonNull DataTree.Mut intoMut()
      Gets this data tree as a mutable one.

      If not mutable, the data is copied to a new tree, which will be made deeply mutable. That is, this function will also be called on any DataTrees encountered in this tree's entries, and DataList.intoMut() on any data lists likewise.

      If this instance is already DataTree.Mut, then it may be returned without changes.

      Returns:
      this tree if mutable, or a mutable copy if needed

    • validateKey

      public static boolean validateKey(@Nullable Object value)
      Checks whether the given object is valid as a key in the data tree. Keys must be either primitive or String. Null values are not accepted as keys.
      Parameters:
      value - the value
      Returns:
      true if a valid canonical key, false if not

    • equals

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

    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public final String toString()
      Overrides:
      toString in class Object