org.eclipse.microprofile.config.spi

Interface Converter<T>

public interface Converter<T>

Interface for converting configured values from String to any Java type.

Converters for the following types are provided by default:

• boolean and Boolean, values for true: (case insensitive) "true", "yes", "Y", "on", "1"
• int and Integer
• long and Long
• float and Float, a dot '.' is used to separate the fractional digits
• double and Double, a dot '.' is used to separate the fractional digits
• java.time.Duration as defined in Duration.parse(CharSequence)
• java.time.LocalDateTime as defined in LocalDateTime.parse(CharSequence)
• java.time.LocalDate as defined in LocalDate.parse(CharSequence)
• java.time.LocalTime as defined in LocalTime.parse(CharSequence)
• java.time.OffsetDateTime as defined in OffsetDateTime.parse(CharSequence)
• java.time.OffsetTime as defined in OffsetTime.parse(CharSequence)
• java.time.Instant
• java.net.URL as defined by URL.URL(java.lang.String)
• java.lang.Class based on the result of Class.forName(java.lang.String)

Custom Converters will get picked up via the ServiceLoader mechanism and and can be registered by providing a file
META-INF/services/org.eclipse.microprofile.config.spi.Converter
which contains the fully qualified Converter implementation class name as content.

A Converter can specify a javax.annotation.Priority. If no priority is explicitly assigned, the value of 100 is assumed. If multiple Converters are registered for the same type, the one with the highest priority will be used.

Custom Converters can also be registered programmatically via `ConfigBuilder#withConverters(Converter... converters)` or `ConfigBuilder#withConverter(Class type, int priority, Converter converter)`. All Built In Converters have a javax.annotation.Priority of 1 A Converter should handle null values returning either null or a valid Object of the specified type.

Array Converters

The implementation must support the Array converter for each built-in converters and custom converters. The delimiter for the config value is ",". The escape character is "\". e.g. myPets=dog,cat,dog\,cat

For the property injection, List and Set should be supported as well.

Usage:

String[] myPets = config.getValue("myPet", String[].class);

@Inject @ConfigProperty(name="myPets") private String[] myPets;

@Inject @ConfigProperty(name="myPets") private List<String> myPets;

@Inject @ConfigProperty(name="myPets") private Set<String> myPets;

myPets will be "dog", "cat", "dog,cat"

Implicit Converters

If no explicit Converter and no built-in Converter could be found for a certain type, the Config provides an Implicit Converter, if

• The target type T has a Constructor with a String parameter, or
• the target type T has a static T valueOf(String) method, or
• the target type T has a static T parse(CharSequence) method

Author:

Ron Smeral, Mark Struberg, Emily Jiang, John D. Ament

Method Summary

Modifier and Type	Method and Description
T	convert(String value) Configure the string value to a specified type

Method Detail

convert

T convert(String value)

Configure the string value to a specified type

Parameters:

value - the string representation of a property value.

Returns:

the converted value or null

Throws:

IllegalArgumentException - if the value cannot be converted to the specified type.