com.xpcagey.config.api

Interface Config

All Superinterfaces:

AutoCloseable, Iterable<Element>

public interface Config
extends Iterable<Element>, AutoCloseable

Method Summary

Modifier and Type	Method and Description
void	addListener(Consumer<Element> listener) Places a change listener into the system.
void	addTrigger(String key, Consumer<Element> trigger) Places a listener for a single key into the system.
default Optional<Element>	get(String key) Attempt to retrieve an element by key in a type safe manner that allows functional chaining; best used when a key is not required and the program needs to branch based on its presence
SortedMap<String,Element>	getAll() Returns a snapshot of the current elements inside this configuration; if there were multiple descriptors used to build a compound configuration the map will be flattened to show only the values that would be returned by get queries.
String	getName() Returns the name of this configuration; useful if a program wants to have distinct configuration blocks that each correspond to a different context.
Element	getOrNull(String key) Attempt to retrieve an element by key efficiently by not wrapping for type safety if it is missing; best used in situations where temporary object creation overhead is not acceptable but the value is not required
default Element	getOrThrow(String key) Attempt to retrieve an element by key without needing conditional logic to interpret the result; best used when a default has been set for the key or when the program must have a value to operate correctly.
Iterator<String>	getSources() Lists the items that were used to construct this configuration; useful for debugging
default boolean	hasKey(String key) Queries the configuration to see if it currently has an element at the specified key
void	removeListener(Consumer<Element> listener) Removes a change listener from the system.
void	removeTrigger(String key, Consumer<Element> trigger) Removes a listener for a single key from the system.

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Methods inherited from interface java.lang.AutoCloseable

close

Method Detail

getName

String getName()

Returns the name of this configuration; useful if a program wants to have distinct configuration blocks that each correspond to a different context.

Returns:

the name of this configuration that was specified at load time

getSources

Iterator<String> getSources()

Lists the items that were used to construct this configuration; useful for debugging

Returns:

the sources for value lookup used by this config in priority order (highest to lowest)

hasKey

default boolean hasKey(String key)

Queries the configuration to see if it currently has an element at the specified key

Parameters:

key - the key to search

Returns:

true if the key exists

getAll

SortedMap<String,Element> getAll()

Returns a snapshot of the current elements inside this configuration; if there were multiple descriptors used to build a compound configuration the map will be flattened to show only the values that would be returned by get queries.

Returns:

the mapping of current values.

get

default Optional<Element> get(String key)

Attempt to retrieve an element by key in a type safe manner that allows functional chaining; best used when a key is not required and the program needs to branch based on its presence

Parameters:

key - the key to search

Returns:

the element if found, or Optional.empty() if the element was not found.

getOrNull

Element getOrNull(String key)

Attempt to retrieve an element by key efficiently by not wrapping for type safety if it is missing; best used in situations where temporary object creation overhead is not acceptable but the value is not required

Parameters:

key - the key to search

Returns:

the element if found, or null if the element was not found.

getOrThrow

default Element getOrThrow(String key)
                    throws MissingElementException

Attempt to retrieve an element by key without needing conditional logic to interpret the result; best used when a default has been set for the key or when the program must have a value to operate correctly.

Parameters:

key -

Returns:

the element if found

Throws:

MissingElementException - if the element was not found

addListener

void addListener(Consumer<Element> listener)

Places a change listener into the system. The listener will receive reports of any change in the current values supplied by configuration. This binding will *not* attempt to keep the callback from being garbage collected, and is safe to use with ephemeral objects.

Parameters:

listener - the code to be executed when a value updates.

removeListener

void removeListener(Consumer<Element> listener)

Removes a change listener from the system.

Parameters:

listener - the code that was previously registered with addListener

addTrigger

void addTrigger(String key,
                Consumer<Element> trigger)

Places a listener for a single key into the system. If that key is already present, the config will immediately fire the trigger, allowing initialization and update to share a common code path. This binding will *not* attempt to keep the code from being garbage collected, and is safe to use with ephemeral objects. Triggers do not receive an update if the key is missing or removed from the Config

Parameters:

key - the key of the configuration parameter to track

trigger - the code to be executed on register and again when the value updates

removeTrigger

void removeTrigger(String key,
                   Consumer<Element> trigger)

Removes a listener for a single key from the system.

Parameters:

key - the key of the configuration parameter to stop tracking

trigger - the code that was previously registered with addTrigger