Settings (microBean™ Settings 0.0.4 API)

java.lang.Object
- org.microbean.settings.Source
- - org.microbean.settings.Settings

```
@Typed(value=Settings.class)
public class Settings
extends Source
```
A provider of named setting values sourced from any number of sources.
Please see the overview for necessary context.

Class Organization

The bulk of the methods that belong to the Settings class can be placed into two categories:
1. Value acquisition methods. These methods, such as the canonical get(String, Set, Converter, BiFunction) method and its convenience forms, such as, simply, get(String), acquire values from Sources, resolve ambiguities, perform type conversion and so on.
2. Configuration methods. These methods, such as the canonical configure(Object, Iterable, String, Set) method and its convenience forms, such as, simply, configure(Object), fully configure Java Beans by using the value acquisition methods above in conjunction with PropertyDescriptor features from the Java Beans specification.
Author:

Laird Nelson

Thread Safety:

Instances of this class are safe for concurrent use by multiple threads.

Field Summary

Fields
Modifier and Type	Field and Description
`static BiFunction<? super String,? super Set<? extends Annotation>,? extends String>`	`EMPTY` A convenient `BiFunction` suitable for use as a default value function normally provided to the `get(String, Set, Type, BiFunction)` method and its ilk that returns an empty `String` when invoked.
`static BiFunction<? super String,? super Set<? extends Annotation>,? extends String>`	`NULL` A convenient `BiFunction` suitable for use as a default value function normally provided to the `get(String, Set, Type, BiFunction)` method and its ilk that returns `null` when invoked.

Constructor Summary

