Package org.jgrapes.util

Class ConfigurationStore

java.lang.Object

org.jgrapes.core.internal.ComponentVertex

org.jgrapes.core.Component

org.jgrapes.util.ConfigurationStore

All Implemented Interfaces:

Iterable<ComponentType>, Channel, ComponentType, Eligible, Manager

Direct Known Subclasses:

NightConfigStore, PreferencesStore

public abstract class ConfigurationStore
extends Component

A base class for configuration stores.

Implementing classes must override one of the methods structured(String) or values(String) as the default implementations of either calls the other.

Nested Class Summary

Nested classes/interfaces inherited from interface org.jgrapes.core.Channel

Channel.Default

Field Summary

Fields

Modifier and Type	Field	Description
static final Pattern	NUMBER

Fields inherited from class org.jgrapes.core.Component

logger

Fields inherited from interface org.jgrapes.core.Channel

BROADCAST, SELF

Constructor Summary

Constructors

Constructor	Description
ConfigurationStore()	Creates a new component with its channel set to itself.
ConfigurationStore(Channel componentChannel)	Creates a new component base with its channel set to the given channel.
ConfigurationStore(Channel componentChannel, HandlerDefinition.ChannelReplacements channelReplacements)	Creates a new component base like ConfigurationStore(Channel) but with channel mappings for Handler annotations.

Method Summary

Modifier and Type	Method	Description
static <T> Optional<T>	as(Object value, Class<T> requested)	If the value is not null, return it as the requested type.
static Optional<Boolean>	asBoolean(Object value)	Short for as(value, Boolean.class).
static Optional<Instant>	asInstant(Object value)	Short for as(value, Instant.class).
static Optional<Number>	asNumber(Object value)	Short for as(value, Number.class).
static Optional<String>	asString(Object value)	Short for as(value, String.class).
static Map<String,Object>	flatten(Map<String,?> structured)	Configuration information should be kept simple.
static Map<String,Object>	mergeValue(Map<?,?> target, String selector, Object value)	Similar to structure(Map) but merges only a single value into an existing map.
static Map<String,Object>	structure(Map<String,?> flatProperties)	Same as structure(Map, boolean) with false as second argument.
static Map<String,Object>	structure(Map<String,?> flatProperties, boolean convertSparse)	The reverse operation to flatten(Map).
Optional<Map<String,Object>>	structured(String path)	Return the properties for a given path if they exists as structured data, see structure(Map).
Optional<Map<String,String>>	values(String path)	Return the values for a given path if they exist.

Methods inherited from class org.jgrapes.core.Component

channel, component, defaultCriterion, isEligibleFor, setName

Methods inherited from class org.jgrapes.core.internal.ComponentVertex

activeEventPipeline, addHandler, attach, children, componentPath, componentVertex, detach, fire, initComponentsHandlers, iterator, name, newEventPipeline, newEventPipeline, parent, registerAsGenerator, root, toString, unregisterAsGenerator

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface org.jgrapes.core.Manager

stream

Field Details

NUMBER

public static final Pattern NUMBER

Constructor Details

ConfigurationStore

public ConfigurationStore()

Creates a new component with its channel set to itself.

ConfigurationStore

public ConfigurationStore(Channel componentChannel)

Creates a new component base with its channel set to the given channel.

As a special case Channel.SELF can be passed to the constructor to make the component use itself as channel. The special value is necessary as you obviously cannot pass an object to be constructed to its constructor.

Parameters:

componentChannel - the channel that the component’s handlers listen on by default and that Manager.fire(Event, Channel...) sends the event to

ConfigurationStore

public ConfigurationStore(Channel componentChannel,
 HandlerDefinition.ChannelReplacements channelReplacements)

Creates a new component base like ConfigurationStore(Channel) but with channel mappings for Handler annotations.

Parameters:

componentChannel - the channel that the component’s handlers listen on by default and that Manager.fire(Event, Channel...) sends the event to

