Interface ConfigValueResolver
-
public interface ConfigValueResolver
This is an abstraction to resolve
Config
values using a fluent API that is used when the basicConfig.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 occurConfig.getValue(String, Class)
can be used instead.Values can be resolved as
List
orSet
. 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()
andthrowOnFailedConversion()
.Usually conversion relies on registered
Converter
s. Ad-hoc conversion can be done usingasConvertedBy(Function, Object)
. Values resolved asString
are not converted. Values resolved asString[]
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 usingwithDefault(String)
. As the API can not capture if such a raw default has been provided it still requires to provide a typed default or useOptional
to ensure resolution will return a value. If a rawString
is provided it takes precedence over a typed default. Should conversion of a raw default fail the typed default is used or in case ofOptional
the property is considered not present.The only way
as
-methods might return anull
reference is by usingnull
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 Description static class
ConfigValueResolver.ElementPolicy
What to do when collection element conversion fails.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description <T> Optional<T>
as(Class<T> type)
Resolves the property as a simple or array type wrapped in anOptional
.<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 converterFunction
.<E> List<E>
asList(Class<E> elementType)
Resolves the property asList
.<E> List<E>
asList(Class<E> elementType, List<E> defaultValue)
Resolves the property asList
.<E> Set<E>
asSet(Class<E> elementType)
Resolves the property asSet
.<E> Set<E>
asSet(Class<E> elementType, Set<E> defaultValue)
Resolves the property asSet
.<E> Supplier<E>
asSupplier(Class<E> elementType)
Resolves the property asSupplier
.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 theConfigValueResolver.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, notnull
- 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 applyingString.trim()
to the source level value- Returns:
- This resolver for fluent API usage
-
withPolicy
ConfigValueResolver withPolicy(ConfigValueResolver.ElementPolicy policy)
Change theConfigValueResolver.ElementPolicy
setting. This affects array types as well asList
andSet
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 usingwithDefault(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 andthrowOnFailedConversion()
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, notnull
defaultValue
- any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested usingthrowOnMissingProperty()
orthrowOnFailedConversion()
.- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
as
<T> Optional<T> as(Class<T> type)
Resolves the property as a simple or array type wrapped in anOptional
.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, notnull
- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
asConvertedBy
<T> T asConvertedBy(Function<String,T> converter, T defaultValue)
Resolves the property as converted by the provided converterFunction
.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 emptyString
might be passed to the provided converter function, otherwise the empty string will be considered missing.- Parameters:
type
- target type of the conversion, notnull
defaultValue
- any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested usingthrowOnMissingProperty()
orthrowOnFailedConversion()
.- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
asList
<E> List<E> asList(Class<E> elementType)
Resolves the property asList
. Raw value is split into elements as defined byConfig
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 aList
while also honouring defaults.- Parameters:
elementType
- type of the list elements, notnull
- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
asSupplier
<E> Supplier<E> asSupplier(Class<E> elementType)
Resolves the property asSupplier
. Raw value will be fetched anew each time the supplier is called.- Parameters:
elementType
- type of the element, notnull
- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
asList
<E> List<E> asList(Class<E> elementType, List<E> defaultValue)
Resolves the property asList
. Raw value is split into elements as defined byConfig
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 aList
while also honouring defaults.- Parameters:
elementType
- type of the list elements, notnull
defaultValue
- any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested usingthrowOnMissingProperty()
orthrowOnFailedConversion()
.- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
asSet
<E> Set<E> asSet(Class<E> elementType)
Resolves the property asSet
. Raw value is split into elements as defined byConfig
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 aSet
while also honouring defaults.- Parameters:
elementType
- type of the set elements, notnull
- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
asSet
<E> Set<E> asSet(Class<E> elementType, Set<E> defaultValue)
Resolves the property asSet
. Raw value is split into elements as defined byConfig
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 aSet
while also honouring defaults.- Parameters:
elementType
- type of the set elements, notnull
defaultValue
- any value including null. It is returned in case of missing property or failed conversion unless throwing exceptions has been explicitly requested usingthrowOnMissingProperty()
orthrowOnFailedConversion()
.- 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 usingthrowOnFailedConversion()
NoSuchElementException
- if the property isn't present in the configuration and throwing exceptions has been requested usingthrowOnMissingProperty()
-
-