Package org.eclipse.microprofile.config.spi

Interface Converter<T>

All Superinterfaces:

Serializable

public interface Converter<T>
extends Serializable

A mechanism for converting configured values from String to any Java type.

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.

Author:

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

Method Summary

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

Method Detail

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