channelReplacements - the channel replacements to apply to the channels elements of the Handler annotations

Method Details

flatten

public static Map<String,Object> flatten(Map<String,?> structured)

Configuration information should be kept simple.

Sometimes, however, it is unavoidable to structure the information associated with a (logical) key. This can be done by reflecting the structure in the names of actual keys, derived from the logical key. Names such as “key.0”, “key.1”, “key.2” can be used to express that the value associated with “key” is a list of values. “key.a”, “key.b”, “key.c” can be used to associate “key” with a map from “a”, “b”, “c” to some values.

This methods looks at all values in the map passed as argument. If the value is a collection or map, the entry is converted to several entries following the pattern outlined above.

Parameters:

structured - the map with possibly structured properties

Returns:

the map with flattened properties

structure

public static Map<String,Object> structure(Map<String,?> flatProperties)

Same as structure(Map, boolean) with false as second argument.

Parameters:

flatProperties - the flat properties

Returns:

a map with structured values

structure

public static Map<String,Object> structure(Map<String,?> flatProperties,
 boolean convertSparse)

The reverse operation to flatten(Map).

Entries with key names matching the pattern outlined in flatten(Map) are combined to a single entry with a structured value (map or list).

Usually, only key patterns with consecutive numbers starting with zero are converted to lists (e.g. key.0, key.1, key.2). If entries are missing, the values at that level are converted to a Map<Integer,Object> with the given entries instead. If convertSparse is true, incomplete index sets such as key.2, key.3, key.5 are converted to lists with the available number of elements despite the missing entries.

If the derived class overrides structured(String), the leaf values in the returned structure are the values provided by the overriding implementation (while {@link #values(String))} always provides Strings). Some configuration formats define types other then string and therefore value can be e.g. Integers or Instants. In order to support the usage of arbitrary configuration store implementations, values obtained from the data structure returned by structure(Map, boolean) should always be passed through as(Object, Class). This method preserves non-string objects if they match the requested type or converts the value from its string representation to the requested type, if possible.

Parameters:

flatProperties - the flat properties

convertSparse - controls conversion to lists

Returns:

a map with structured values

mergeValue

public static Map<String,Object> mergeValue(Map<?,?> target,
 String selector,
 Object value)

Similar to structure(Map) but merges only a single value into an existing map.

Parameters:

target - the target

selector - the path selector

value - the value

Returns:

the map

values

public Optional<Map<String,String>> values(String path)

Return the values for a given path if they exist.

This method should only be used in cases where configuration values are needed before the InitialConfiguration event is fired, e.g. while creating the component tree.

Parameters:

path - the path

Returns:

the values, if defined for the given path

structured

public Optional<Map<String,Object>> structured(String path)

Return the properties for a given path if they exists as structured data, see structure(Map).

Parameters:

path - the path

Returns:

the values, if defined for the given path

as

public static <T> Optional<T> as(Object value,
 Class<T> requested)

If the value is not null, return it as the requested type.

The method is successful if the value already is of the requested type (or a subtype) or if the value is of type String and can be converted to the requested type.

Supported types are:

• String
• Number, converts from String using BigDecimal(String)
• Instant, converts from TemporalAccessor or from String using {@link Instant#parse(CharSequence))
• Boolean, converts from {@link String} using Boolean.valueOf(String)

Returns:

the value

asString

public static Optional<String> asString(Object value)

Short for as(value, String.class).

Parameters:

value - the value

Returns:

the optional

asNumber

public static Optional<Number> asNumber(Object value)

Short for as(value, Number.class).

Parameters:

value - the value

Returns:

the optional

asInstant

public static Optional<Instant> asInstant(Object value)

Short for as(value, Instant.class).

Parameters:

value - the value

Returns:

the optional

asBoolean

public static Optional<Boolean> asBoolean(Object value)

Short for as(value, Boolean.class).

Parameters:

value - the value

Returns:

the optional