me.zeroeightsix.fiber.api.tree

Class ConfigQuery<T extends ConfigNode>

java.lang.Object

me.zeroeightsix.fiber.api.tree.ConfigQuery<T>

Type Parameters:

T - the type of queried tree nodes

public final class ConfigQuery<T extends ConfigNode>
extends java.lang.Object

A query that can be run against any config tree to try and get a node.

A ConfigQuery follows a path in the tree, represented by a list of strings. It can notably be used to retrieve nodes from various config trees with a similar structure.

Method Summary

Modifier and Type	Method and Description
static ConfigQuery<ConfigBranch>	branch(java.lang.String first, java.lang.String... more) Creates a ConfigQuery for a branch with a specific path.
static <V> ConfigQuery<ConfigLeaf<V>>	leaf(java.lang.Class<? super V> propertyType, java.lang.String first, java.lang.String... more) Creates a ConfigQuery for a property with a specific path and value type.
T	run(ConfigTree cfg) Runs this query on a config tree.
java.util.Optional<T>	search(ConfigTree cfg) Searches a config tree for a node satisfying this query.
java.lang.String	toString() Returns a string representation of this query.

Methods inherited from class java.lang.Object

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

Method Detail

branch

public static ConfigQuery<ConfigBranch> branch(java.lang.String first,
                                               java.lang.String... more)

Creates a ConfigQuery for a branch with a specific path.

Each part of the path must correspond to a single node name. The first part matches a direct child node of the root supplied to the search(ConfigTree) and run(ConfigTree) methods. Each additional name matches a node such that the nth name matches a node at depth n, starting from the supplied tree. The last name should be the name of the branch to retrieve.

Parameters:

first - the first name in the config path

more - additional node names forming the config path

Returns:

a config query for branches of existing trees

leaf

public static <V> ConfigQuery<ConfigLeaf<V>> leaf(java.lang.Class<? super V> propertyType,
                                                  java.lang.String first,
                                                  java.lang.String... more)

Creates a ConfigQuery for a property with a specific path and value type.

Each part of the path must correspond to a single node name. The first part matches a direct child node of the root supplied to the search(ConfigTree) and run(ConfigTree) methods. Each additional name matches a node such that the nth name matches a node at depth n, starting from the supplied tree. The last name should be the name of the leaf to retrieve.

The returned query will only match a leaf with a property type that is identical to the given propertyType.

Parameters:

propertyType - a class object representing the type of values held by queried properties

first - the first name in the config path

more - additional node names forming the config path

Returns:

a config query for leaves of existing trees

search

public java.util.Optional<T> search(ConfigTree cfg)

Searches a config tree for a node satisfying this query. If none is found, Optional.empty() is returned.

Parameters:

cfg - the config tree to search in

Returns:

an Optional describing the queried node, or Optional.empty().

See Also:

run(ConfigTree)

run

@Nonnull
public T run(ConfigTree cfg)
               throws FiberQueryException

Runs this query on a config tree.

If this query's parameters do not match the config's structure, a FiberQueryException carrying error details is thrown. The exception's information can be used for further handling of the erroring config.

Parameters:

cfg - the config tree to run the query on

Returns:

the queried node, with the right path and type

Throws:

FiberQueryException - if this query's parameters do not match the config's structure

See Also:

FiberQueryException.MissingChild, FiberQueryException.WrongType, search(ConfigTree)

toString

public java.lang.String toString()

Returns a string representation of this query.

The string representation consists of the expected node type, followed by the expected value type, if any, followed by a representation of this query's path where individual node names are joined by dots.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this query