Constructors
Constructor and Description
`Settings()` Creates a new `Settings`.
`Settings(BiFunction<? super String,? super Set<Annotation>,? extends Set<? extends Source>> sourcesFunction, ConverterProvider converterProvider, Iterable<? extends Arbiter> arbiters)` Creates a new `Settings`.
`Settings(Set<Annotation> qualifiers, BiFunction<? super String,? super Set<Annotation>,? extends Set<? extends Source>> sourcesFunction, ConverterProvider converterProvider, Iterable<? extends Arbiter> arbiters)` Creates a new `Settings`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected Value`	`arbitrate(Set<? extends Source> sources, String name, Set<Annotation> qualifiers, Collection<? extends Value> values)` Performs value arbitration on a `Collection` of `Value`s that this `Settings` instance determined were indistinguishable during value acquisition, and returns the `Value` to be used instead (normally drawn from the `Collection` according to some heuristic).
`void`	`configure(Object object)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, BeanInfo beanInfo)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, BeanInfo beanInfo, Set<Annotation> qualifiers)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, BeanInfo beanInfo, String prefix)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, BeanInfo beanInfo, String prefix, Set<Annotation> qualifiers)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, Iterable<? extends PropertyDescriptor> propertyDescriptors)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, Iterable<? extends PropertyDescriptor> propertyDescriptors, String prefix)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, Iterable<? extends PropertyDescriptor> propertyDescriptors, String prefix, Set<Annotation> qualifiers)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, Set<Annotation> qualifiers)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, String prefix)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`void`	`configure(Object object, String prefix, Set<Annotation> qualifiers)` Configures the supplied Java Bean by acquiring setting values named after the supplied `PropertyDescriptor`s and using their affiliated write methods to set the corresponding values.
`String`	`get(String name)` Returns a suitable `String` value for a setting named by the supplied `name`.
`String`	`get(String name, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable `String` value for a setting named by the supplied `name` and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Class<T> type)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `Class`.
`<T> T`	`get(String name, Class<T> type, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `Class`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Class<T> type, String defaultValue)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `Class`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Converter<? extends T> converter)` Returns a suitable value for a setting named by the supplied `name` as converted by the supplied `Converter`.
`<T> T`	`get(String name, Converter<? extends T> converter, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` as converted by the supplied `Converter` and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`String`	`get(String name, Set<Annotation> qualifiers)` Returns a suitable `String` value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`.
`String`	`get(String name, Set<Annotation> qualifiers, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable `String` value for a setting named by the supplied `name` and qualified with the supplied `qualifiers` and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Set<Annotation> qualifiers, Class<T> type, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the `Converter` located using the supplied `Class`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Set<Annotation> qualifiers, Class<T> type, String defaultValue)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the `Converter` located using the supplied `Class`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Set<Annotation> qualifiers, Converter<? extends T> converter)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the supplied `Converter`.
`<T> T`	`get(String name, Set<Annotation> qualifiers, Converter<? extends T> converter, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the supplied `Converter` and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Set<Annotation> qualifiers, Converter<? extends T> converter, String defaultValue)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the supplied `Converter` and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`String`	`get(String name, Set<Annotation> qualifiers, String defaultValue)` Returns a suitable `String` value for a setting named by the supplied `name` and qualified with the supplied `qualifiers` and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`Object`	`get(String name, Set<Annotation> qualifiers, Type type)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the `Converter` located using the supplied `Type`.
`Object`	`get(String name, Set<Annotation> qualifiers, Type type, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the `Converter` located using the supplied `Type`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, Set<Annotation> qualifiers, TypeLiteral<T> typeLiteral, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` and qualified with the supplied `qualifiers`, as converted by the `Converter` located using the supplied `TypeLiteral`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`String`	`get(String name, String defaultValue)` Returns a suitable `String` value for a setting named by the supplied `name` and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`Object`	`get(String name, Type type)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `Type`.
`Object`	`get(String name, Type type, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `Type`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, TypeLiteral<T> typeLiteral)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `TypeLiteral`.
`<T> T`	`get(String name, TypeLiteral<T> typeLiteral, BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `TypeLiteral`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`<T> T`	`get(String name, TypeLiteral<T> typeLiteral, String defaultValue)` Returns a suitable value for a setting named by the supplied `name` as converted by the `Converter` located using the supplied `TypeLiteral`, and with default value semantics implemented by the optional supplied `defaultValueFunction`.
`protected Value`	`getValue(Source source, String name, Set<Annotation> qualifiers)` Given a `Source`, a name of a setting and a (possibly `null`) `Set` of qualifying `Annotation`s, returns a `Value` for the supplied `name` originating from the supplied `Source`.
`@Experimental Value`	`getValue(String name, Set<Annotation> qualifiers)` Implements the `Source.getValue(String, Set)` method so that this `Settings` can be conveniently used as a `Source` from a higher-order `Settings`.
`protected void`	`handleMalformedValues(String name, Set<Annotation> qualifiers, Collection<? extends Value> badValues)` Processes a `Collection` of `Value` instances that were determined to be malformed in some way during the execution of a `get(String, Set, Converter, BiFunction)` operation.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NULL
```
public static final BiFunction<? super String,? super Set<? extends Annotation>,? extends String> NULL
```
    A convenient BiFunction suitable for use as a default value function normally provided to the get(String, Set, Type, BiFunction) method and its ilk that returns null when invoked.
  - EMPTY
```
public static final BiFunction<? super String,? super Set<? extends Annotation>,? extends String> EMPTY
```
    A convenient BiFunction suitable for use as a default value function normally provided to the get(String, Set, Type, BiFunction) method and its ilk that returns an empty String when invoked.
- Constructor Detail
  - Settings
```
public Settings()
```
    Creates a new Settings.
    The created instance will use an empty Set of qualifiers by default.
    
    The created instance will source its values from System properties and environment variables, in that order.
    
    The created instance will use a new Converters instance as its underlying source of Converter instances.
    
    The created instance will use a single SourceOrderArbiter as its mechanism for value arbitration.
    
    See Also:
    
    Settings(Set, BiFunction, ConverterProvider, Iterable)
  - Settings
```
public Settings(BiFunction<? super String,? super Set<Annotation>,? extends Set<? extends Source>> sourcesFunction,
                ConverterProvider converterProvider,
                Iterable<? extends Arbiter> arbiters)
```
    Creates a new Settings.
    
    Parameters:
    
    sourcesFunction - a BiFunction that accepts a setting name and a Set of qualifier annotations and returns a Set of Sources appropriate for the request represented by its inputs; may be null; may return null; if non-null and this new Settings will be used concurrently by multiple threads, then this parameter value must be safe for concurrent use by multiple threads; any Set returned by this BiFunction will be iterated over by this Settings instance without any synchronization
    
    converterProvider - a ConverterProvider; must not be null; if this new Settings will be used concurrently by multiple threads, then this parameter value must be safe for concurrent use by multiple threads
    
    arbiters - an Iterable of Arbiters; may be null; if this new Settings will be used concurrently by multiple threads, then this parameter value must be safe for concurrent use by multiple threads and Iterators produced by its iterator() method must also be safe for concurrent iteration by multiple threads
    
    Throws:
    
    NullPointerException - if converterProvider is null
    
    See Also:
    
    Settings(Set, BiFunction, ConverterProvider, Iterable)
  - Settings
```
public Settings(Set<Annotation> qualifiers,
                BiFunction<? super String,? super Set<Annotation>,? extends Set<? extends Source>> sourcesFunction,
                ConverterProvider converterProvider,
                Iterable<? extends Arbiter> arbiters)
```
    Creates a new Settings.
    
    Parameters:
    
    qualifiers - a Set of annotations that can be used to further qualify the selection of appropriate values; may be null; will be iterated over with no synchronization or locking and shallowly copied by this constructor
    
    sourcesFunction - a BiFunction that accepts a setting name and a Set of qualifier annotations and returns a Set of Sources appropriate for the request represented by its inputs; may be null; may return null; if non-null and this new Settings will be used concurrently by multiple threads, then this parameter value must be safe for concurrent use by multiple threads; any Set returned by this BiFunction will be iterated over by this Settings instance without any synchronization
    
    converterProvider - a ConverterProvider; must not be null; if this new Settings will be used concurrently by multiple threads, then this parameter value must be safe for concurrent use by multiple threads
    
    arbiters - an Iterable of Arbiters; may be null; if this new Settings will be used concurrently by multiple threads, then this parameter value must be safe for concurrent use by multiple threads and Iterators produced by its iterator() method must also be safe for concurrent iteration by multiple threads
    
    Throws:
    
    NullPointerException - if converterProvider is null
- Method Detail
  - get
```
public final String get(String name)
```
    Returns a suitable String value for a setting named by the supplied name.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if name is null
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final String get(String name,
                        String defaultValue)
```
    Returns a suitable String value for a setting named by the supplied name and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    defaultValue - a String representation of the default value to be used in case setting value acquisition does not yield a value; may be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if name is null
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final String get(String name,
                        BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable String value for a setting named by the supplied name and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if name is null
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final String get(String name,
                        Set<Annotation> qualifiers)
```
    Returns a suitable String value for a setting named by the supplied name and qualified with the supplied qualifiers.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if name is null
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final String get(String name,
                        Set<Annotation> qualifiers,
                        String defaultValue)
```
    Returns a suitable String value for a setting named by the supplied name and qualified with the supplied qualifiers and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    defaultValue - a String representation of the default value to be used in case setting value acquisition does not yield a value; may be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if name is null
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final String get(String name,
                        Set<Annotation> qualifiers,
                        BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable String value for a setting named by the supplied name and qualified with the supplied qualifiers and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if name is null
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Class<T> type)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied Class.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    type - a Class used to locate an appropriate Converter; must not be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or class is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Class<T> type,
                       String defaultValue)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied Class, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    type - a Class used to locate an appropriate Converter; must not be null
    
    defaultValue - a String representation of the default value to be used in case setting value acquisition does not yield a value; may be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or class is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Class<T> type,
                       BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied Class, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    type - a Class used to locate an appropriate Converter; must not be null
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or class is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Set<Annotation> qualifiers,
                       Class<T> type,
                       String defaultValue)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the Converter located using the supplied Class, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    type - a Class used to locate an appropriate Converter; must not be null
    
    defaultValue - a String representation of the default value to be used in case setting value acquisition does not yield a value; may be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or type is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Set<Annotation> qualifiers,
                       Class<T> type,
                       BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the Converter located using the supplied Class, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    type - a Class used to locate an appropriate Converter; must not be null
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or type is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       TypeLiteral<T> typeLiteral)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied TypeLiteral.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    typeLiteral - a TypeLiteral used to locate an appropriate Converter; must not be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or typeLiteral is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       TypeLiteral<T> typeLiteral,
                       String defaultValue)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied TypeLiteral, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    typeLiteral - a TypeLiteral used to locate an appropriate Converter; must not be null
    
    defaultValue - a String representation of the default value to be used in case setting value acquisition does not yield a value; may be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or typeLiteral is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       TypeLiteral<T> typeLiteral,
                       BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied TypeLiteral, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    typeLiteral - a TypeLiteral used to locate an appropriate Converter; must not be null
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or typeLiteral is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Set<Annotation> qualifiers,
                       TypeLiteral<T> typeLiteral,
                       BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the Converter located using the supplied TypeLiteral, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    typeLiteral - a TypeLiteral used to locate an appropriate Converter; must not be null
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or typeLiteral is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final Object get(String name,
                        Type type)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied Type.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    type - a Type used to locate an appropriate Converter; must not be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or type is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final Object get(String name,
                        Set<Annotation> qualifiers,
                        Type type)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the Converter located using the supplied Type.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    type - a Type used to locate an appropriate Converter; must not be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or type is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final Object get(String name,
                        Type type,
                        BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name as converted by the Converter located using the supplied Type, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    type - a Type used to locate an appropriate Converter; must not be null
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or type is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final Object get(String name,
                        Set<Annotation> qualifiers,
                        Type type,
                        BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the Converter located using the supplied Type, and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    type - a Type used to locate an appropriate Converter; must not be null
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or type is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Converter<? extends T> converter)
```
    Returns a suitable value for a setting named by the supplied name as converted by the supplied Converter.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    converter - a Converter used to convert a String value into a setting value of the appropriate type; must not be null; must either be safe for concurrent use by multiple threads or created specially for this method invocation or supplied in a context where it is known that only one thread is executing at a time
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or converter is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Set<Annotation> qualifiers,
                       Converter<? extends T> converter)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the supplied Converter.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    converter - a Converter used to convert a String value into a setting value of the appropriate type; must not be null; must either be safe for concurrent use by multiple threads or created specially for this method invocation or supplied in a context where it is known that only one thread is executing at a time
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or converter is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Converter<? extends T> converter,
                       BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name as converted by the supplied Converter and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    converter - a Converter used to convert a String value into a setting value of the appropriate type; must not be null; must either be safe for concurrent use by multiple threads or created specially for this method invocation or supplied in a context where it is known that only one thread is executing at a time
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or converter is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    See Also:
    
    get(String, Set, Converter, BiFunction)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Set<Annotation> qualifiers,
                       Converter<? extends T> converter,
                       String defaultValue)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the supplied Converter and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    converter - a Converter used to convert a String value into a setting value of the appropriate type; must not be null; must either be safe for concurrent use by multiple threads or created specially for this method invocation or supplied in a context where it is known that only one thread is executing at a time
    
    defaultValue - a String representation of the default value to be used in case setting value acquisition does not yield a value; may be null
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or converter is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - get
```
public final <T> T get(String name,
                       Set<Annotation> qualifiers,
                       Converter<? extends T> converter,
                       BiFunction<? super String,? super Set<? extends Annotation>,? extends String> defaultValueFunction)
```
    Returns a suitable value for a setting named by the supplied name and qualified with the supplied qualifiers, as converted by the supplied Converter and with default value semantics implemented by the optional supplied defaultValueFunction.
    
    Type Parameters:
    
    T - the type to which any value should be converted
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    converter - a Converter used to convert a String value into a setting value of the appropriate type; must not be null; must either be safe for concurrent use by multiple threads or created specially for this method invocation or supplied in a context where it is known that only one thread is executing at a time
    
    defaultValueFunction - a BiFunction accepting a setting name and a Set of qualifier Annotations that returns a default String-typed value when a value could not sourced; may be null in which case if no value can be sourced a NoSuchElementException will be thrown; may return null; must be safe for concurrent use by mulitple threads; must not call any of this Settings instance's methods or undefined behavior will result
    
    Returns:
    
    a suitable value (possibly null)
    
    Throws:
    
    NullPointerException - if either name or converter is null
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value)
    
    ConversionException - if conversion could not occur for any reason other than bad inputs
    
    NoSuchElementException - if defaultValueFunction was null and no value could be sourced
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value
    
    ArbitrationException - if there was a problem performing value arbitration
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException
    
    ELException - if there was an error related to expression language parsing or evaluation
    
    ConcurrentModificationException - if the BiFunction or Iterable supplied at construction time throws one
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - getValue
```
@Experimental
public final @Experimental Value getValue(String name,
                                                        Set<Annotation> qualifiers)
```
    Implements the Source.getValue(String, Set) method so that this Settings can be conveniently used as a Source from a higher-order Settings.
    End users should never need to call this method directly.
    
    Specified by:
    
    getValue in class Source
    
    Parameters:
    
    name - the name of the setting for which a value is to be returned; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of the value to be returned; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    Returns:
    
    a suitable Value, or null if no Value could be created or acquired
    
    Throws:
    
    NullPointerException - if name is null
    
    ValueAcquisitionException - if there was a procedural problem acquiring a Value
    
    See Also:
    
    Source.getValue(String, Set)
    
    Idempotency:
    
    This method may not be idempotent. That is, two invocations supplied with the same name and qualifiers parameter values may or may not return Values that are identical, equal or neither.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object)
                     throws IntrospectionException,
                            ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    IntrospectionException - if introspection of the supplied object fails
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            String prefix)
                     throws IntrospectionException,
                            ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    prefix - a String that will be prepended to each PropertyDescriptor name before using the result as the name of a setting for which a value will be acquired; may be null
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    IntrospectionException - if introspection of the supplied object fails
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            Set<Annotation> qualifiers)
                     throws IntrospectionException,
                            ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of values; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    IntrospectionException - if introspection of the supplied object fails
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            String prefix,
                            Set<Annotation> qualifiers)
                     throws IntrospectionException,
                            ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    prefix - a String that will be prepended to each PropertyDescriptor name before using the result as the name of a setting for which a value will be acquired; may be null
    
    qualifiers - a Set of Annotations to further qualify the selection of values; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    IntrospectionException - if introspection of the supplied object fails
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            BeanInfo beanInfo)
                     throws ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    beanInfo - a BeanInfo providing access to PropertyDescriptors; must not be null
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            BeanInfo beanInfo,
                            String prefix)
                     throws ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    beanInfo - a BeanInfo providing access to PropertyDescriptors; must not be null
    
    prefix - a String that will be prepended to each PropertyDescriptor name before using the result as the name of a setting for which a value will be acquired; may be null
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            BeanInfo beanInfo,
                            Set<Annotation> qualifiers)
                     throws ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    beanInfo - a BeanInfo providing access to PropertyDescriptors; must not be null
    
    qualifiers - a Set of Annotations to further qualify the selection of values; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            BeanInfo beanInfo,
                            String prefix,
                            Set<Annotation> qualifiers)
                     throws ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    beanInfo - a BeanInfo providing access to PropertyDescriptors; must not be null
    
    prefix - a String that will be prepended to each PropertyDescriptor name before using the result as the name of a setting for which a value will be acquired; may be null
    
    qualifiers - a Set of Annotations to further qualify the selection of values; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    Throws:
    
    NullPointerException - if either object or beanInfo is null
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            Iterable<? extends PropertyDescriptor> propertyDescriptors)
                     throws ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    propertyDescriptors - an Iterable of PropertyDescriptors; must not be null
    
    Throws:
    
    NullPointerException - if either object or propertyDescriptors is null
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            Iterable<? extends PropertyDescriptor> propertyDescriptors,
                            String prefix)
                     throws ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    This implementation calls the configure(Object, Iterable, String, Set) method with sensible defaults.
    
    Parameters:
    
    object - the Object to configure; must not be null
    
    propertyDescriptors - an Iterable of PropertyDescriptors; must not be null
    
    prefix - a String that will be prepended to each PropertyDescriptor name before using the result as the name of a setting for which a value will be acquired; may be null
    
    Throws:
    
    NullPointerException - if either object or propertyDescriptors is null
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    See Also:
    
    configure(Object, Iterable, String, Set)
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - configure
```
public final void configure(Object object,
                            Iterable<? extends PropertyDescriptor> propertyDescriptors,
                            String prefix,
                            Set<Annotation> qualifiers)
                     throws ReflectiveOperationException
```
    Configures the supplied Java Bean by acquiring setting values named after the supplied PropertyDescriptors and using their affiliated write methods to set the corresponding values.
    For each PropertyDescriptor reachable from the supplied Iterable:
    - A setting name is synthesized by concatenating the value of the supplied prefix (or the empty string if the supplied prefix is null) and the return value of the FeatureDescriptor.getName() method.
    - The PropertyDescriptor is interrogated for a write method. If there is no write method, processing stops.
    - A Type is acquired for the (writable) property in question by first seeing if it has a propertyType attribute set to a Type or a TypeLiteral (very uncommon) and then by using the return value of its PropertyDescriptor.getPropertyType() method.
    - A Converter is acquired by first synthesizing one wrapped around the return value of the PropertyDescriptor.createPropertyEditor(Object) method, if that method returns a non-null value, and then by retrieving one normally otherwise.
    - A default value is sought as the String-typed value of the PropertyDescriptor's defaultValue attribute. If the value of that attribute is null or not a String (very common) then no default value will be used.
    - The get(String, Set, Converter, BiFunction) method is called. If the method throws a NoSuchElementException, then processing stops.
    - The return value from the previous step is passed to an invocation of the PropertyDescriptor's write method on the supplied object.
    The net effect is that only writable Java Bean properties for which there is a setting value will be set to that value.
    Parameters:
    
    object - the Object to configure; must not be null
    
    propertyDescriptors - an Iterable of PropertyDescriptors; must not be null
    
    prefix - a String that will be prepended to each PropertyDescriptor name before using the result as the name of a setting for which a value will be acquired; may be null
    
    qualifiers - a Set of Annotations to further qualify the selection of values; may be null; if non-null then this parameter value must be safe for concurrent iteration by multiple threads
    
    Throws:
    
    NullPointerException - if either object or propertyDescriptors is null
    
    ReflectiveOperationException - if there was a problem invoking a write method; the supplied Object may, in this case, be left in an inconsistent state
    
    IllegalArgumentException - if conversion could not occur for any reason; see Converter.convert(Value); the supplied Object may, in this case, be left in an inconsistent state
    
    ConversionException - if conversion could not occur for any reason other than bad inputs; the supplied Object may, in this case, be left in an inconsistent state
    
    ValueAcquisitionException - if there was a procedural problem acquiring a value; the supplied Object may, in this case, be left in an inconsistent state
    
    ArbitrationException - if there was a problem performing value arbitration; the supplied Object may, in this case, be left in an inconsistent state
    
    AmbiguousValuesException - if arbitration completed but could not resolve an ambiguity between potential return values; the supplied Object may, in this case, be left in an inconsistent state
    
    MalformedValuesException - if the handleMalformedValues(String, Set, Collection) method was overridden and the override throws a MalformedValuesException; the supplied Object may, in this case, be left in an inconsistent state
    
    ELException - if there was an error related to expression language parsing or evaluation; the supplied Object may, in this case, be left in an inconsistent state
    
    Idempotency:
    
    No guarantees are made with respect to the idempotency of this method.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - arbitrate
