Global converters

Converters may be global to a Config instance. Global converters are registered either by being discovered or explicitly added to the configuration.

Global converters are automatically applied to types that match the converter's type.

Built-in converters

Global converters may be built in. Such converters are provided by the implementation. A compliant implementation must provide build-in converters for at least the following types:

boolean and Boolean, returning true for at least the following values (case insensitive):
- true
- yes
- y
- on
- 1
byte and Byte, accepting (at minimum) all values accepted by the Byte.parseByte(String) method
short and Short, accepting (at minimum) all values accepted by the Byte.parseByte(String) method
int, Integer, and OptionalInt accepting (at minimum) all values accepted by the Integer.parseInt(String) method
long, Long, and OptionalLong accepting (at minimum) all values accepted by the Long.parseLong(String) method
float and Float, accepting (at minimum) all values accepted by the Float.parseFloat(String) method
double, Double, and OptionalDouble accepting (at minimum) all values accepted by the Double.parseDouble(String) method
java.lang.Class based on the result of Class.forName(java.lang.String)

Global converter discovery

Custom global converters may be added to a configuration via the ServiceLoader mechanism, and as such can be registered by providing a resource named "META-INF/services/org.eclipse.microprofile.config.spi.Converter" which contains the fully qualified Converter implementation class name(s) (one per line) as content.

It is also possible to explicitly register a global converter to a configuration builder using the ConfigBuilder.withConverters(Converter[]) and ConfigBuilder.withConverter(Class, int, Converter) methods.

Implicit converters

If no global converter can be found for a given type, the configuration implementation must attempt to derive an implicit converter if any of the following are true (in order):

the target type has a public static T of(String) method
the target type has a public static T valueOf(String) method
the target type has a public static T parse(CharSequence) method
the target type has a public constructor with a single parameter of type String
the target type is an array of any type corresponding to either a registered global converter or a built in or implicit converter

Converter priority

A converter implementation class can specify a priority by way of the standard jakarta.annotation.Priority annotation or by explicitly specifying the priority value to the appropriate builder method.

If no priority is explicitly assigned, the default priority value of 100 is assumed.

If multiple converters are registered for the same type, the one with the highest numerical priority value will be used.

All built in Converters have a priority value of 1. Implicit converters are only created when no other converter was found; therefore, they do not have a priority.

Empty values

For all converters, the empty string "" must be considered an empty value. Some converters may consider other values to be empty as well.

Implementations may (but are not required to) implement Config.getOptionalValue() using a Converter. If so, this converter must return Optional.empty() for an empty input.

Array conversion

A conforming implementation must support the automatic creation of an implicit converter for array types. This converter uses a comma (U+002C ',') as a delimiter. To allow a comma to be embedded within individual array element values, it may be escaped using a backslash (U+005C '\') character. Any escaped comma character will be included as a plain comma within the single element (the backslash is discarded by the converter).

Empty elements must not be included in the final array. An array which would consist of only empty values must be considered empty; the array converter must return null in this case.

Method Summary

Modifier and Type

Method

Description

T

convert(String value)

Convert the given string value to a specified type.

Method Details
- convert
  
  T convert(String value) throws IllegalArgumentException, NullPointerException
  
  Convert the given string value to a specified type. Callers must not pass in null for value; doing so may result in a NullPointerException being thrown.
  
  Parameters:
  
  value - the string representation of a property value (must not be null)
  
  Returns:
  
  the converted value, or null if the value is empty
  
  Throws:
  
  IllegalArgumentException - if the value cannot be converted to the specified type
  
  NullPointerException - if the given value was null

Interface Converter<T>