uk.co.bigbeeconsultants.bconfig

Class ConfigJ

java.lang.Object

uk.co.bigbeeconsultants.bconfig.ConfigJ

All Implemented Interfaces:

java.util.Map<java.lang.String,java.lang.String>

public final class ConfigJ
extends java.lang.Object
implements java.util.Map<java.lang.String,java.lang.String>

Provides configuration data in the form of a Java map. Normal construction is via the factory methods, which provide all the necessary parsing and string interpolation behaviour.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
static ConfigJ	Empty Provides a singleton empty instance.
static ValueFactory	valueFactory Provides the converter to convert Strings to Values.

Method Summary

Methods

Modifier and Type	Method and Description
ConfigJ	add(java.lang.String key, java.lang.String value) Gets a new configuration based on this one with another value added or replaced.
ConfigJ	addAll(java.util.Map<java.lang.String,java.lang.String> map) Adds a number of elements provided by a second map and returns a new instance with the added elements.
void	clear()
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
ConfigJ	drop(java.lang.String key) Gets a new configuration based on this one with a value removed.
ConfigJ	dropAll(java.lang.Iterable<java.lang.String> keys) Gets a new configuration based on this one with removal of all the keys given in another collection.
ConfigJ	endingWith(java.lang.String suffix) Filters the subset of entries ending with a given suffix, returning a new ConfigJ instance.
java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.String>>	entrySet()
boolean	equals(java.lang.Object o)
static ConfigJ	from(ConfigJ primary, ConfigJ fallback) Constructs an instance using an existing Config with a cascaded fallback.
static ConfigJ	from(ConfigSourceJ source) Constructs an instance from an input source.
static ConfigJ	from(ConfigSourceJ source, ConfigJ fallback) Constructs an instance from an input source and with a cascaded fallback.
static ConfigJ	from(ConfigSourceJ source, java.util.Set<java.lang.String> requiredKeys) Constructs an instance from an input source and with a specified set of required keys, usually obtained from a default instance.
static ConfigJ	from(java.io.File file) Constructs an instance from a file.
static ConfigJ	from(java.io.File file, ConfigJ fallback) Constructs an instance from a file and with a cascaded fallback.
static ConfigJ	from(java.io.File file, java.util.Set<java.lang.String> requiredKeys) Constructs an instance from a file and with a specified set of required keys, usually obtained from a default instance.
static ConfigJ	from(java.util.Map<java.lang.String,java.lang.String> sourceData) Constructs an instance from a map, keeping the same iteration order.
static ConfigJ	from(ParserJ parser) Constructs an instance from an input parser.
static ConfigJ	from(ParserJ parser, ConfigJ fallback) Constructs an instance using the parser supplied and with a cascaded fallback.
static ConfigJ	from(ParserJ parser, java.util.Set<java.lang.String> requiredKeys) Constructs an instance using the parser supplied and with a specified set of required keys, usually obtained from a default instance.
static ConfigJ	fromClasspath(java.lang.String resourcePath) Constructs an instance from a classpath resource.
static ConfigJ	fromClasspath(java.lang.String resourcePath, ConfigJ fallback) Constructs an instance from a classpath resource and with a cascaded fallback.
static ConfigJ	fromClasspath(java.lang.String resourcePath, java.util.Set<java.lang.String> requiredKeys) Constructs an instance from a classpath resource and with a specified set of required keys, usually obtained from a default instance.
java.lang.String	get(java.lang.Object key) Gets a required value.
java.lang.String	getOrElse(java.lang.Object key, java.lang.String defaultValue) Gets a value, using a default if the key is not found in the configuration.
java.lang.String	getOrNull(java.lang.Object key) Gets a value if present.
int	hashCode()
boolean	isEmpty()
java.util.Set<java.lang.String>	keySet()
ConfigJ	overriddenBy(ConfigSourceJ source) Constructs a new instance based on source information, using `this` as the fallback.
ConfigJ	overriddenBy(java.io.File file) Constructs a new instance based on source information, using `this` as the fallback.
ConfigJ	overriddenBy(java.util.Map<java.lang.String,java.lang.String> other) Constructs a new instance based on source information, using `this` as the fallback.
ConfigJ	overriddenBy(ParserJ parser) Constructs a new instance based on source information, using `this` as the fallback.
java.lang.String	put(java.lang.String key, java.lang.String value)
void	putAll(java.util.Map<? extends java.lang.String,? extends java.lang.String> m)
java.lang.String	remove(java.lang.Object key)
ConfigJ	section(java.lang.String sectionName) If 'ini' file sections are used, this filters the subset of entries in a given section, returning a new ConfigJ instance.
int	size()
ConfigJ	startingWith(java.lang.String prefix) Filters the subset of entries starting with a given prefix, returning a new ConfigJ instance.
<T> T	toBean(java.lang.Class<T> beanClass) Copies some or all of this config into a new instance of a specified javabean class.
<T> T	toBean(T bean) Copies some or all of this config into a specified javabean.
java.lang.String	toString()
Value	value(java.lang.Object key) Gets a required value.
Value	valueOrElse(java.lang.Object key, java.lang.String defaultValue) Gets a value, using a default if the key is not found in the configuration.
java.util.Collection<java.lang.String>	values()
ConfigJ	verifyKeys(java.util.Set<java.lang.String> requiredKeys) Provides checking that the configuration keys are exactly as expected.
ConfigJ	verifyKeys(java.util.Set<java.lang.String> requiredKeys, java.lang.String name) Provides checking that the configuration keys are exactly as expected.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

