ConfigProvider
Entry point for accessing configuration.
public final class ConfigProvider {
public static Config getConfig();
public static Config getConfig(ClassLoader loader);
}getConfig()
Returns the Config instance cached for the current thread context class loader, with the default configuration sources and the discovered sources and converters.
Config config = ConfigProvider.getConfig();
String value = config.getValue("key", String.class);A non-cached instance with the same content can be built programmatically:
ConfigBuilder builder = ConfigProviderResolver.instance().getBuilder();
Config config = builder
.addDefaultSources()
.addDiscoveredSources()
.addDiscoveredConverters()
.build();ConfigProviderResolver
SPI class that backs ConfigProvider and hands out builders. ConfigProvider has no builder method — getBuilder() lives here.
public abstract class ConfigProviderResolver {
public static ConfigProviderResolver instance();
public abstract Config getConfig();
public abstract Config getConfig(ClassLoader loader);
public abstract ConfigBuilder getBuilder();
public abstract void registerConfig(Config config, ClassLoader classLoader);
public abstract void releaseConfig(Config config);
}Config
Main configuration interface for reading properties.
public interface Config {
<T> T getValue(String propertyName, Class<T> propertyType);
ConfigValue getConfigValue(String propertyName);
<T> List<T> getValues(String propertyName, Class<T> propertyType); // default method
<T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType);
<T> Optional<List<T>> getOptionalValues(String propertyName, Class<T> propertyType); // default method
Iterable<String> getPropertyNames();
Iterable<ConfigSource> getConfigSources();
<T> Optional<Converter<T>> getConverter(Class<T> forType);
<T> T unwrap(Class<T> type);
}getValue()
Get a required property, converted to the target type.
String name = config.getValue("app.name", String.class);
int port = config.getValue("app.port", int.class);
String[] items = config.getValue("app.items", String[].class);Throws NoSuchElementException if key is not found.
Array types are supported directly (String[].class, int[].class, …). Collection types are not — getValue("app.items", List.class) has no converter; use getValues() / getOptionalValues() instead.
getConfigValue()
Get the value together with its resolution metadata (raw value, source name, source ordinal).
ConfigValue cv = config.getConfigValue("app.name");
String raw = cv.getRawValue();
String sourceName = cv.getSourceName();getValues()
Get a required multi-valued property (comma-separated) as a List<T>. This spec default method builds on the array conversion path.
List<String> items = config.getValues("app.items", String.class);getOptionalValue()
Get an optional property.
Optional<String> version = config.getOptionalValue("app.version", String.class);
String v = version.orElse("1.0.0");Returns Optional.empty() if key is not found; does not throw.
ConfigBuilder
Programmatic builder for Config instances, obtained from ConfigProviderResolver.instance().getBuilder().
public interface ConfigBuilder {
ConfigBuilder addDefaultSources();
ConfigBuilder addDiscoveredSources();
ConfigBuilder addDiscoveredConverters();
ConfigBuilder forClassLoader(ClassLoader loader);
ConfigBuilder withSources(ConfigSource... sources);
ConfigBuilder withConverters(Converter<?>... converters);
<T> ConfigBuilder withConverter(Class<T> type, int priority, Converter<T> converter);
Config build();
}withSources()
Add custom configuration sources.
builder.withSources(
new DatabaseConfigSource(),
new RemoteConfigSource()
);The builder starts empty: call addDefaultSources() to include the built-in sources (system properties, environment variables, microprofile-config.properties) alongside yours.
withConverters()
Add multiple converters at once.
builder.withConverters(
new ColorConverter(),
new DurationConverter()
);ConfigSource
SPI for implementing custom configuration sources.
public interface ConfigSource {
String CONFIG_ORDINAL = "config_ordinal";
int DEFAULT_ORDINAL = 100;
String getName();
default int getOrdinal(); // reads config_ordinal, falls back to DEFAULT_ORDINAL
String getValue(String propertyName);
Set<String> getPropertyNames();
default Map<String, String> getProperties();
}Converter
SPI for implementing type converters.
public interface Converter<T> extends Serializable {
T convert(String value) throws IllegalArgumentException, NullPointerException;
}Implement to convert string values to custom types:
public class ColorConverter implements Converter<Color> {
@Override
public Color convert(String value) {
if (value.startsWith("#")) {
return Color.decode(value);
}
// ... other parsing logic
throw new IllegalArgumentException("Invalid color: " + value);
}
}@ConfigProperty
CDI injection annotation (from MicroProfile Config spec).
@Inject
@ConfigProperty(name = "key")
String value;
@Inject
@ConfigProperty(name = "key", defaultValue = "default")
String valueWithDefault;
@Inject
@ConfigProperty(name = "key")
Optional<String> optionalValue;Attributes:
-
name— configuration key -
defaultValue— fallback value if key not found (makes injection optional)
ConfigSourceProvider
SPI for dynamic source discovery.
public interface ConfigSourceProvider {
Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader);
}Implement to provide multiple sources based on runtime conditions:
public class MySourceProvider implements ConfigSourceProvider {
@Override
public Iterable<ConfigSource> getConfigSources(ClassLoader cl) {
return List.of(
new Source1(),
new Source2()
);
}
}Environment variables mapping
For a property name, the environment is searched with three name forms, in order (MicroProfile Config §7.6):
-
the exact property name (e.g.
app.name); -
the property name with every non-alphanumeric character replaced by
_, original case preserved (e.g.app_name); -
the second form uppercased (e.g.
APP_NAME).
The first form that yields a value wins:
| Env var | Matches config key |
|---|---|
|
|
|
|
|
|
|
|
Property name patterns
-
Valid characters:
a-z,0-9,.,-,_ -
Case-sensitive (environment variables are reached through the three-form mapping above)
-
Hierarchical via
.(e.g.,app.database.host)
Special properties
-
mp.config.profile— active configuration profile; resolved like any other property, from whichever registered config source defines it (highest ordinal wins)