jezuch.utils.starmapper3.config
Class Config

java.lang.Object
  jezuch.utils.starmapper3.config.Config

All Implemented Interfaces:

Iterable<Pair<Path,Object>>

public class Config
extends Object
implements Iterable<Pair<Path,Object>>

The Config is similar to Parameters, but with slightly limited and "condensed" interface, more suited to Unified Configuration Model. This is a wrapper around Parameters, so it will use its default Converters.

A "config" consists of values, under Paths (a path is basically a list of Strings). Specific values - defined as NormalSettings - have a Path, type, a default value and Validator. All these things are aggregated in NormalSettings, which are used to access config values. Values can be set using NormalSettings (via set(NormalSetting, Object)) or with other parameters (via set(Class, Path, Object)), after which the value will be converted to proper type (if possible, and if the Path is a known NormalSetting).

NormalSettings contain a concrete Path to a value; but there are also IndexedSettings, which aggregate Path, type, a default value and Validator just like NormalSettings, but the Path is a "pattern", and the IndexedSetting can't be used to retrieve a config value. The pattern is a Path with embedded tags, in a format defined by MessageFormat. You can create a concrete NormalSetting by calling IndexedSetting.get(Object[]) with proper index values (IndexedSetting can also parse a Path to see if it matches its pattern and if so, retrieve the index values from it).

The NormalSettingBase and IndexedSettingBase are a typeless objects that can be used to "derive" other NormalSettings (or IndexedSettings) from them under their subpaths. The derivation process should be done via NormalSettingBase.derive(Class, Object, Validator, String[]), NormalSettingBase.deriveIndexed(Class, Object, Validator, String[]) and IndexedSettingBase.derive(Class, Object, Validator, String[]) methods, as they remember the new NormalSettings and IndexedSettings in a static List, which is later used to reserve them for validation.

The Config class can be subclassed by applications to define their own config values. The NormalSettings and IndexedSettings defined by subclasses by calling NormalSettingBase.derive(Class, Object, Validator, String...), NormalSettingBase.deriveIndexed(Class, Object, Validator, String...) or IndexedSettingBase.derive(Class, Object, Validator, String...), will be registered for validation with the base class.

Author:

ksobolewski

Nested Class Summary

static class	Config.ClassWrapperConverter<T,U extends Config.GenericsWrapper<Class<? extends T>>> A generic Converter for Config.GenericsWrapper for Classes.
static class	Config.GenericsWrapper<T> A wrapper class that aims to convert generified form of any class to a concrete class (overcoming limications of .class operator and allowing for NormalSettings to be of type Class, among others).
static class	Config.SortedIntSet This class is a very thin wrapper around SortedSet<Integer> necessary to be able to specify SortedSet<Integer>.class.

Field Summary