```
protected Value arbitrate(Set<? extends Source> sources,
                          String name,
                          Set<Annotation> qualifiers,
                          Collection<? extends Value> values)
```
    Performs value arbitration on a Collection of Values that this Settings instance determined were indistinguishable during value acquisition, and returns the Value to be used instead (normally drawn from the Collection according to some heuristic).
    This implementation iterates over the Arbiter instances supplied at construction time and asks each in turn to perform value arbitration. The first non-null value from an Arbiter is used as the return value from this method; otherwise null is returned.
    
    Parameters:
    
    sources - the Set of Sources in effect during the current value acquisition operation; must not be null; must be unmodifiable; must be safe for concurrent read-only access by multiple threads
    
    name - the name of the setting value being sought; must not be null
    
    qualifiers - the Set of qualifier Annotations in effect during the current value acquisition operation; must not be null; must be unmodifiable; must be safe for concurrent read-only access by multiple threads
    
    values - the Collection of Values acquired during the current value acquisition operation that were deemed to be indistinguishable; must not be null; must be unmodifiable; must be safe for concurrent read-only access by multiple threads
    
    Returns:
    
    the result of value arbitration as a single Value, or null if arbitration could not select a single Value
    
    See Also:
    
    Arbiter, Arbiter.arbitrate(Set, String, Set, Collection)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method.
    
    Nullability:
    
    This method may return null.
    
    Thread Safety:
    
    This method is safe for concurrent use by multiple threads.
  - getValue
