io.github.fablabsmc.fablabs.api.fiber.v1.builder

Class ConfigTreeBuilder

java.lang.Object

io.github.fablabsmc.fablabs.impl.fiber.builder.ConfigNodeBuilder

io.github.fablabsmc.fablabs.api.fiber.v1.builder.ConfigTreeBuilder

All Implemented Interfaces:

ConfigTree

public class ConfigTreeBuilder
extends ConfigNodeBuilder
implements ConfigTree

A builder for configuration trees/branches.

Usage example:

 ConfigBranch config = ConfigTree.builder()
         .withValue("A", ConfigTypes.INTEGER, 10)
         .fork("child")
             .beginValue("drops", ConfigTypes.makeSet(ConfigTypes.STRING)), new HashSet<>(Arrays.asList("diamond", "cactus"))
             .withComment("List of things to drop")
             .finishValue()
         .finishNode()
         .build();
 

See Also:

ConfigTree.builder(), PropertyMirror

Field Summary

Fields inherited from class io.github.fablabsmc.fablabs.impl.fiber.builder.ConfigNodeBuilder

attributes, parent

Constructor Summary

Constructors

Constructor and Description
ConfigTreeBuilder(ConfigTree parent, String name) Creates a new builder with initial settings.

Method Summary

Modifier and Type	Method and Description
ConfigTreeBuilder	applyFromPojo(Object pojo) Configure this builder using a POJO (Plain Old Java Object).
ConfigTreeBuilder	applyFromPojo(Object pojo, AnnotatedSettings settings) Configure this builder using a POJO (Plain Old Java Object).
<T,R> ConfigLeafBuilder<T,R>	beginValue(String name, ConfigType<R,T,?> type, R defaultValue)
<T> ConfigLeafBuilder<T,T>	beginValue(String name, SerializableType<T> type, T defaultValue) Creates a scalar ConfigLeafBuilder with the given default value.
ConfigBranch	build() Construct a new ConfigNode based on this builder's specifications.
ConfigTreeBuilder	finishBranch() Builds and registers the ConfigNode with the parent node.
ConfigTreeBuilder	finishBranch(Consumer<ConfigBranch> action) Builds and registers the ConfigNode with the parent node before running the given action on the newly built node.
ConfigTreeBuilder	fork(String name) Forks this builder, creating a subtree whose parent is this node.
NodeCollection	getItems() Returns a collection of this builder's children.
ConfigNode	lookup(String name) Tries to find a child in this builder by name.
boolean	lookupAndBind(String name, PropertyMirror<?> mirror) Tries to find a child leaf in this node by name.
ConfigBranch	lookupBranch(String name) Tries to find a child branch in this node by name.
<T> ConfigLeaf<T>	lookupLeaf(String name, SerializableType<T> type) Tries to find a child leaf in this node by name.
ConfigTreeBuilder	withAttribute(ConfigAttribute<?> attribute) Adds a single ConfigAttribute to the built ConfigNode.
<A> ConfigTreeBuilder	withAttribute(FiberId id, SerializableType<A> type, A defaultValue) Adds a ConfigAttribute to the built ConfigBranch.
ConfigTreeBuilder	withAttributes(Collection<ConfigAttribute<?>> attributes) Adds a collection of ConfigAttribute to the built ConfigNode.
ConfigTreeBuilder	withChild(ConfigNode item) Attempts to introduce a new child to this builder.
ConfigTreeBuilder	withChild(ConfigNode item, boolean overwrite) Attempts to introduce a new child to this builder.
ConfigTreeBuilder	withComment(String comment) Sets the ConfigBranch's comment.
<R> ConfigTreeBuilder	withMirroredValue(String name, PropertyMirror<R> mirror, R defaultValue) Adds a ConfigLeaf bound to a PropertyMirror, using the mirror's type information.
ConfigTreeBuilder	withName(String name) Sets the ConfigBranch's name.
ConfigTreeBuilder	withParent(ConfigTreeBuilder parent) Sets the parent builder for this builder.
ConfigTreeBuilder	withSeparateSerialization() Marks the built subtree as being serialized separately.
ConfigTreeBuilder	withSeparateSerialization(boolean serializeSeparately) Sets whether a subtree should be serialized separately.
<R,S> ConfigTreeBuilder	withValue(String name, ConfigType<R,S,?> type, R defaultValue) Adds a ConfigLeaf with a type and default value derived from another type.
<T> ConfigTreeBuilder	withValue(String name, SerializableType<T> type, T defaultValue) Adds a ConfigLeaf with the given type and default value to the tree.

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.github.fablabsmc.fablabs.api.fiber.v1.tree.ConfigTree