Empty

public static final ConfigJ Empty

Provides a singleton empty instance.

valueFactory

public static ValueFactory valueFactory

Provides the converter to convert Strings to Values. It can be replaced by other subclasses to suit.

This is a mutable public static field to allow for extension, whilst being very simple in the normal un-extended use-case; this is a deliberately-simple strategy.

Method Detail

size

public int size()

Specified by:

size in interface java.util.Map<java.lang.String,java.lang.String>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Map<java.lang.String,java.lang.String>

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map<java.lang.String,java.lang.String>

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map<java.lang.String,java.lang.String>

get

public java.lang.String get(java.lang.Object key)

Gets a required value. If there is doubt whether the key exists, it should first be tested with {#containsKey} to avoid the NoSuchElementException.

Otherwise, {#getOrNull} or {#getOrElse} could be used.

Specified by:

get in interface java.util.Map<java.lang.String,java.lang.String>

Parameters:

key - the key

Returns:

the value

Throws:

java.util.NoSuchElementException - if the key is not found.

getOrNull

public java.lang.String getOrNull(java.lang.Object key)

Gets a value if present.

Parameters:

key - the key

Returns:

the value if the key is present, null otherwise.

getOrElse

public java.lang.String getOrElse(java.lang.Object key,
                         java.lang.String defaultValue)

Gets a value, using a default if the key is not found in the configuration.

Parameters:

key - the key

defaultValue - the value to be returned if the key is absent

Returns:

the value

valueOrElse

public Value valueOrElse(java.lang.Object key,
                java.lang.String defaultValue)

Gets a value, using a default if the key is not found in the configuration. If the string is surrounded by double-quotes, these are removed.

Parameters:

key - the key

defaultValue - the value to be returned if the key is absent

Returns:

the value

value

public Value value(java.lang.Object key)

Gets a required value. If there is doubt whether the key exists, it should first be tested with {#containsKey} to avoid the NoSuchElementException. Otherwise, {#valueOrElse} can be used.

Parameters:

key - the key

Returns:

the value

Throws:

java.util.NoSuchElementException - if the key is not found.

toBean

public <T> T toBean(java.lang.Class<T> beanClass)
         throws java.lang.ReflectiveOperationException

Copies some or all of this config into a new instance of a specified javabean class. This operates via reflection to create a new bean instance. If the bean has setters, it uses them to populate values using the setter names to indicate the keys into this config instance. Otherwise, if the bean has a constructor with a suitable number of parameters, it creates a new instance using that constructor, with the order of the constructor parameters being determined by the declaration order of the bean's fields. The bean may itself contain nested beans that will be configured recursively provided the configuration contains the necessary subsections (see section(String) and startingWith(String)).

Type Parameters:

T - the type of the bean

Parameters:

beanClass - the required javabean class

Returns:

the new javabean

Throws:

java.lang.ReflectiveOperationException - if it was not possible to create or modify the bean by reflection for some reason

java.util.NoSuchElementException - if any key is not found, i.e. the bean properties are not a proper subset of the available config keys.

java.lang.IllegalArgumentException - if the type of the data cannot be coerced to match the type of the setter / constructor parameter.

toBean

public <T> T toBean(T bean)
         throws java.lang.ReflectiveOperationException

Copies some or all of this config into a specified javabean. This operates via reflection to use its setters to populate values using the setter names to indicate the keys into this config instance. The bean may itself contain nested beans that will be configured recursively provided the configuration contains the necessary subsections (see section(String) and startingWith(String)).

Type Parameters:

T - the type of the bean

Parameters:

bean - the existing javabean

Returns:

the modified javabean

Throws:

java.lang.ReflectiveOperationException - if it was not possible to modify the bean by reflection for some reason

java.util.NoSuchElementException - if any key is not found, i.e. the bean properties are not a proper subset of the available config keys.

java.lang.IllegalArgumentException - if the type of the data cannot be coerced to match the type of the setter.

put

public java.lang.String put(java.lang.String key,
                   java.lang.String value)

Specified by:

put in interface java.util.Map<java.lang.String,java.lang.String>

remove

public java.lang.String remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map<java.lang.String,java.lang.String>

putAll

public void putAll(java.util.Map<? extends java.lang.String,? extends java.lang.String> m)

Specified by:

putAll in interface java.util.Map<java.lang.String,java.lang.String>

clear

public void clear()

Specified by:

clear in interface java.util.Map<java.lang.String,java.lang.String>

add

public ConfigJ add(java.lang.String key,
          java.lang.String value)

Gets a new configuration based on this one with another value added or replaced. The original instance is not modified.

addAll

public ConfigJ addAll(java.util.Map<java.lang.String,java.lang.String> map)

Adds a number of elements provided by a second map and returns a new instance with the added elements. The original instance is not modified.

drop

public ConfigJ drop(java.lang.String key)

Gets a new configuration based on this one with a value removed. The original instance is not modified.

dropAll

public ConfigJ dropAll(java.lang.Iterable<java.lang.String> keys)

Gets a new configuration based on this one with removal of all the keys given in another collection. The original instance is not modified.

keySet

public java.util.Set<java.lang.String> keySet()

Specified by:

keySet in interface java.util.Map<java.lang.String,java.lang.String>

values

public java.util.Collection<java.lang.String> values()

Specified by:

values in interface java.util.Map<java.lang.String,java.lang.String>

entrySet

public java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.String>> entrySet()

Specified by:

entrySet in interface java.util.Map<java.lang.String,java.lang.String>

equals

public boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Map<java.lang.String,java.lang.String>

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Map<java.lang.String,java.lang.String>

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

section

public ConfigJ section(java.lang.String sectionName)

If 'ini' file sections are used, this filters the subset of entries in a given section, returning a new ConfigJ instance.

This is the same as filtering those entries starting with a given prefix (i.e. {#startingWith}), except that an implied '.' joins the section name to its contained keys.

The keys in the resulting ConfigJ are shortened by removing the implied prefix from them, but in the typical case of an 'ini' file, this actually means the keys will be exactly as written. For example, if a section is "[xxx]" and it contains entry "yyy=1", the resulting ConfigJ will contain "yyy=1". (Note that the parent ConfigJ would contain "xxx.yyy=1" in this case.) The values are unchanged from the source data.

startingWith

public ConfigJ startingWith(java.lang.String prefix)

Filters the subset of entries starting with a given prefix, returning a new ConfigJ instance. This allows hierarchical configurations to be loaded from a single file (or multiple files, if using the overriding feature in the constructors).

The keys in the resulting ConfigJ are shortened by removing the prefix from them. For example, if the prefix "xxx." is applied the entry "xxx.yyy=1", the resulting ConfigJ will contain "yyy=1". The values are unchanged from the source data.

endingWith

public ConfigJ endingWith(java.lang.String suffix)

Filters the subset of entries ending with a given suffix, returning a new ConfigJ instance. This allows hierarchical configurations to be loaded from a single file (or multiple files, if using the overriding feature in the constructors).

The keys in the resulting ConfigJ are shortened by removing the suffix from them. For example, if the suffix ".yyy" is applied the entry "xxx.yyy=1", the resulting ConfigJ will contain "xxx=1". The values are unchanged from the source data.

verifyKeys

public ConfigJ verifyKeys(java.util.Set<java.lang.String> requiredKeys)
                   throws ConfigException

Provides checking that the configuration keys are exactly as expected.

Parameters:

requiredKeys - the specification of what's required

Returns:

this

Throws:

ConfigException

verifyKeys

public ConfigJ verifyKeys(java.util.Set<java.lang.String> requiredKeys,
                 java.lang.String name)
                   throws ConfigException

Provides checking that the configuration keys are exactly as expected.

Parameters:

requiredKeys - the specification of what's required

name - a diagnostic name used in any error message, e.g. the name of the file (default is "Config")

Returns:

this

Throws:

ConfigException

overriddenBy

public ConfigJ overriddenBy(java.util.Map<java.lang.String,java.lang.String> other)

Constructs a new instance based on source information, using `this` as the fallback.

Parameters:

other - the source for the new instance. Note that this could be a `Config`.

Returns:

the new instance composed from `other` with `this` as fallback.

overriddenBy

public ConfigJ overriddenBy(ParserJ parser)

Constructs a new instance based on source information, using `this` as the fallback.

Parameters:

parser - the source for the new instance

Returns:

the new instance constructed from `parser` with `this` as fallback.

overriddenBy

public ConfigJ overriddenBy(ConfigSourceJ source)
                     throws ConfigException

Constructs a new instance based on source information, using `this` as the fallback.

Parameters:

source - the source for the new instance

Returns:

the new instance constructed from `source` with `this` as fallback.

Throws:

ConfigException

overriddenBy

public ConfigJ overriddenBy(java.io.File file)
                     throws ConfigException

Constructs a new instance based on source information, using `this` as the fallback.

Parameters:

file - the source for the new instance

Returns:

the new instance constructed from `file` with `this` as fallback.

Throws:

ConfigException

from

public static ConfigJ from(java.util.Map<java.lang.String,java.lang.String> sourceData)
                    throws ConfigException

Constructs an instance from a map, keeping the same iteration order. A defensive copy is made of the source data.

Throws:

ConfigException

from

public static ConfigJ from(java.io.File file)
                    throws ConfigException

Constructs an instance from a file.

Throws:

ConfigException

from

public static ConfigJ from(ConfigSourceJ source)
                    throws ConfigException

Constructs an instance from an input source.

Throws:

ConfigException

fromClasspath

public static ConfigJ fromClasspath(java.lang.String resourcePath)
                             throws ConfigException

Constructs an instance from a classpath resource.

Throws:

ConfigException

from

public static ConfigJ from(ParserJ parser)

Constructs an instance from an input parser.

from

public static ConfigJ from(java.io.File file,
           ConfigJ fallback)
                    throws ConfigException

Constructs an instance from a file and with a cascaded fallback.

Throws:

ConfigException

from

public static ConfigJ from(ConfigSourceJ source,
           ConfigJ fallback)
                    throws ConfigException

Constructs an instance from an input source and with a cascaded fallback.

Throws:

ConfigException

fromClasspath

public static ConfigJ fromClasspath(java.lang.String resourcePath,
                    ConfigJ fallback)
                             throws ConfigException

Constructs an instance from a classpath resource and with a cascaded fallback.

Throws:

ConfigException

from

public static ConfigJ from(ParserJ parser,
           ConfigJ fallback)

Constructs an instance using the parser supplied and with a cascaded fallback.

from

public static ConfigJ from(ConfigJ primary,
           ConfigJ fallback)

Constructs an instance using an existing Config with a cascaded fallback.

from

public static ConfigJ from(java.io.File file,
           java.util.Set<java.lang.String> requiredKeys)
                    throws ConfigException

Constructs an instance from a file and with a specified set of required keys, usually obtained from a default instance.

Throws:

ConfigException

from

public static ConfigJ from(ConfigSourceJ source,
           java.util.Set<java.lang.String> requiredKeys)
                    throws ConfigException

Constructs an instance from an input source and with a specified set of required keys, usually obtained from a default instance.

Throws:

ConfigException

fromClasspath

public static ConfigJ fromClasspath(java.lang.String resourcePath,
                    java.util.Set<java.lang.String> requiredKeys)
                             throws ConfigException

Constructs an instance from a classpath resource and with a specified set of required keys, usually obtained from a default instance.

Throws:

ConfigException

from

public static ConfigJ from(ParserJ parser,
           java.util.Set<java.lang.String> requiredKeys)
                    throws ConfigException

Constructs an instance using the parser supplied and with a specified set of required keys, usually obtained from a default instance.

Throws:

ConfigException