Package com.norconex.commons.lang.map

# Class Properties

java.lang.Object
com.norconex.commons.lang.map.ObservableMap<String,List<String>>
com.norconex.commons.lang.map.Properties

All Implemented Interfaces:
  `Serializable`, `Map<String,List<String>>`

Direct Known Subclasses:
  `QueryString`

public class Properties extends ObservableMap<String,List<String>> implements Serializable

This class is a enhanced version of `Properties` that enforces the use of String keys and values internally, but offers many convenience methods for storing and retrieving multiple values of different types (e.g. Integer, Locale, File, etc). It also supports properties with multiple values. You can also see this class as a string-based multi-value map with helpful methods. While it does not extend `Properties`, it offers similar load and store methods and can be used as a replacement for it in many cases. It also adds support for storing/loading as JSON, XML, and Java Bean.

This class extends `ObservableMap` which means you can listen for property changes.

To insert values, there are set and add methods. The set methods will first remove any existing value(s) under the given key before inserting the new one(s). It is essentially the same behavior as `Map.put(Object, Object)`. The add method will add the new value(s) to the list of already existing ones (if any).

The storing of entries with multiple values will create one file entry per value. To preserve old behavior and force multiple values to be on the same line, use the store/load method accepting a joining delimiter.

Upon encountering a problem in parsing a value to its desired type, a `PropertiesException` is thrown.

See Also:
  - Serialized Form