```
protected Value getValue(Source source,
                         String name,
                         Set<Annotation> qualifiers)
```
    Given a Source, a name of a setting and a (possibly null) Set of qualifying Annotations, returns a Value for the supplied name originating from the supplied Source.
    The default implementation of this method calls the Source.getValue(String, Set) method on the supplied Source, passing the remaining arguments to it, and returns its result.
    
    Parameters:
    
    source - the Source of the Value to be returned; must not be null
    
    name - the name of the setting for which a Value is to be returned; must not be null
    
    qualifiers - an unmodifiable Set of qualifying Annotations; may be null
    
    Returns:
    
    an appropriate Value, or null
    
    Throws:
    
    NullPointerException - if source or name is null
    
    UnsupportedOperationException - if an override of this method attempts to modify the qualifiers parameter
    
    ValueAcquisitionException - if there was an exceptional problem acquiring a Value, but not in the relatively common case that an appropriate Value could not be located
    
    See Also:
    
    Source.getValue(String, Set)
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Nullability:
    
    This method and its overrides are permitted to return null.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.
  - handleMalformedValues
```
protected void handleMalformedValues(String name,
                                     Set<Annotation> qualifiers,
                                     Collection<? extends Value> badValues)
```
    Processes a Collection of Value instances that were determined to be malformed in some way during the execution of a get(String, Set, Converter, BiFunction) operation.
    The default implementation of this method does nothing. Overrides may consider throwing a MalformedValuesException instead.
    
    Overrides of this method should not call any of this Settings instance's other methods (especially get(String, Set, Converter, BiFunction)) as undefined behavior or infinite loops may result.
    
    Value instances in the supplied Collection of Value instances will be discarded after this method completes and are for informational purposes only.
    
    Parameters:
    
    name - the name of the configuration setting for which a Value is being retrieved by an invocation of the get(String, Set, Converter, BiFunction) method; must not be null
    
    qualifiers - an unmodifiable Set of qualifier Annotations qualifying the value retrieval operation; may be null
    
    badValues - a non-null unmodifiable Collection of Values that have been determined to be malformed in some way
    
    Throws:
    
    NullPointerException - if name or badValues is null
    
    UnsupportedOperationException - if an override attempts to modify either of the qualifiers or the badValues parameters
    
    MalformedValuesException - if processing should abort
    
    See Also:
    
    get(String, Set, Converter, BiFunction), Value
    
    Idempotency:
    
    No guarantees of any kind are made with respect to the idempotency of this method or its overrides.
    
    Thread Safety:
    
    This method is and its overrides must be safe for concurrent use by multiple threads.

Class Settings

Class Organization

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NULL

EMPTY

Constructor Detail

Settings

Settings

Settings

Method Detail

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

get

getValue

configure

configure

configure

configure

configure

configure

configure

configure

configure

configure

configure

arbitrate

getValue

handleMalformedValues