me.zeroeightsix.fiber.api.builder

Class ConfigTreeBuilder

java.lang.Object

me.zeroeightsix.fiber.impl.builder.ConfigNodeBuilder

me.zeroeightsix.fiber.api.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()
         .beginValue("version", "1.0.0")
             .withFinality()
             .beginConstraints() // checks the default value
                 .regex("\\d+\\.\\d+\\.\\d+")
             .finishConstraints()
         .finishValue()
         .fork("child")
             .beginValue("A", 10)
                 .beginConstraints()
                     .composite(CompositeType.OR)
                         .atLeast(3)
                         .atMost(0)
                     .finishComposite()
                 .finishConstraints()
             .finishValue()
         .finishNode()
         .build();
 

See Also:

ConfigTree.builder(), PropertyMirror

Field Summary

Fields inherited from class me.zeroeightsix.fiber.impl.builder.ConfigNodeBuilder

attributes, parent

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
ConfigTreeBuilder	applyFromPojo(java.lang.Object pojo) Configure this builder using a POJO (Plain Old Java Object).
ConfigTreeBuilder	applyFromPojo(java.lang.Object pojo, AnnotatedSettings settings) Configure this builder using a POJO (Plain Old Java Object).
<C extends java.util.Collection<E>,E> ConfigAggregateBuilder<C,E>	beginAggregateValue(java.lang.String name, java.lang.Class<? super C> collectionType, java.lang.Class<E> elementType, C defaultValue) Creates an aggregate ConfigLeafBuilder.
<E> ConfigAggregateBuilder<E[],E>	beginAggregateValue(java.lang.String name, E[] defaultValue) Creates an aggregate ConfigLeafBuilder.
<E> ConfigAggregateBuilder<java.util.List<E>,E>	beginListValue(java.lang.String name, java.lang.Class<E> elementType, E... defaultValues) Creates a ConfigAggregateBuilder for a List settings with the given default elements.
<E> ConfigAggregateBuilder<java.util.Set<E>,E>	beginSetValue(java.lang.String name, java.lang.Class<E> elementType, E... defaultElements) Creates a ConfigAggregateBuilder for a Set settings with the given default elements.
<T> ConfigLeafBuilder<T>	beginValue(java.lang.String name, java.lang.Class<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()
ConfigTreeBuilder	finishBranch(java.util.function.Consumer<ConfigBranch> action)
ConfigTreeBuilder	fork(java.lang.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(java.lang.String name) Tries to find a child in this builder by name.
<A> ConfigTreeBuilder	withAttribute(FiberId id, java.lang.Class<A> type, A defaultValue) Adds a ConfigAttribute to the built ConfigBranch.
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(java.lang.String comment) Sets the ConfigBranch's comment.
ConfigTreeBuilder	withName(java.lang.String name) Sets the ConfigBranch's name.
ConfigTreeBuilder	withParent(ConfigTreeBuilder parent)
ConfigTreeBuilder	withSeparateSerialization() Marks the built subtree as being serialized separately.
ConfigTreeBuilder	withSeparateSerialization(boolean serializeSeparately) Sets whether a subtree should be serialized separately.
<T> ConfigTreeBuilder	withValue(java.lang.String name, java.lang.Class<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 me.zeroeightsix.fiber.api.tree.ConfigTree

builder, builder

Constructor Detail

ConfigTreeBuilder

public ConfigTreeBuilder(@Nullable
                         ConfigTree parent,
                         @Nullable
                         java.lang.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(java.lang.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

withParent

public ConfigTreeBuilder withParent(ConfigTreeBuilder parent)

withName

public ConfigTreeBuilder withName(java.lang.String name)

Sets the ConfigBranch's name.

Overrides:

withName in class ConfigNodeBuilder

Parameters:

name - the name

Returns:

this builder

See Also:

ConfigTree.lookup(java.lang.String)

withComment

public ConfigTreeBuilder withComment(@Nullable
                                     java.lang.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,
                                           java.lang.Class<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()

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(java.lang.Object pojo)
                                throws FiberException

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.

Parameters:

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

Returns:

this, for chaining

Throws:

FiberException

See Also:

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

applyFromPojo

public ConfigTreeBuilder applyFromPojo(java.lang.Object pojo,
                                       AnnotatedSettings settings)
                                throws FiberException

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.

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:

FiberException

See Also:

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

beginValue

public <T> ConfigLeafBuilder<T> beginValue(@Nonnull
                                           java.lang.String name,
                                           @Nonnull
                                           java.lang.Class<T> type,
                                           @Nullable
                                           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:

ConfigLeafBuilder, withValue(String, Class, Object), beginAggregateValue(String, Object[]), beginAggregateValue(String, Class, Class, Collection), beginListValue(String, Class, Object[]), beginSetValue(String, Class, Object[])

withValue

public <T> ConfigTreeBuilder withValue(@Nonnull
                                       java.lang.String name,
                                       @Nonnull
                                       java.lang.Class<T> type,
                                       @Nullable
                                       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, one of the begin*Value methods 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, Class, Object), beginAggregateValue(String, Object[]), beginAggregateValue(String, Class, Class, Collection), beginListValue(String, Class, Object[]), beginSetValue(String, Class, Object[])

beginAggregateValue

public <E> ConfigAggregateBuilder<E[],E> beginAggregateValue(@Nonnull
                                                             java.lang.String name,
                                                             @Nonnull
                                                             E[] defaultValue)

Creates an aggregate ConfigLeafBuilder.

Type Parameters:

E - the type of elements defaultValue holds

Parameters:

defaultValue - the default array of values the ConfigLeaf will hold.

Returns:

the newly created builder

See Also:

Aggregate

beginListValue

public <E> ConfigAggregateBuilder<java.util.List<E>,E> beginListValue(@Nonnull
                                                                      java.lang.String name,
                                                                      java.lang.Class<E> elementType,
                                                                      E... defaultValues)

Creates a ConfigAggregateBuilder for a List settings with the given default elements.

This method should not be called by intermediary generic methods (eg. <T> void f(ConfigTreeBuilder b, T t) {b.beginListValue("", t);}), as it will prevent type checking while building the tree. Use beginAggregateValue(String, Class, Class, Collection) in those cases instead.

Type Parameters:

E - the type of elements contained by the set

Parameters:

defaultValues - the default values of the

Returns:

the newly created builder

beginSetValue

public <E> ConfigAggregateBuilder<java.util.Set<E>,E> beginSetValue(@Nonnull
                                                                    java.lang.String name,
                                                                    java.lang.Class<E> elementType,
                                                                    E... defaultElements)

Creates a ConfigAggregateBuilder for a Set settings with the given default elements.

Type Parameters:

E - the type of elements contained by the set

Parameters:

defaultElements - the elements contained by default in the set setting

Returns:

the newly created builder

beginAggregateValue

public <C extends java.util.Collection<E>,E> ConfigAggregateBuilder<C,E> beginAggregateValue(@Nonnull
                                                                                             java.lang.String name,
                                                                                             @Nonnull
                                                                                             java.lang.Class<? super C> collectionType,
                                                                                             @Nullable
                                                                                             java.lang.Class<E> elementType,
                                                                                             @Nonnull
                                                                                             C defaultValue)

Creates an aggregate ConfigLeafBuilder.

Type Parameters:

C - the type of collection defaultValue is

E - the type elementType represents

Parameters:

collectionType - the class object representing the type of collection to create a setting for

elementType - the class object representing the type of elements defaultValue holds

defaultValue - the default collection of values the ConfigLeaf will hold.

Returns:

the newly created builder

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(java.lang.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()

finishBranch

public ConfigTreeBuilder finishBranch(java.util.function.Consumer<ConfigBranch> action)