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.

  • Field Details

  • 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:

      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