- ## Nested Class Summary

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

  `Map.Entry<K,V>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_JAVA_PROPERTIES_DELIMITER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Properties()`
  Create a new instance with case-sensitive keys.
  `Properties(boolean caseInsensitiveKeys)`
  Creates a new instance.
  `Properties(Map<String,List<String>> map)`
  Decorates `Map` as a `Properties`.
  `Properties(Map<String,List<String>> map, boolean caseInsensitiveKeys)`
  Decorates a `Map` argument as a `Properties`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final <T> void`
  `add(String key, T... values)`
  Adds one or multiple string values.
  `final <T> void`
  `addList(String key, List<T> values)`
  Adds one or multiple values as strings.
  `boolean`
  `equals(Object other)`
  `void`
  `fromString(String str)`
  Reads a property list (key and element pairs) from the input string.
  `final List<String>`
  `get(Object key)`
  `final <T> T`
  `get(String key, Class<T> type)`
  Gets a single value, converted to the given type.
  `final <T> T`
  `get(String key, Class<T> type, T defaultValue)`
  Gets a single value, converted to the given type.
  `final BigDecimal`
  `getBigDecimal(String key)`
  Gets value as a BigDecimal.
  `final BigDecimal`
  `getBigDecimal(String key, BigDecimal defaultValue)`
  Gets value as a BigDecimal.
  `final List<BigDecimal>`
  `getBigDecimals(String key)`
  Gets values as a list of BigDecimals.
  `final Boolean`
  `getBoolean(String key)`
  Gets value as a boolean.
  `final Boolean`
  `getBoolean(String key, Boolean defaultValue)`
  Gets value as a boolean.
  `final List<Boolean>`
  `getBooleans(String key)`
  Gets values as a list of booleans.
  `final Class<?>`
  `getClass(String key)`
  Gets a class, assuming key value is a fully qualified class name available in the classloader.
  `final Class<?>`
  `getClass(String key, Class<?> defaultValue)`
  Gets a class, assuming key value is a fully qualified class name available in the classloader.
  `final List<Class>`
  `getClasses(String key)`
  Gets values as a list of initialized classes.
  `final Date`
  `getDate(String key)`
  Gets value as a date.
  `final Date`
  `getDate(String key, Date defaultValue)`
  Gets value as a date.
  `final List<Date>`
  `getDates(String key)`
  Gets values as a list of dates.
  `final Double`
  `getDouble(String key)`
  Gets value as a double.
  `final Double`
  `getDouble(String key, Double defaultValue)`
  Gets value as a double.
  `final List<Double>`
  `getDoubles(String key)`
  Gets values as a list of doubles.
  `final File`
  `getFile(String key)`
  Gets a file, assuming key value is a file system path.
  `final File`
  `getFile(String key, File defaultValue)`
  Gets a file, assuming key value is a file system path.
  `final List<File>`
  `getFiles(String key)`
  Gets values as a list of files.
  `final Float`
  `getFloat(String key)`
  Gets value as a float.
  `final Float`
  `getFloat(String key, Float defaultValue)`
  Gets value as a float.
  `final List<Float>`
  `getFloats(String key)`
  Gets values as a list of floats.
  `final Instant`
  `getInstant(String key)`
  Gets value as a UTC date-time `Instant`.
  `final Instant`
  `getInstant(String key, Instant defaultValue)`
  Gets value as a UTC date-time `Instant`.
  `final List<Instant>`
  `getInstants(String key)`
  Gets values as a list of UTC date-time `Instant`s.
  `final Integer`
  `getInteger(String key)`
  Gets value as an integer.
  `final Integer`
  `getInteger(String key, Integer defaultValue)`
  Gets value as an integer.
  `final List<Integer>`
  `getIntegers(String key)`
  Gets values as a list of integers.
  `final <T> List<T>`
  `getList(String key, Class<T> type)`
  Gets a list of values, with its elements converted to the given type.
  `final <T> List<T>`
  `getList(String key, Class<T> type, List<T> defaultValues)`
  Gets a list of values, with its elements converted to the given type.
  `final LocalDateTime`
  `getLocalDateTime(String key)`
  Gets value as a local date-time.
  `final LocalDateTime`
  `getLocalDateTime(String key, LocalDateTime defaultValue)`
  Gets value as a local date-time.
  `final List<LocalDateTime>`
  `getLocalDateTimes(String key)`
  Gets values as a list of local date-times.
  `final Locale`
  `getLocale(String key)`
  Gets value as a locale.
  `final Locale`
  `getLocale(String key, Locale defaultValue)`
  Gets value as a locale.
  `final List<Locale>`
  `getLocales(String key)`
  Gets values as a list of locales.
  `final Long`
  `getLong(String key)`
  Gets value as a long.
  `final Long`
  `getLong(String key, Long defaultValue)`
  Gets value as a long.
  `final List<Long>`
  `getLongs(String key)`
  Gets values as a list of longs.
  `final String`
  `getString(String key)`
  Gets value as string.
  `final String`
  `getString(String key, String defaultValue)`
  Gets value as string.
  `final List<String>`
  `getStrings(String key)`
  Gets values as a list of strings.
  `int`
  `hashCode()`
  `boolean`
  `isCaseInsensitiveKeys()`
  Gets whether keys are case sensitive or not.
  `void`
  `loadFromBean(Object bean)`
  Converts all the bean properties into entries in this instance.
  `void`
  `loadFromJSON(InputStream in)`
  Loads all of the properties from the JSON document input stream (UTF-8) into this instance.
  `void`
  `loadFromJSON(Reader reader)`
  Loads all of the properties from the JSON document reader into this instance.
  `void`
  `loadFromMap(Map<?,?> map)`
  Reads all key/value pairs in the given map, and add them to this `Map`.
  `void`
  `loadFromProperties(InputStream inStream)`
  Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`.
  `void`
  `loadFromProperties(InputStream inStream, String delimiter)`
  Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`.
  `void`
  `loadFromProperties(Reader reader)`
  Loads this `Map` from an input of a format compatible with `Properties.load(Reader)`.
  `void`
  `loadFromProperties(Reader reader, String delimiter)`
  Loads this `Map` from an input of a format compatible with `Properties.load(Reader)`.
  `void`
  `loadFromXML(InputStream in)`
  Loads this `Map` from an input of a format compatible with `Properties.loadFromXML(InputStream)`.
  `void`
  `loadFromXML(InputStream in, String delimiter)`
  Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`.
  `void`
  `loadFromXML(Reader reader)`
  Loads this `Map` from an input of a format compatible with `Properties.loadFromXML(InputStream)`.
  `void`
  `loadFromXML(Reader reader, String delimiter)`
  Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`.
  `Properties`
  `match(PropertyMatcher propertyMatcher)`
  Gets a properties subset for keys and values matched by the property matcher.
  `Properties`
  `match(TextMatcher fieldMatcher, TextMatcher valueMatcher)`
  Gets a properties subset for matching keys and values.
  `Properties`
  `matchKeys(TextMatcher keyMatcher)`
  Gets a properties subset for keys matched by the key matcher.
  `Properties`
  `matchValues(TextMatcher valueMatcher)`
  Gets a properties subset for values matched by the value matcher.
  `List<String>`
  `put(String key, List<String> values)`
  `void`
  `putAll(Map<? extends String,? extends List<String>> m)`
  `final List<String>`
  `remove(Object key)`
  `final <T> void`
  `set(String key, T... values)`
  Sets one or multiple values as strings replacing existing ones.
  `final <T> void`
  `setList(String key, List<T> values)`
  Sets one or multiple values as strings replacing existing ones.
  `void`
  `storeToBean(Object bean)`
  Copy all properties in this map to the given bean, mapping keys to setter methods of the same name.
  `void`
  `storeToJSON(OutputStream os)`
  Writes this `Map` as JSON to the output stream as UTF-8 in a format suitable for using the `loadFromJSON(InputStream)` method.
  `void`
  `storeToJSON(Writer writer)`
  Writes this `Map` as JSON to the writer in a format suitable for using the `loadFromJSON(Reader)` method.
  `void`
  `storeToProperties(OutputStream out)`
  Stores this `Map` in a format compatible with `Properties.store(OutputStream, String)`.
  `void`
  `storeToProperties(OutputStream out, String delimiter)`
  Stores this `Map` in a format compatible with `Properties.store(OutputStream, String)`.
  `void`
  `storeToProperties(Writer writer)`
  Stores this `Map` in a format compatible with `Properties.store(Writer, String)`.
  `void`
  `storeToProperties(Writer writer, String delimiter)`
  Stores this `Map` in a format compatible with `Properties.store(Writer, String)`.
  `void`
  `storeToXML(OutputStream os)`
  Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`.
  `void`
  `storeToXML(OutputStream os, String delimiter)`
  Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`.
  `void`
  `storeToXML(Writer writer)`
  Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`.
  `void`
  `storeToXML(Writer writer, String delimiter)`
  Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`.
  `Properties`
  `toProperties()`
  Converts this `Map` to a new Java `Properties` instance.
  `String`
  `toString()`
  Returns this `Map` in a format compatible with `Properties.store(Writer, String)`.
  `List<String>`
  `valueList()`
  Returns all property values merged into a single list.

  ### Methods inherited from class com.norconex.commons.lang.map.ObservableMap

  `addMapChangeListener, clear, clearMapChangeListeners, containsKey, containsValue, entrySet, getMapChangeListeners, isEmpty, keySet, removeMapChangeListener, size, values`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- ## Field Details

  - ### DEFAULT_JAVA_PROPERTIES_DELIMITER

    public static final String DEFAULT_JAVA_PROPERTIES_DELIMITER
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Properties

    public Properties()
    Create a new instance with case-sensitive keys. Internally wraps a `HashMap` to store keys and values.

  - ### Properties

    public Properties(boolean caseInsensitiveKeys)
    Creates a new instance. Internally wraps a `HashMap` to store keys and values.
    Parameters:
      `caseInsensitiveKeys` - when `true` methods taking a key argument will consider the key being passed without consideration for character case.

  - ### Properties

    public Properties(Map<String,List<String>> map)
    Decorates `Map` as a `Properties`. As of version 1.4 the `Map` argument is decorated so that modifications to this instance will also modify the supplied `Map`. To use a `Map` to initialize values only, use the `loadFromMap(Map)` method.
    Parameters:
      `map` - the Map to decorate

  - ### Properties

    public Properties(Map<String,List<String>> map, boolean caseInsensitiveKeys)
    Decorates a `Map` argument as a `Properties`. As of version 1.4 the `Map` argument is decorated so that modifications to this instance will also modify the supplied `Map`. To use a `Map` to initialize values only, use the `loadFromMap(Map)` method.
    Parameters:
      `map` - the Map to decorate
      `caseInsensitiveKeys` - when `true` methods taking a key argument will consider the key being passed without consideration for character case.

- ## Method Details

  - ### isCaseInsensitiveKeys

    public boolean isCaseInsensitiveKeys()
    Gets whether keys are case sensitive or not.
    Returns:
      `true` if case insensitive
    Since:
      1.8

  - ### matchKeys

    public Properties matchKeys(TextMatcher keyMatcher)
    Gets a properties subset for keys matched by the key matcher.
    Parameters:
      `keyMatcher` - keys to match
    Returns:
      properties subset or empty properties (never `null`)
    Since:
      2.0.0

  - ### matchValues

    public Properties matchValues(TextMatcher valueMatcher)
    Gets a properties subset for values matched by the value matcher.
    Parameters:
      `valueMatcher` - values to match
    Returns:
      properties subset or empty properties (never `null`)
    Since:
      2.0.0

  - ### match

    public Properties match(PropertyMatcher propertyMatcher)
    Gets a properties subset for keys and values matched by the property matcher. Same as invoking `match(TextMatcher, TextMatcher)`.
    Parameters:
      `propertyMatcher` - property matcher
    Returns:
      properties subset or empty properties (never `null`)
    Since:
      2.0.0

  - ### match

    public Properties match(TextMatcher fieldMatcher, TextMatcher valueMatcher)
    Gets a properties subset for matching keys and values. Same as invoking `match(PropertyMatcher)`.
    Parameters:
      `fieldMatcher` - property matcher
      `valueMatcher` - property value
    Returns:
      properties subset or empty properties (never `null`)
    Since:
      2.0.0

  - ### toString

    public String toString()
    Returns this `Map` in a format compatible with `Properties.store(Writer, String)`. Multi-value properties are merged, joined by the symbol for record separator (U+241E).
    Overrides:
      `toString` in class `ObservableMap<String,List<String>>`
    Returns:
      the properties as string
    Since:
      2.0.0

  - ### storeToProperties

    public void storeToProperties(Writer writer) throws IOException
    Stores this `Map` in a format compatible with `Properties.store(Writer, String)`. Multi-value properties are merged, joined by the symbol for record separator (U+241E).
    Parameters:
      `writer` - an output character stream writer.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### storeToProperties

    public void storeToProperties(Writer writer, String delimiter) throws IOException
    Stores this `Map` in a format compatible with `Properties.store(Writer, String)`. Multi-value properties are merged, joined by the supplied delimiter character. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `writer` - an output character stream writer.
      `delimiter` - string to used as a separator when joining multiple values for the same key.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### storeToProperties

    public void storeToProperties(OutputStream out) throws IOException
    Stores this `Map` in a format compatible with `Properties.store(OutputStream, String)`. Multi-value properties are merged, joined by the symbol for record separator (U+241E).
    Parameters:
      `out` - an output stream.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### storeToProperties

    public void storeToProperties(OutputStream out, String delimiter) throws IOException
    Stores this `Map` in a format compatible with `Properties.store(OutputStream, String)`. Multi-value properties are merged, joined by the supplied delimiter character. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `out` - an output stream.
      `delimiter` - delimiter string to used as a separator when joining multiple values for the same key.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### storeToXML

    public void storeToXML(OutputStream os) throws IOException
    Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`. Multi-value properties are merged, joined by the symbol for record separator (U+241E).
    Parameters:
      `os` - the output stream on which to store the XML document.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### storeToXML

    public void storeToXML(OutputStream os, String delimiter) throws IOException
    Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`. Multi-value properties are merged, joined by the supplied delimiter character. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `os` - the output stream on which to store the XML document.
      `delimiter` - delimiter string to used as a separator when joining multiple values for the same key.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### storeToXML

    public void storeToXML(Writer writer) throws IOException
    Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`. Multi-value properties are merged, joined by the symbol for record separator (U+241E).
    Parameters:
      `writer` - writer on which to store the XML document.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### storeToXML

    public void storeToXML(Writer writer, String delimiter) throws IOException
    Stores this `Map` in a UTF-8 format compatible with `Properties.storeToXML(OutputStream, String)`. Multi-value properties are merged, joined by the supplied delimiter character. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `writer` - the writer on which to store the XML document.
      `delimiter` - delimiter string to used as a separator when joining multiple values for the same key.
    Throws:
      `IOException` - i/o problem

  - ### storeToJSON

    public void storeToJSON(OutputStream os) throws IOException
    Writes this `Map` as JSON to the output stream as UTF-8 in a format suitable for using the `loadFromJSON(InputStream)` method.
    Parameters:
      `os` - the output stream on which to store the properties.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### storeToJSON

    public void storeToJSON(Writer writer) throws IOException
    Writes this `Map` as JSON to the writer in a format suitable for using the `loadFromJSON(Reader)` method.
    Parameters:
      `writer` - the writer on which to store the XML document.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### storeToBean

    public void storeToBean(Object bean)
    Copy all properties in this map to the given bean, mapping keys to setter methods of the same name. Existing bean values for matching accessors are overwritten. Other values are left intact. `null` beans are ignored.
    Parameters:
      `bean` - the object to store properties into
    Since:
      2.0.0

  - ### fromString

    public void fromString(String str)
    Reads a property list (key and element pairs) from the input string. Otherwise, the same considerations as `loadFromProperties(InputStream)` apply.
    Parameters:
      `str` - the string to load

  - ### toProperties

    public Properties toProperties()
    Converts this `Map` to a new Java `Properties` instance. Multi-value properties are merged, joined by the symbol for record separator (U+241E).
    Returns:
      a `java.util.Properties` instance
    Since:
      2.0.0
    See Also:
      - `loadFromMap(Map)`

  - ### loadFromMap

    public void loadFromMap(Map<?,?> map)

    Reads all key/value pairs in the given map, and add them to this `Map`. Keys and values are converted to strings using their toString() method, with exception of values being arrays or collections. In such case, the entry is considered a multi-value one and each value will be separately converted to string. `null` keys are ignored. `null` values are converted to an empty string.

    Changes to this instance won't be reflected in the given `Map`. If you want otherwise, use invoke the constructor with a `Map` argument.

    You can use this method to populate this `Map` from a `Properties`.

    Parameters:
      `map` - the map containing values to load
    Since:
      2.0.0

  - ### loadFromProperties

    public void loadFromProperties(Reader reader) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.load(Reader)`. Multi-value properties are split using the symbol for record separator (U+241E).
    Parameters:
      `reader` - the input character stream.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### loadFromProperties

    public void loadFromProperties(Reader reader, String delimiter) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.load(Reader)`. Multi-value properties are split using the supplied delimiter string. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `reader` - the input character stream.
      `delimiter` - delimiter string to used to parse a multi-value key.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### loadFromProperties

    public void loadFromProperties(InputStream inStream) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`. Multi-value properties are split using the symbol for record separator (U+241E).
    Parameters:
      `inStream` - the input stream.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### loadFromProperties

    public void loadFromProperties(InputStream inStream, String delimiter) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`. Multi-value properties are split using the supplied delimiter string. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `inStream` - the input stream.
      `delimiter` - delimiter string to used to parse a multi value key.
    Throws:
      `IOException` - i/o problem
    Since:
      2.0.0

  - ### loadFromXML

    public void loadFromXML(InputStream in) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.loadFromXML(InputStream)`. Multi-value properties are split using the symbol for record separator (U+241E).
    Parameters:
      `in` - in the input stream from which to read the XML document.
    Throws:
      `IOException` - i/o problem

  - ### loadFromXML

    public void loadFromXML(InputStream in, String delimiter) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`. Multi-value properties are split using the supplied delimiter string. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `in` - in the input stream from which to read the XML document.
      `delimiter` - delimiter string to used to parse a multi-value key.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### loadFromXML

    public void loadFromXML(Reader reader) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.loadFromXML(InputStream)`. Multi-value properties are split using the symbol for record separator (U+241E).
    Parameters:
      `reader` - the reader from which to read the XML document.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### loadFromXML

    public void loadFromXML(Reader reader, String delimiter) throws IOException
    Loads this `Map` from an input of a format compatible with `Properties.load(InputStream)`. Multi-value properties are split using the supplied delimiter string. If the delimiter is `null`, the symbol for record separator (U+241E) is used.
    Parameters:
      `reader` - reader from which to read the XML document.
      `delimiter` - delimiter string to used to parse a multi-value key.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### loadFromJSON

    public void loadFromJSON(InputStream in) throws IOException
    Loads all of the properties from the JSON document input stream (UTF-8) into this instance.
    Parameters:
      `in` - the input stream from which to read the JSON document.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### loadFromJSON

    public void loadFromJSON(Reader reader) throws IOException
    Loads all of the properties from the JSON document reader into this instance.
    Parameters:
      `reader` - the reader from which to read the JSON document.
    Throws:
      `IOException` - i/o problem
    Since:
      1.14.0

  - ### loadFromBean

    public void loadFromBean(Object bean)
    Converts all the bean properties into entries in this instance. `null` beans are ignored.
    Parameters:
      `bean` - the object to load properties from
    Since:
      2.0.0

  - ### get

    public final <T> T get(String key, Class<T> type)
    Gets a single value, converted to the given type.
    Type Parameters:
      `T` - returned value type
    Parameters:
      `key` - the key of the value to get
      `type` - target class of value
    Returns:
      value
    Since:
      2.0.0

  - ### get

    public final <T> T get(String key, Class<T> type, T defaultValue)
    Gets a single value, converted to the given type.
    Type Parameters:
      `T` - returned value type
    Parameters:
      `key` - the key of the value to get
      `type` - target class of value
      `defaultValue` - default value if key has no value.
    Returns:
      value
    Since:
      2.0.0

  - ### getList

    public final <T> List<T> getList(String key, Class<T> type)
    Gets a list of values, with its elements converted to the given type.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `key` - the key of the values to get
      `type` - target class of values
    Returns:
      value list
    Since:
      2.0.0

  - ### getList

    public final <T> List<T> getList(String key, Class<T> type, List<T> defaultValues)
    Gets a list of values, with its elements converted to the given type.
    Type Parameters:
      `T` - returned list type
    Parameters:
      `key` - the key of the values to get
      `type` - target class of values
      `defaultValues` - default values if the key returns `null` or an empty list
    Returns:
      value list
    Since:
      2.0.0

  - ### set

    @SafeVarargs public final <T> void set(String key, T... values)
    Sets one or multiple values as strings replacing existing ones. Setting a single `null` value or an empty array is the same as calling `remove(Object)` with the same key. When setting multiple values, `null` values are converted to empty strings.
    Type Parameters:
      `T` - values type
    Parameters:
      `key` - the key of the value to set
      `values` - the values to set
    Since:
      2.0.0

  - ### add

    @SafeVarargs public final <T> void add(String key, T... values)
    Adds one or multiple string values. Adding a single `null` value has no effect. When adding multiple values, `null` values are converted to blank strings.
    Type Parameters:
      `T` - values type
    Parameters:
      `key` - the key of the value to set
      `values` - the values to set
    Since:
      2.0.0

  - ### setList

    public final <T> void setList(String key, List<T> values)
    Sets one or multiple values as strings replacing existing ones. Setting a single `null` value or an empty array is the same as calling `remove(Object)` with the same key. When setting multiple values, `null` values are converted to empty strings.
    Type Parameters:
      `T` - values type
    Parameters:
      `key` - the key of the value to set
      `values` - the values to set
    Since:
      2.0.0

  - ### addList

    public final <T> void addList(String key, List<T> values)
    Adds one or multiple values as strings. Adding a `null` or empty list has no effect. When adding multiple values, `null` values are converted to empty strings.
    Type Parameters:
      `T` - values type
    Parameters:
      `key` - the key of the value to set
      `values` - the values to set
    Since:
      2.0.0

  - ### getString

    public final String getString(String key)
    Gets value as string.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getString

    public final String getString(String key, String defaultValue)
    Gets value as string.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getStrings

    public final List<String> getStrings(String key)
    Gets values as a list of strings. This method is null-safe. No matches returns an empty list.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getInteger

    public final Integer getInteger(String key)
    Gets value as an integer.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getInteger

    public final Integer getInteger(String key, Integer defaultValue)
    Gets value as an integer.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getIntegers

    public final List<Integer> getIntegers(String key)
    Gets values as a list of integers.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getDouble

    public final Double getDouble(String key)
    Gets value as a double.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getDouble

    public final Double getDouble(String key, Double defaultValue)
    Gets value as a double.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getDoubles

    public final List<Double> getDoubles(String key)
    Gets values as a list of doubles.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getLong

    public final Long getLong(String key)
    Gets value as a long.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getLong

    public final Long getLong(String key, Long defaultValue)
    Gets value as a long.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getLongs

    public final List<Long> getLongs(String key)
    Gets values as a list of longs.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getFloat

    public final Float getFloat(String key)
    Gets value as a float.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getFloat

    public final Float getFloat(String key, Float defaultValue)
    Gets value as a float.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getFloats

    public final List<Float> getFloats(String key)
    Gets values as a list of floats.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getBigDecimal

    public final BigDecimal getBigDecimal(String key)
    Gets value as a BigDecimal.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getBigDecimal

    public final BigDecimal getBigDecimal(String key, BigDecimal defaultValue)
    Gets value as a BigDecimal.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getBigDecimals

    public final List<BigDecimal> getBigDecimals(String key)
    Gets values as a list of BigDecimals.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getLocalDateTime

    public final LocalDateTime getLocalDateTime(String key)
    Gets value as a local date-time. The date must be a valid date-time as defined by `DateTimeFormatter.ISO_LOCAL_DATE_TIME`.
    Parameters:
      `key` - property key
    Returns:
      the value
    Since:
      2.0.0

  - ### getLocalDateTime

    public final LocalDateTime getLocalDateTime(String key, LocalDateTime defaultValue)
    Gets value as a local date-time. The date must be a valid date-time as defined by `DateTimeFormatter.ISO_LOCAL_DATE_TIME`.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value
    Since:
      2.0.0

  - ### getLocalDateTimes

    public final List<LocalDateTime> getLocalDateTimes(String key)
    Gets values as a list of local date-times. Each date must be a valid date-time as defined by `DateTimeFormatter.ISO_LOCAL_DATE_TIME`.
    Parameters:
      `key` - property key
    Returns:
      the values
    Since:
      2.0.0

  - ### getInstant

    public final Instant getInstant(String key)
    Gets value as a UTC date-time `Instant`. The date must be a valid date-time as defined by `DateTimeFormatter.ISO_INSTANT`.
    Parameters:
      `key` - property key
    Returns:
      the value
    Since:
      2.0.0

  - ### getInstant

    public final Instant getInstant(String key, Instant defaultValue)
    Gets value as a UTC date-time `Instant`. The date must be a valid date-time as defined by `DateTimeFormatter.ISO_INSTANT`.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value
    Since:
      2.0.0

  - ### getInstants

    public final List<Instant> getInstants(String key)
    Gets values as a list of UTC date-time `Instant`s. Each date must be a valid date-time as defined by `DateTimeFormatter.ISO_INSTANT`.
    Parameters:
      `key` - property key
    Returns:
      the values
    Since:
      2.0.0

  - ### getDate

    public final Date getDate(String key)
    Gets value as a date.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getDate

    public final Date getDate(String key, Date defaultValue)
    Gets value as a date.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getDates

    public final List<Date> getDates(String key)
    Gets values as a list of dates.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getBoolean

    public final Boolean getBoolean(String key)
    Gets value as a boolean. The underlying string value matching the key must exist and equal "true" (ignoring case) to return `true`. Any other value (including `null`) will return `false`.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getBoolean

    public final Boolean getBoolean(String key, Boolean defaultValue)
    Gets value as a boolean. The underlying string value matching the key must exist and equal "true" (ignoring case) to return `true`. Any other value (including `null`) will return `false`. If there are no entries for the given key, the default value is returned instead.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getBooleans

    public final List<Boolean> getBooleans(String key)
    Gets values as a list of booleans.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getLocale

    public final Locale getLocale(String key)
    Gets value as a locale.
    Parameters:
      `key` - property key
    Returns:
      the value

  - ### getLocale

    public final Locale getLocale(String key, Locale defaultValue)
    Gets value as a locale.
    Parameters:
      `key` - property key
      `defaultValue` - default value to return when original value is null.
    Returns:
      the value

  - ### getLocales

    public final List<Locale> getLocales(String key)
    Gets values as a list of locales.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getFile

    public final File getFile(String key)
    Gets a file, assuming key value is a file system path.
    Parameters:
      `key` - properties key
    Returns:
      a File

  - ### getFile

    public final File getFile(String key, File defaultValue)
    Gets a file, assuming key value is a file system path.
    Parameters:
      `key` - properties key
      `defaultValue` - default file being returned if no file has been defined for the given key in the properties.
    Returns:
      a File

  - ### getFiles

    public final List<File> getFiles(String key)
    Gets values as a list of files.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### getClass

    public final Class<?> getClass(String key)
    Gets a class, assuming key value is a fully qualified class name available in the classloader.
    Parameters:
      `key` - properties key
    Returns:
      initialized class

  - ### getClass

    public final Class<?> getClass(String key, Class<?> defaultValue)
    Gets a class, assuming key value is a fully qualified class name available in the classloader.
    Parameters:
      `key` - properties key
      `defaultValue` - default file being returned if no class has been defined for the given key in the properties.
    Returns:
      initialized class

  - ### getClasses

    public final List<Class> getClasses(String key)
    Gets values as a list of initialized classes.
    Parameters:
      `key` - property key
    Returns:
      the values

  - ### get

    public final List<String> get(Object key)
    Specified by:
      `get` in interface `Map<String,List<String>>`
    Overrides:
      `get` in class `ObservableMap<String,List<String>>`

  - ### remove

    public final List<String> remove(Object key)
    Specified by:
      `remove` in interface `Map<String,List<String>>`
    Overrides:
      `remove` in class `ObservableMap<String,List<String>>`

  - ### put

    public List<String> put(String key, List<String> values)
    Specified by:
      `put` in interface `Map<String,List<String>>`
    Overrides:
      `put` in class `ObservableMap<String,List<String>>`

  - ### putAll

    public void putAll(Map<? extends String,? extends List<String>> m)
    Specified by:
      `putAll` in interface `Map<String,List<String>>`
    Overrides:
      `putAll` in class `ObservableMap<String,List<String>>`

  - ### valueList

    public List<String> valueList()
    Returns all property values merged into a single list. Duplicate values are kept.
    Returns:
      value list (never `null`)
    Since:
      2.0.0

  - ### equals

    public boolean equals(Object other)
    Specified by:
      `equals` in interface `Map<String,List<String>>`
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Specified by:
      `hashCode` in interface `Map<String,List<String>>`
    Overrides:
      `hashCode` in class `Object`