static int	PARAM_CLIP_EAST A magic value for 0th index of SET_IMAGE_CLIP translating to "east".
static int	PARAM_CLIP_NORTH A magic value for 0th index of SET_IMAGE_CLIP translating to "north".
static int	PARAM_CLIP_SOUTH A magic value for 0th index of SET_IMAGE_CLIP translating to "south".
static int	PARAM_CLIP_WEST A magic value for 0th index of SET_IMAGE_CLIP translating to "west".
static int	PARAM_COLOR_BLUE A magic value for 1st index of SET_REGION_COLOR translating to "blue".
static int	PARAM_COLOR_GREEN A magic value for 1st index of SET_REGION_COLOR translating to "green".
static int	PARAM_COLOR_RED A magic value for 1st index of SET_REGION_COLOR translating to "red".
static int	PARAM_IMAGE_SIZE_MAPSIZE A magic value for SET_IMAGE_WIDTH and SET_IMAGE_HEIGHT that equals the image size with the map size for the dimension it is assigned to.
static int	PARAM_IMAGE_SIZE_PROPORTIONAL A magic value for SET_IMAGE_WIDTH and SET_IMAGE_HEIGHT that causes the image to retain the proportions of The Map; this is most useful when one of the dimensions is PARAM_IMAGE_SIZE_PROPORTIONAL and the other is a concrete number.
static Pattern	PATTERN_LIST_SEPARATOR A Pattern used to separate elements of lists of values for config values whose types are arrays; the exact pattern is: "[,; \t\+] *+", which means: a comma, semicolon, space, tab or plus sign followed by any number of spaces.
static NormalSettingBase	SET_CONCURRENCY_BASE A NormalSettingBase for paths under which concurrency options are defined.
static NormalSetting<Integer>	SET_CONCURRENCY_QUEUE_DEPTH Sets maximum queue depth for incoming results in a batch.
static NormalSetting<Integer>	SET_CONCURRENCY_THREADS Sets a ratio of parallelism in batch mode, or, in other words, number of concurrently drawn images.
static NormalSetting<Integer>	SET_CONCURRENCY_THREADS_PERIMAGE Sets a ratio of image-level parallelism, or, in other words, a number of threads drawing each image.
static NormalSettingBase	SET_GLOBAL_BASE A NormalSettingBase for paths under which some global parameters are defined.
static NormalSetting<Boolean>	SET_GLOBAL_LINKFRAMES Causes data from previous time points to carry to later time points; that is each time a new image os prepared the data is not erased and accumulated from scratch.
static NormalSetting<Config.SortedIntSet>	SET_GLOBAL_TIMES A sorted set of time points to draw images from.
static NormalSettingBase	SET_IMAGE_BASE A NormalSettingBase for paths under which image parameters are defined.
static IndexedSetting<Long>	SET_IMAGE_CLIP A value indexed by a string ("west", "south", "east", "north") defining (up to) four edges of a clip regions.
static NormalSetting<Boolean>	SET_IMAGE_DRAWNAMES A flag defining whether Starmapper will draw names for Nodes.
static NormalSetting<Boolean>	SET_IMAGE_DRAWNAMES_NOTOWNED A flag defining whether Starmapper will draw names for Nodes which don't have owners.
static NormalSetting<Boolean>	SET_IMAGE_DRAWNODES A flag defining whether Starmapper will draw Icons for Nodes.
static NormalSetting<Boolean>	SET_IMAGE_DRAWNODES_NOTOWNED A flag defining whether Starmapper will draw Icons for Nodes which don't have owners.
static NormalSetting<Integer>	SET_IMAGE_HEIGHT Defines the image height.
static NormalSetting<Integer>	SET_IMAGE_WIDTH Defines the image width, not including the legend's width.
static NormalSettingBase	SET_MODEL_BASE A NormalSettingBase for paths under which model-specific values are set.
static NormalSettingBase	SET_PLOTTER_BASE A NormalSettingBase for paths under which plotter-specific values are set.
static IndexedSettingBase	SET_REGION_BASE An IndexedSettingBase for paths under which Regions are defined.
static IndexedSetting<Integer>	SET_REGION_COLOR A value indexed by Region's number and colour component ("red", "green", "blue") which declares Region's Color.
static IndexedSetting<String>	SET_REGION_NAME A value indexed by Region's number which declares Region's name.

Constructor Summary

Config()
Creates a new Config with all base settings registered with their Validators and with no custom settings or converters.

Config(List<Setting> settings, List<Converter<?>> converters)
Creates a new Config with all base and specified settings registered with their Validators and with specified Converters also registered.

Method Summary

<T> T	get(NormalSetting<T> setting) Returns a value under the given NormalSetting's Path.
Iterator<Pair<Path,Object>>	iterator() Returns a view of this Config as a mapping of plain Objects under Paths.
<T> void	set(Class<T> type, Path path, T value) Sets a value under the given Path.
<T> void	set(NormalSetting<T> setting, T value) Sets the value under the path described by the given NormalSetting.

Methods inherited from class java.lang.Object

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

Field Detail

PATTERN_LIST_SEPARATOR

public static final Pattern PATTERN_LIST_SEPARATOR

A Pattern used to separate elements of lists of values for config values whose types are arrays; the exact pattern is: "[,; \t\+] *+", which means: a comma, semicolon, space, tab or plus sign followed by any number of spaces.

PARAM_IMAGE_SIZE_MAPSIZE

public static final int PARAM_IMAGE_SIZE_MAPSIZE

A magic value for SET_IMAGE_WIDTH and SET_IMAGE_HEIGHT that equals the image size with the map size for the dimension it is assigned to.

See Also:

Constant Field Values

PARAM_IMAGE_SIZE_PROPORTIONAL

public static final int PARAM_IMAGE_SIZE_PROPORTIONAL

A magic value for SET_IMAGE_WIDTH and SET_IMAGE_HEIGHT that causes the image to retain the proportions of The Map; this is most useful when one of the dimensions is PARAM_IMAGE_SIZE_PROPORTIONAL and the other is a concrete number. If both dimensions are any of the magic values, it has the same effect as PARAM_IMAGE_SIZE_MAPSIZE assigned to both dimensions.

See Also:

Constant Field Values

PARAM_CLIP_WEST

public static final int PARAM_CLIP_WEST

A magic value for 0th index of SET_IMAGE_CLIP translating to "west".

See Also:

Constant Field Values

PARAM_CLIP_SOUTH

public static final int PARAM_CLIP_SOUTH

A magic value for 0th index of SET_IMAGE_CLIP translating to "south".

See Also:

Constant Field Values

PARAM_CLIP_EAST

public static final int PARAM_CLIP_EAST

A magic value for 0th index of SET_IMAGE_CLIP translating to "east".

See Also:

Constant Field Values

PARAM_CLIP_NORTH

