Package org.eclipse.microprofile.config.spi

Interface Converter<T>

  • All Superinterfaces:
    java.io.Serializable
    public interface Converter<T>
extends java.io.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
    • int and Integer, accepting (at minimum) all values accepted by the Integer.parseInt(String) method
    • long and Long, 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 and Double, 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)
    • 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 javax.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.

    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).

    • Method Detail

      • convert

        T convert​(java.lang.String value)
        Convert the given string value to a specified type.
        Parameters:
        value - the string representation of a property value
        Returns:
        the converted value, or null if the value is empty
        Throws:
        java.lang.IllegalArgumentException - if the value cannot be converted to the specified type