fish.payara.nucleus.microprofile.config.spi

Interface ConfigValueResolver

public interface ConfigValueResolver

This is an abstraction to resolve Config values using a fluent API that is used when the basic Config.getValue(String, Class) does not suffice or the user wants to make sure a value is returned without an exception. The method names are chosen for good readability when used as a fluent API.

This API is designed so reliably result in a return value. This means by default it will not throw exceptions for missing properties or failed conversion but instead return a default value that callers have to provide. Alternatively to providing a default value a value can be resolved as Optional. If a caller wants exceptions to occur Config.getValue(String, Class) can be used instead.

Values can be resolved as List or Set. By default these return empty lists or sets in case of missing property or failed conversion.

Should exceptions be thrown for either missing properties or failed conversion the default of not throwing exception and using default values can be overridden using throwOnMissingProperty() and throwOnFailedConversion().

Usually conversion relies on registered Converters. Ad-hoc conversion can be done using asConvertedBy(Function, Object). Values resolved as String are not converted. Values resolved as String[] are only split but elements are not converted.

Typed defaults are provided with one of the as-methods. Raw property string defaults can be provided using withDefault(String). As the API can not capture if such a raw default has been provided it still requires to provide a typed default or use Optional to ensure resolution will return a value. If a raw String is provided it takes precedence over a typed default. Should conversion of a raw default fail the typed default is used or in case of Optional the property is considered not present.

The only way as-methods might return a null reference is by using null as typed default. In such case it is considered the intention of the caller and therefore not problematic.

Author:

Jan Bernitt

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ConfigValueResolver.ElementPolicy What to do when collection element conversion fails.

Method Summary

Modifier and Type	Method and Description
<T> Optional<T>	as(Class<T> type) Resolves the property as a simple or array type wrapped in an Optional.
<T> T	as(Class<T> type, T defaultValue) Resolves the property as a simple or array type.
<T> T	asConvertedBy(Function<String,T> converter, T defaultValue) Resolves the property as converted by the provided converter Function.
<E> List<E>	asList(Class<E> elementType) Resolves the property as List.
<E> List<E>	asList(Class<E> elementType, List<E> defaultValue) Resolves the property as List.
<E> Set<E>	asSet(Class<E> elementType) Resolves the property as Set.
<E> Set<E>	asSet(Class<E> elementType, Set<E> defaultValue) Resolves the property as Set.
<E> Supplier<E>	asSupplier(Class<E> elementType) Resolves the property as Supplier.
default ConfigValueResolver	throwOnFailedConversion() Disables the default behaviour of not throwing exceptions and instead returning typed default values for case of failed conversion or missing converter for the target type.
ConfigValueResolver	throwOnFailedConversion(boolean throwOnFailedConversion) Disables or enables throwing exceptions for failed conversions.
default ConfigValueResolver	throwOnMissingProperty() Disables the default behaviour of not throwing exceptions and instead returning default values for case of missing or empty raw value.
ConfigValueResolver	throwOnMissingProperty(boolean throwOnMissingProperty) Disables or enables throwing exceptions for missing properties.
ConfigValueResolver	withDefault(String value) Provides a raw property value default value.
ConfigValueResolver	withPolicy(ConfigValueResolver.ElementPolicy policy) Change the ConfigValueResolver.ElementPolicy setting.
ConfigValueResolver	withTrimming(boolean trim) Change the source level value trimming setting.
ConfigValueResolver	withTTL(long ttl) Use a custom cache TTL for resolution.

Method Detail

withTTL

ConfigValueResolver withTTL(long ttl)

Use a custom cache TTL for resolution. A cache entry is linked to its TTL. Use a different TTL uses a different cache entry which has the effect of using the current value for the resolved value if that TTL had not been used before. This usually behaves as intended when a call site uses a relatively stable or hard coded TTL. Call sites should never use a TTL value that is naturally varying like a value based on the current time.

Parameters:

ttl - Cache time to live in milliseconds, 0 to not use caching, negative to use default TTL

Returns:

This resolver for fluent API usage

withDefault

ConfigValueResolver withDefault(String value)

Provides a raw property value default value.

The raw default is considered to be on the source level and therefore takes precedence over typed defaults provided to any of the as-methods. Should raw default be empty of fail to convert to the target type the typed default is used.

Parameters:

value - raw default value, not null

Returns:

This resolver for fluent API usage

withTrimming

ConfigValueResolver withTrimming(boolean trim)

Change the source level value trimming setting.

Parameters:

trim - true to apply trim on source level values (default) or false to disabling applying String.trim() to the source level value

Returns:

This resolver for fluent API usage

withPolicy

ConfigValueResolver withPolicy(ConfigValueResolver.ElementPolicy policy)

Change the ConfigValueResolver.ElementPolicy setting. This affects array types as well as List and Set results.

Parameters:

policy - the policy to use when conversion of collection elements fails

Returns:

This resolver for fluent API usage

throwOnMissingProperty

default ConfigValueResolver throwOnMissingProperty()

Disables the default behaviour of not throwing exceptions and instead returning default values for case of missing or empty raw value. If used in combination with #acceptEmpty() empty raw values will not throw an exception, otherwise they do.

Returns:

This resolver for fluent API usage

throwOnMissingProperty

ConfigValueResolver throwOnMissingProperty(boolean throwOnMissingProperty)

Disables or enables throwing exceptions for missing properties.