public static final int PARAM_CLIP_NORTH

A magic value for 0th index of SET_IMAGE_CLIP translating to "north".

See Also:

Constant Field Values

PARAM_COLOR_RED

public static final int PARAM_COLOR_RED

A magic value for 1st index of SET_REGION_COLOR translating to "red".

See Also:

Constant Field Values

PARAM_COLOR_GREEN

public static final int PARAM_COLOR_GREEN

A magic value for 1st index of SET_REGION_COLOR translating to "green".

See Also:

Constant Field Values

PARAM_COLOR_BLUE

public static final int PARAM_COLOR_BLUE

A magic value for 1st index of SET_REGION_COLOR translating to "blue".

See Also:

Constant Field Values

SET_MODEL_BASE

public static final NormalSettingBase SET_MODEL_BASE

A NormalSettingBase for paths under which model-specific values are set. Each model should define its own namespace for its values.

SET_PLOTTER_BASE

public static final NormalSettingBase SET_PLOTTER_BASE

A NormalSettingBase for paths under which plotter-specific values are set. Each Plotter should define its own namespace for its values.

SET_GLOBAL_BASE

public static final NormalSettingBase SET_GLOBAL_BASE

A NormalSettingBase for paths under which some global parameters are defined.

SET_GLOBAL_TIMES

public static final NormalSetting<Config.SortedIntSet> SET_GLOBAL_TIMES

A sorted set of time points to draw images from. It is being sorted before use to meet guarantees of Starmapper.startBatch(jezuch.utils.Predicate, Config, jezuch.utils.starmapper3.Plotter, java.net.URI, String). Repeated values will be ignored. The times can be specified as single values or ranges in the form <from>..<to> (both ends inclusive), separated by separators matching the regular expression in PATTERN_LIST_SEPARATOR.

List of zero elements is treated specially: all time points encountered are plotted.

Path: /global/times

Type: Config.SortedIntSet (SortedSet<Integer>) (convertible from Strings of items separated by separators matching the regular expression in PATTERN_LIST_SEPARATOR)

Default: new int[0]

Validated: no

SET_GLOBAL_LINKFRAMES

public static final NormalSetting<Boolean> SET_GLOBAL_LINKFRAMES

Causes data from previous time points to carry to later time points; that is each time a new image os prepared the data is not erased and accumulated from scratch. This is so regardles if SET_GLOBAL_TIMES is set or not.

Path: /global/link-frames

Type: Boolean

Default: Boolean.TRUE

Validated: no

SET_IMAGE_BASE

public static final NormalSettingBase SET_IMAGE_BASE

A NormalSettingBase for paths under which image parameters are defined.

SET_IMAGE_WIDTH

public static final NormalSetting<Integer> SET_IMAGE_WIDTH

Defines the image width, not including the legend's width. Can be a concrete positive numer or one of magic values: -1 or -2.

Path: /image/width

Type: Integer

Default: 640

Validated: yes (value ≥ 1 or value in (-1, -2))

SET_IMAGE_HEIGHT

public static final NormalSetting<Integer> SET_IMAGE_HEIGHT

Defines the image height. Can be a concrete positive numer or one of magic values: -1 or -2.

Path: /image/height

Type: Integer

Default: 480

Validated: yes (value ≥ 1 or value in (-1, -2))

SET_IMAGE_CLIP

public static final IndexedSetting<Long> SET_IMAGE_CLIP

A value indexed by a string ("west", "south", "east", "north") defining (up to) four edges of a clip regions. Each of these edges can be null meaning the clip egde equal to map edge.

Path: /image/clip/{0}

Type: Integer

Default: null

Validated: no

SET_IMAGE_DRAWNODES

public static final NormalSetting<Boolean> SET_IMAGE_DRAWNODES

A flag defining whether Starmapper will draw Icons for Nodes.

Path: /image/draw-nodes

Type: Boolean

Default: Boolean.TRUE

Validated: no

SET_IMAGE_DRAWNODES_NOTOWNED

public static final NormalSetting<Boolean> SET_IMAGE_DRAWNODES_NOTOWNED

A flag defining whether Starmapper will draw Icons for Nodes which don't have owners.

Path: /image/draw-nodes-notowned

Type: Boolean

Default: Boolean.TRUE

Validated: no

SET_IMAGE_DRAWNAMES

public static final NormalSetting<Boolean> SET_IMAGE_DRAWNAMES

A flag defining whether Starmapper will draw names for Nodes.

Path: /image/draw-names

Type: Boolean

Default: Boolean.TRUE

Validated: no

SET_IMAGE_DRAWNAMES_NOTOWNED

public static final NormalSetting<Boolean> SET_IMAGE_DRAWNAMES_NOTOWNED

A flag defining whether Starmapper will draw names for Nodes which don't have owners.

Path: /image/draw-names-notowned

