Vidocq Documentation

ConfigProvider

Point d’entrée pour accéder à la configuration.

public final class ConfigProvider {
    public static Config getConfig();
    public static ConfigBuilder getConfigBuilder();
}

getConfig()

Retourne une instance Config mise en cache avec les sources de configuration et les convertisseurs par défaut.

Config config = ConfigProvider.getConfig();
String value = config.getValue("key", String.class);

Équivalent à :

ConfigBuilder builder = ConfigProvider.getConfigBuilder();
Config config = builder.build();

getConfigBuilder()

Retourne un nouveau ConfigBuilder pour la configuration programmatique.

ConfigBuilder builder = ConfigProvider.getConfigBuilder();
builder.withSources(new MySource());
builder.withConverter(Color.class, new ColorConverter());
Config config = builder.build();

Config

Interface de configuration principale pour lire les propriétés.

public interface Config extends AutoCloseable {

    <T> T getValue(String propertyName, Class<T> propertyType);
    <T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType);

    Iterable<String> getPropertyNames();
    Iterable<ConfigSource> getConfigSources();
}

getValue()

Obtenir une propriété requise, convertie au type cible.

String name = config.getValue("app.name", String.class);
int port = config.getValue("app.port", int.class);
List<String> items = config.getValue("app.items", List.class);

Lève NoSuchElementException si la clé n’est pas trouvée.

getOptionalValue()

Obtenir une propriété optionnelle.

Optional<String> version = config.getOptionalValue("app.version", String.class);
String v = version.orElse("1.0.0");

Retourne Optional.empty() si la clé n’est pas trouvée ; ne lève pas d’exception.

getPropertyNames()

Lister tous les noms de propriétés disponibles.

for (String name : config.getPropertyNames()) {
    System.out.println(name);
}

getConfigSources()

Accéder à la liste ordonnée des sources de configuration.

for (ConfigSource source : config.getConfigSources()) {
    System.out.println(source.getName() + " (ordinal: " + source.getOrdinal() + ")");
}

ConfigBuilder

Builder programmatique pour les instances Config.

public interface ConfigBuilder {
    ConfigBuilder withSources(ConfigSource... sources);
    ConfigBuilder withConverters(Converter<?>... converters);
    <T> ConfigBuilder withConverter(Class<T> type, Converter<T> converter);
    Config build();
}

withSources()

Ajouter des sources de configuration personnalisées.

builder.withSources(
    new DatabaseConfigSource(),
    new RemoteConfigSource()
);

Les sources sont ajoutées à la cascade en plus des sources built-in.

withConverters()

Ajouter plusieurs convertisseurs à la fois.

builder.withConverters(
    new ColorConverter(),
    new DurationConverter()
);

withConverter()

Ajouter un convertisseur pour un type spécifique.

builder.withConverter(Color.class, new ColorConverter());
builder.withConverter(MyCustomType.class, value -> new MyCustomType(value));

build()

Créer l’instance Config.

Config config = builder.build();

ConfigSource

SPI pour implémenter des sources de configuration personnalisées.

public interface ConfigSource {

    String getName();
    int getOrdinal();

    String getValue(String propertyName);
    Map<String, String> getProperties();
}

getName()

Nom lisible pour la source (utilisé dans les journaux et l’introspection).

getOrdinal()

Ordre de priorité pour la recherche de source (plus haut = plus haute priorité).

Ordinaux built-in : * Propriétés système : 400 * Variables d’environnement : 300 * microprofile-config.properties : 100

getValue()

Retourner une valeur de propriété ou null si non trouvée.

getProperties()

Retourner toutes les propriétés de cette source.

Converter

SPI pour implémenter les convertisseurs de types.

public interface Converter<T> {
    T convert(String value);
}

Implémentez pour convertir les valeurs de chaîne en types personnalisés :

public class ColorConverter implements Converter<Color> {
    @Override
    public Color convert(String value) {
        if (value.startsWith("#")) {
            return Color.decode(value);
        }
        // ... autre logique de parsing
        throw new IllegalArgumentException("Invalid color: " + value);
    }
}

@ConfigProperty

Annotation d’injection CDI (de la spec MicroProfile Config).

@Inject
@ConfigProperty("key")
String value;

@Inject
@ConfigProperty(name = "key", defaultValue = "default")
String valueWithDefault;

@Inject
@ConfigProperty("key")
Optional<String> optionalValue;

Attributs : * name — clé de configuration * defaultValue — valeur de repli si la clé n’est pas trouvée (rend l’injection optionnelle)

ConfigSourceProvider

SPI pour la découverte dynamique de sources.

public interface ConfigSourceProvider {
    Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader);
}

Implémentez pour fournir plusieurs sources en fonction des conditions runtime :

public class MySourceProvider implements ConfigSourceProvider {
    @Override
    public Iterable<ConfigSource> getConfigSources(ClassLoader cl) {
        return List.of(
            new Source1(),
            new Source2()
        );
    }
}

Mappage des variables d’environnement

Les variables d’environnement sont automatiquement mappées aux clés de propriétés :

| Var env | Clé config | |---------|------------| | APP_NAME | app.name | | APP_DB_HOST | app.db.host | | my_property | my.property | | MY_PROPERTY | my.property |

La casse est normalisée en minuscules ; les traits de soulignement et les points sont traités de manière équivalente.

Motifs de noms de propriété

  • Caractères valides : a-z, 0-9, ., -, _

  • Insensible à la casse (mais conventionnellement en minuscules)

  • Hiérarchique via . (p. ex., app.database.host)

Propriétés spéciales

  • mp.config.profile — profil de configuration actif (propriété système uniquement)

Exceptions

  • NoSuchElementException — propriété non trouvée dans getValue() (requise)

  • IllegalArgumentException — échec de la conversion de type, ou cycle d’expression détecté

  • DeploymentException — échec de l’injection CDI (clé requise manquante)

Suivant

  • Usage — configuration programmatique

  • TCK — test de conformance