Parameters:

throwOnMissingProperty - true to have exceptions thrown when property does not exist, false to use default values

Returns:

This resolver for fluent API usage

See Also:

throwOnMissingProperty()

throwOnFailedConversion

default ConfigValueResolver throwOnFailedConversion()

Disables the default behaviour of not throwing exceptions and instead returning typed default values for case of failed conversion or missing converter for the target type. If a raw value default is provided using withDefault(String) conversion of this default is tried in case conversion of source value failed. With a raw default a exception is only thrown if conversion of raw default value failed as well and throwOnFailedConversion() was used.

Returns:

This resolver for fluent API usage

throwOnFailedConversion

ConfigValueResolver throwOnFailedConversion(boolean throwOnFailedConversion)

Disables or enables throwing exceptions for failed conversions.

Parameters:

throwOnFailedConversion - true to have exceptions thrown then property conversion fails, false to use defaults

Returns:

This resolver for fluent API usage

See Also:

throwOnFailedConversion()

as

<T> T as(Class<T> type,
         T defaultValue)

Resolves the property as a simple or array type.

If the property is missing, defined empty, the required converter is missing or conversion fails the provided default value is returned.

Parameters:

type - target type of the conversion, not null

defaultValue - any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested using throwOnMissingProperty() or throwOnFailedConversion().

Returns:

the resolved and converted property value or the default value

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()

as

<T> Optional<T> as(Class<T> type)

Resolves the property as a simple or array type wrapped in an Optional.

If the property is missing, defined empty, the required converter is missing or conversion fails Optional.empty() is returned.

Parameters:

type - target type of the conversion, not null

Returns:

the resolved and converted property value as present or empty Optional

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()

asConvertedBy

<T> T asConvertedBy(Function<String,T> converter,
                    T defaultValue)

Resolves the property as converted by the provided converter Function.

If the property is missing, defined empty or the conversion fails the provided default value is returned.

This is meant for ad-hoc conversions using lambda expressions as converter to circumvent the need to register a special Converter for single case use or to allow using different converter functions for same target type at multiple usages.

If this method is used in connection with #acceptEmpty() the empty String might be passed to the provided converter function, otherwise the empty string will be considered missing.

Parameters:

type - target type of the conversion, not null

defaultValue - any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested using throwOnMissingProperty() or throwOnFailedConversion().

Returns:

the resolved and converted property value or the default value

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()

asList

<E> List<E> asList(Class<E> elementType)

Resolves the property as List. Raw value is split into elements as defined by Config for array types.

If the property is missing, defined empty, the required element type converter is missing or conversion fails an empty list is returned. The returned list must not be considered modifiable.

This is equivalent to asList(Class, List) with an empty list as default value.

This is equivalent to as(Class, Object) with 1-dimensional array type of the provided element type as type where the returned array is later wrapped in a List while also honouring defaults.

Parameters:

elementType - type of the list elements, not null

Returns:

the resolved and converted property value or an empty list

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()

asSupplier

<E> Supplier<E> asSupplier(Class<E> elementType)

Resolves the property as Supplier. Raw value will be fetched anew each time the supplier is called.

Parameters:

elementType - type of the element, not null

Returns:

a supplier that resolves the converted property value. Will not be null

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()

asList

<E> List<E> asList(Class<E> elementType,
                   List<E> defaultValue)

Resolves the property as List. Raw value is split into elements as defined by Config for array types.

If the property is missing, defined empty, the required element type converter is missing or conversion fails the provided default value is returned. The returned list must not be considered modifiable.

This is equivalent to as(Class, Object) with 1-dimensional array type of the provided element type as type where the returned array is later wrapped in a List while also honouring defaults.

Parameters:

elementType - type of the list elements, not null

defaultValue - any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested using throwOnMissingProperty() or throwOnFailedConversion().

Returns:

the resolved and converted property value or an empty list

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()

asSet

<E> Set<E> asSet(Class<E> elementType)

Resolves the property as Set. Raw value is split into elements as defined by Config for array types.

If the property is missing, defined empty, the required element type converter is missing or conversion fails an empty set is returned. The returned set must not be considered modifiable.

This is equivalent to asSet(Class, Set) with an empty set as default value.

This is equivalent to as(Class, Object) with 1-dimensional array type of the provided element type as type where the returned array is later wrapped in a Set while also honouring defaults.

Parameters:

elementType - type of the set elements, not null

Returns:

the resolved and converted property value or an empty set

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()

asSet

<E> Set<E> asSet(Class<E> elementType,
                 Set<E> defaultValue)

Resolves the property as Set. Raw value is split into elements as defined by Config for array types.

If the property is missing, defined empty, the required element type converter is missing or conversion fails an empty set is returned. The returned set must not be considered modifiable.

This is equivalent to asSet(Class, Set) with an empty set as default value.

This is equivalent to as(Class, Object) with 1-dimensional array type of the provided element type as type where the returned array is later wrapped in a Set while also honouring defaults.

Parameters:

elementType - type of the set elements, not null

defaultValue - any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested using throwOnMissingProperty() or throwOnFailedConversion().

Returns:

the resolved and converted property value or an empty set

Throws:

IllegalArgumentException - if the property cannot be converted to the specified type and throwing exceptions has been requested using throwOnFailedConversion()

NoSuchElementException - if the property isn't present in the configuration and throwing exceptions has been requested using throwOnMissingProperty()