builder, builder

Constructor Detail

ConfigTreeBuilder

public ConfigTreeBuilder(@Nullable
                         ConfigTree parent,
                         @Nullable
                         String name)

Creates a new builder with initial settings.

Parameters:

parent - the initial parent

name - the initial name

See Also:

ConfigTree.builder(), ConfigTree.builder(ConfigTree, String)

Method Detail

getItems

@Nonnull
public NodeCollection getItems()

Returns a collection of this builder's children.

The returned collection is guaranteed to have no two nodes with the same name. Elements may be freely added and removed from it.

Specified by:

getItems in interface ConfigTree

Returns:

the set of children

See Also:

NodeCollection.add(ConfigNode, boolean), NodeCollection.removeByName(String)

lookup

@Nullable
public ConfigNode lookup(String name)

Tries to find a child in this builder by name. If a child is found, it will be returned.

Specified by:

lookup in interface ConfigTree

Parameters:

name - The name of the child to look for

Returns:

the child if found, otherwise null

lookupBranch

@Nullable
public ConfigBranch lookupBranch(String name)

Tries to find a child branch in this node by name. If a child is found, and it is a branch node, it is returned.

Specified by:

lookupBranch in interface ConfigTree

Parameters:

name - The name of the child to look for.

Returns:

The child branch if found, otherwise null.

lookupLeaf

@Nullable
public <T> ConfigLeaf<T> lookupLeaf(String name,
                                              SerializableType<T> type)

Tries to find a child leaf in this node by name. If a child with the right type is found, it will be returned.

Specified by:

lookupLeaf in interface ConfigTree

Type Parameters:

T - the type of values held by the leaf

Parameters:

name - the name of the leaf to look for

type - a SerializableType object representing the type of values held by the leaf

Returns:

the leaf if found, otherwise null

lookupAndBind

public boolean lookupAndBind(String name,
                             PropertyMirror<?> mirror)

Tries to find a child leaf in this node by name. If a child with the right type is found, the mirror will be bound to it.

Specified by:

lookupAndBind in interface ConfigTree

Parameters:

name - the name of the leaf to mirror

mirror - the mirror to bind to the leaf

Returns:

true if the operation succeeded

withParent

public ConfigTreeBuilder withParent(ConfigTreeBuilder parent)

Sets the parent builder for this builder. This builder must represent a named node.

Parameters:

parent - The parent builder.

Returns:

This builder.

Throws:

IllegalStateException - If no name has been set in this builder.

withName

public ConfigTreeBuilder withName(String name)

Sets the ConfigBranch's name.

Overrides:

withName in class ConfigNodeBuilder

Parameters:

name - the name

Returns:

this builder

See Also:

ConfigTree.lookupLeaf(java.lang.String, io.github.fablabsmc.fablabs.api.fiber.v1.schema.type.SerializableType<T>)

withComment

public ConfigTreeBuilder withComment(@Nullable
                                     String comment)

Sets the ConfigBranch's comment.

If null, or if this method is never called, the ConfigLeaf won't have a comment. An empty comment (non null, but only consisting of whitespace) will be serialised.

Overrides:

withComment in class ConfigNodeBuilder

Parameters:

comment - the comment

Returns:

this builder

withAttribute

public <A> ConfigTreeBuilder withAttribute(FiberId id,
                                           SerializableType<A> type,
                                           A defaultValue)

Adds a ConfigAttribute to the built ConfigBranch.

Overrides:

withAttribute in class ConfigNodeBuilder

Type Parameters:

A - the type of values stored in the attribute

Parameters:

id - the id of the attribute

type - the class object representing the type of values stored in the attribute

defaultValue - the attribute's default value

Returns:

this, for chaining

See Also:

ConfigNode.getAttributes()

withAttributes

public ConfigTreeBuilder withAttributes(Collection<ConfigAttribute<?>> attributes)

Adds a collection of ConfigAttribute to the built ConfigNode.

