Interface Converter<T>
- All Superinterfaces:
Serializable
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
andBoolean
, returningtrue
for at least the following values (case insensitive):true
yes
y
on
1
byte
andByte
, accepting (at minimum) all values accepted by theByte.parseByte(String)
methodshort
andShort
, accepting (at minimum) all values accepted by theByte.parseByte(String)
methodint
,Integer
, andOptionalInt
accepting (at minimum) all values accepted by theInteger.parseInt(String)
methodlong
,Long
, andOptionalLong
accepting (at minimum) all values accepted by theLong.parseLong(String)
methodfloat
andFloat
, accepting (at minimum) all values accepted by theFloat.parseFloat(String)
methoddouble
,Double
, andOptionalDouble
accepting (at minimum) all values accepted by theDouble.parseDouble(String)
methodjava.lang.Class
based on the result ofClass.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
-
Method Details
-
convert
Convert the given string value to a specified type. Callers must not pass innull
forvalue
; doing so may result in aNullPointerException
being thrown.- Parameters:
value
- the string representation of a property value (must not benull
)- Returns:
- the converted value, or
null
if the value is empty - Throws:
IllegalArgumentException
- if the value cannot be converted to the specified typeNullPointerException
- if the given value wasnull
-