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

All Methods Instance Methods Abstract Methods
`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`