Overrides:

withAttributes in class ConfigNodeBuilder

Parameters:

attributes - A collection of attributes.

Returns:

This builder.

withAttribute

public ConfigTreeBuilder withAttribute(ConfigAttribute<?> attribute)

Adds a single ConfigAttribute to the built ConfigNode.

Overrides:

withAttribute in class ConfigNodeBuilder

Parameters:

attribute - The attribute.

Returns:

This builder.

withSeparateSerialization

public ConfigTreeBuilder withSeparateSerialization()

Marks the built subtree as being serialized separately.

A subtree marked for separate serialization will not appear in the serialized representation of its ancestors. This property can be useful when partitioning a big configuration tree into several files.

This method has no effect if the built node is a tree root.

Returns:

this, for chaining

See Also:

withSeparateSerialization(), ConfigBranch.isSerializedSeparately()

withSeparateSerialization

public ConfigTreeBuilder withSeparateSerialization(boolean serializeSeparately)

Sets whether a subtree should be serialized separately.

If serializeSeparately is true, the subtree created from this builder will not appear in the serialized representation of the ancestor. This property can be especially useful when partitioning a big configuration tree into several files.

This method has no effect if the built node is a tree root.

Parameters:

serializeSeparately - true if the built tree should be serialized separately

Returns:

this, for chaining

applyFromPojo

public ConfigTreeBuilder applyFromPojo(Object pojo)
                                throws RuntimeFiberException

Configure this builder using a POJO (Plain Old Java Object).

The tree structure will be based on the pojo's fields, recursively generating settings. The generated settings can be configured in the pojo's class declaration, using annotations such as Setting.

The generated ConfigLeafs will be bound to their respective fields, setting the latter when the former's value is updated.

If a FiberException is thrown when using the underlying AnnotatedSettings, it is wrapped in a RuntimeFiberException.

Parameters:

pojo - an object serving as a base to reflectively generate a config tree

Returns:

this, for chaining

Throws:

RuntimeFiberException

See Also:

Setting, Settings, AnnotatedSettings.applyToNode(ConfigTree, Object), applyFromPojo(Object, AnnotatedSettings)

applyFromPojo

public ConfigTreeBuilder applyFromPojo(Object pojo,
                                       AnnotatedSettings settings)
                                throws RuntimeFiberException

Configure this builder using a POJO (Plain Old Java Object).

The node's structure will be based on the pojo's fields, recursively generating settings. The generated settings can be configured in the pojo's class declaration, using annotations such as Setting.

The generated ConfigLeafs will be bound to their respective fields, setting the latter when the former's value is updated.

If a FiberException is thrown when using the underlying AnnotatedSettings, it is wrapped in a RuntimeFiberException.

Parameters:

pojo - an object serving as a base to reflectively generate a config tree

settings - an AnnotatedSettings instance used to configure this builder

Returns:

this, for chaining

Throws:

RuntimeFiberException

See Also:

@Setting, @Settings, AnnotatedSettings.applyToNode(ConfigTree, Object)

beginValue

public <T> ConfigLeafBuilder<T,T> beginValue(@Nonnull
                                             String name,
                                             @Nonnull
                                             SerializableType<T> type,
                                             @Nonnull
                                             T defaultValue)

Creates a scalar ConfigLeafBuilder with the given default value.

Type Parameters:

T - the type type represents

Parameters:

type - the class of the type of value the ConfigLeaf produced by the builder holds

Returns:

the newly created builder

See Also:

withValue(String, SerializableType, Object), ConfigLeafBuilder, ConfigTypes

beginValue

public <T,R> ConfigLeafBuilder<T,R> beginValue(@Nonnull
                                               String name,
                                               @Nonnull
                                               ConfigType<R,T,?> type,
                                               @Nonnull
                                               R defaultValue)

withValue

public <T> ConfigTreeBuilder withValue(@Nonnull
                                       String name,
                                       @Nonnull
                                       SerializableType<T> type,
                                       @Nonnull
                                       T defaultValue)

Adds a ConfigLeaf with the given type and default value to the tree.

This method allows only basic configuration of the created leaf. For more flexibility, beginValue(java.lang.String, io.github.fablabsmc.fablabs.api.fiber.v1.schema.type.SerializableType<T>, T) can be used.

Type Parameters:

T - the type of value the ConfigLeaf holds.

Parameters:

name - the name of the child leaf

type - the type of values held by the leaf

defaultValue - the default value of the ConfigLeaf to create.

Returns:

this, for chaining

See Also:

beginValue(String, SerializableType, Object), ConfigTypes

withValue

public <R,S> ConfigTreeBuilder withValue(@Nonnull
                                         String name,
                                         @Nonnull
                                         ConfigType<R,S,?> type,
                                         @Nullable
                                         R defaultValue)

Adds a ConfigLeaf with a type and default value derived from another type.

The built leaf will only accept values of type's serializable config type. The full derived type information is only used to convert the provided defaultValue to a valid serialized form. Property mirrors can be used to interact seamlessly with the leaf using runtime types.

This method allows only basic configuration of the created leaf. For more flexibility, beginValue(java.lang.String, io.github.fablabsmc.fablabs.api.fiber.v1.schema.type.SerializableType<T>, T) can be used.

Type Parameters:

R - the runtime type of the defaultValue representation.

S - the type of value the ConfigLeaf holds.

Parameters:

name - the name of the child leaf

type - the type of values held by the leaf

defaultValue - the runtime representation of the default value of the ConfigLeaf to create.

Returns:

this, for chaining

See Also:

beginValue(String, SerializableType, Object), ConfigTypes

withMirroredValue

public <R> ConfigTreeBuilder withMirroredValue(@Nonnull
                                               String name,
                                               @Nonnull
                                               PropertyMirror<R> mirror,
                                               @Nonnull
                                               R defaultValue)

Adds a ConfigLeaf bound to a PropertyMirror, using the mirror's type information.

This method behaves as if:

 this.beginValue(name, mirror.getMirroredType(), defaultValue).finishValue(mirror::mirror)

The built leaf will only accept values of the mirror's serializable config type. The full derived type information is only used to convert the provided defaultValue to a valid serialized form. The mirror can be used to interact seamlessly with the leaf using runtime types.

This method allows only basic configuration of the created leaf. For more flexibility, beginValue(java.lang.String, io.github.fablabsmc.fablabs.api.fiber.v1.schema.type.SerializableType<T>, T) can be used.

Type Parameters:

R - the runtime type of the defaultValue representation.

Parameters:

name - the name of the child leaf

mirror - a mirror to be bound to the leaf

defaultValue - the runtime representation of the default value of the ConfigLeaf to create.

Returns:

this, for chaining

See Also:

beginValue(String, SerializableType, Object), ConfigTypes

withChild

public ConfigTreeBuilder withChild(@Nonnull
                                   ConfigNode item)
                            throws DuplicateChildException

Attempts to introduce a new child to this builder.

Parameters:

item - The child to add

Returns:

this, for chaining

Throws:

DuplicateChildException - if there was already a child by the same name

See Also:

Property

withChild

public ConfigTreeBuilder withChild(@Nonnull
                                   ConfigNode item,
                                   boolean overwrite)
                            throws DuplicateChildException

Attempts to introduce a new child to this builder.

Parameters:

item - The child to add

overwrite - whether existing items should be overwritten

Returns:

this, for chaining

Throws:

DuplicateChildException - if there was already a child by the same name

fork

public ConfigTreeBuilder fork(String name)

Forks this builder, creating a subtree whose parent is this node.

Parameters:

name - the name of the new Node

Returns:

the created node builder

build

public ConfigBranch build()
                   throws RuntimeFiberException

Construct a new ConfigNode based on this builder's specifications.

Calling this method more than once with the same parameters (specifically same parent and/or children) may result in exceptions being thrown, as the resulting tree structure will be invalid.

Specified by:

build in class ConfigNodeBuilder

Returns:

a new ConfigNode

Throws:

RuntimeFiberException - if building the node results in an invalid tree

finishBranch

public ConfigTreeBuilder finishBranch()

Builds and registers the ConfigNode with the parent node. This method is equivalent to this.finishBranch(branch -> {}).

Returns:

The parent builder.

finishBranch

public ConfigTreeBuilder finishBranch(Consumer<ConfigBranch> action)

Builds and registers the ConfigNode with the parent node before running the given action on the newly built node.

Parameters:

action - An operation to run on the built ConfigBranch.

Returns:

The parent builder.