Type: Boolean

Default: Boolean.FALSE

Validated: no

SET_REGION_BASE

public static final IndexedSettingBase SET_REGION_BASE

An IndexedSettingBase for paths under which Regions are defined.

SET_REGION_NAME

public static final IndexedSetting<String> SET_REGION_NAME

A value indexed by Region's number which declares Region's name.

Path: /regions/reg{0}/name

Type: String

Default: null

Validated: no

SET_REGION_COLOR

public static final IndexedSetting<Integer> SET_REGION_COLOR

A value indexed by Region's number and colour component ("red", "green", "blue") which declares Region's Color.

Path: /regions/reg{0}/color/{1}

Type: Integer

Default: 0

Validated: yes (value ≥ 0 and value ≤ 255)

SET_CONCURRENCY_BASE

public static final NormalSettingBase SET_CONCURRENCY_BASE

A NormalSettingBase for paths under which concurrency options are defined.

SET_CONCURRENCY_THREADS

public static final NormalSetting<Integer> SET_CONCURRENCY_THREADS

Sets a ratio of parallelism in batch mode, or, in other words, number of concurrently drawn images. This value can be also 0, which behaves just like concurrency of 1, but does not "seed" the thread pool with tasks. This has the effect that if the data model has to wait to return reports, the image is sent to client immediately after it's finished, not blocked by the model.

Path: /concurrency/threads

Type: Integer

Default: 0

Validated: yes (value ≥ 0)

SET_CONCURRENCY_QUEUE_DEPTH

public static final NormalSetting<Integer> SET_CONCURRENCY_QUEUE_DEPTH

Sets maximum queue depth for incoming results in a batch. The BlockingQueue returned from Starmapper.startBatch(jezuch.utils.Predicate, Config, jezuch.utils.starmapper3.Plotter, java.net.URI, String) will be bounded by this number; if the client application can't keep up with consuming the images, producer threads will wait until there's enough free space in the output queue. The value can be null, meaning an unbounded queue.

This config value is useful to limit mamory usage of Starmapper. The image buffers are rather large and for each image a new buffer is allocated (TODO: implement buffer reuse?) so if the producer threads are allowed to run without limits and the client application doesn't consume the results fast enough, they can quickly exhaust all available memory.

Path: /concurrency/queue-depth

Type: Integer

Default: null (unbounded)

Validated: yes (value ≥ 1 or == null)

SET_CONCURRENCY_THREADS_PERIMAGE

public static final NormalSetting<Integer> SET_CONCURRENCY_THREADS_PERIMAGE

Sets a ratio of image-level parallelism, or, in other words, a number of threads drawing each image. This is cumulative with SET_CONCURRENCY_THREADS.

Path: /concurrency/threads/per-image

Type: Integer

Default: number of processors availale to this VM

Validated: yes (value ≥ 1)

Constructor Detail

Config

public Config()

Creates a new Config with all base settings registered with their Validators and with no custom settings or converters.

Config

public Config(List<Setting> settings,
              List<Converter<?>> converters)

Creates a new Config with all base and specified settings registered with their Validators and with specified Converters also registered. The settings passed to this constructor override any base settings under the same path. Similarily, converters override any existing (default) converters for the same class.

Be sure to specify all converters necessary to handle all the settings.

Method Detail

get

public <T> T get(NormalSetting<T> setting)
      throws ConversionException

Returns a value under the given NormalSetting's Path.

Type Parameters:

T - the NormalSetting's type

Parameters:

setting - the NormalSetting

Returns:

a value under the given NormalSetting's Path

Throws:

ConversionException - if the value somehow can't be converted (quite impossible)

set

public <T> void set(Class<T> type,
                    Path path,
                    T value)
         throws ConversionException,
                ValidationException

Sets a value under the given Path. The value will be converted to proper type if this Path belongs to a known NormalSetting.

Type Parameters:

T - the value's type

Parameters:

type - the value's type's Class

path - the value's Path

value - the value

Throws:

ConversionException - if the value can't be converted to proper type

ValidationException - if the value is invalid for the NormalSetting owning this Path

set

public <T> void set(NormalSetting<T> setting,
                    T value)
         throws ConversionException,
                ValidationException

Sets the value under the path described by the given NormalSetting.

Type Parameters:

T - the NormalSetting's type

Parameters:

setting - the NormalSetting to set

value - the NormalSetting's new value

Throws:

ConversionException - if the value somehow can't be converted to proper type

ValidationException - if the value is invalid for the NormalSetting owning this Path

iterator

public Iterator<Pair<Path,Object>> iterator()

Returns a view of this Config as a mapping of plain Objects under Paths. The Paths are a concrete values, not patterns.

Specified by:

iterator in interface Iterable<Pair<Path,Object>>

Returns:

an Iterator of all values in this Config