![[17.0.0.3 and later]](../ng_v17003plus.gif)
API MicroProfile Config
L'API MicroProfile Config peut être utilisée par les applications comme une seule API pouvant récupérer les informations de configuration de différentes sources.
- Plusieurs sources de configuration peuvent être amalgamées dans une seule configuration et être accessibles via une seule API.
- Les valeurs des propriétés de configuration peuvent être écrasées et remplacées par les valeurs des sources de configuration désignées comme prioritaires.
- Les valeurs peuvent être stockées dans des fichiers de propriétés nommés, dans des variables d'environnement du système ou dans des propriétés Java™.
- Les ressources ConfigSource sont chargées à l'aide d'un Java ClassLoader : le ClassLoader du contexte actuel de l'application ou un ClassLoader fourni par l'utilisateur.
- Les valeurs peuvent être fournies en enregistrant une implémentation d'utilisateur d'une interface ConfigSource.
- Les valeurs peuvent être extraites sous forme de chaînes ou d'objets tapés d'une classe Java particulière à l'aide des convertisseurs de type intégrés ou personnalisés.
- Les implémentations ConfigSource et Converter peuvent être découvertes à l'aide du modèle Java ServiceLoader.
- Les valeurs des propriétés de configuration, qu'elles soient de type primitif, standard ou fournies par l'utilisateur, peuvent être directement injectées via Java CDI (Context and Dependency Injection).
Injection de configuration
L'API MicroProfile Config collecte les sources de configuration par défaut et les sources de configuration qui sont chargées par Java ServiceLoader configsources et qui sont décrites plus tard dans cette rubrique. Java CDI peut être utilisé pour injecter l'objet de configuration directement dans une application.
@Inject
Config config;
String appName = config.getValue(“APP_NAME”, String.class);
Il est également possible d'injecter une seule valeur de propriété de configuration.
@Inject
@ConfigProperty
String PROPERTY_NAME1;
Ces propriétés sont représentées à l'état brut en tant que chaînes, tout comme des propriétés Java standard. Le système utilise les paramètres par défaut des sources de configuration et obtient le nom de la propriété de configuration du nom de classname, la première lettre étant une minuscule, suivi du nom de variable, avec un point comme séparateur. Par exemple, si le fragment précédent se trouve dans la classe appelée ClassA, le nom de propriété qui est résolu est classA.PROPERTY_NAME1.
@Inject
@ConfigProperty(name="PROPERTY_NAME2")
String propertyTwo;
Ce fragment de code recherche la propriété obligatoire PROPERTY_NAME2 dans les sources de configuration. Si la propriété n'existe pas, une exception DeploymentException est émise.
@inject
@ConfigProperty(name="myName", defaultValue="Bob")
String name;
Ce fragment de code recherche la propriété myName dans les configsources configurées. Si la propriété n'est pas définie, la valeur
Bob est affectée à la variable name.Recherche de configuration programmée
L'API MicroProfile Config fournit également une interface permettant d'extraire les propriétés de configuration à l'aide d'appels de méthode. Cette extraction peut être faite de deux manières : à l'aide d'une classe de fournisseur de configuration simple à utiliser qui utilise les paramètres par défaut, et à l'aide d'une classe de générateur de configuration entièrement personnalisable.
La classe ConfigProvider
La manière la plus simple d'utiliser une configuration est d'utiliser une méthode statique sur la classe ConfigProvider. Cette API collecte les sources de configuration par défaut et les sources de configuration qui sont chargées par les configsources de Java® ServiceLoader.
Config config = ConfigProvider.getConfig();
String appName = config.getValue(“APP_NAME”, String.class);
La classe ConfigBuilder
Pour les utilisateurs qui souhaitent créer des configurations de manière plus personnalisée, une API de génération de configuration peut être utilisée pour définir plusieurs options avant que la configuration ne soit générée. Cet exemple utilise le modèle de générateur pour générer la configuration équivalente à celle de l'exemple précédent.
ConfigBuilder builder = ConfigProviderResolver.getBuilder();
builder.addDefaultSources();
Config config = builder.build();
L'appel de builder.addDefaultSources() ajoute le même ensemble de sources par défaut que celui utilisé par ConfigProvider pour générer les configurations. D'autres sources de configuration peuvent également être ajoutées.
Sources de configuration
Les propriétés de configuration peuvent être obtenues de différents emplacements, notamment des fichiers de propriétés et des classes d'utilisateurs qui sont enregistrées par l'application ou chargées à l'aide du modèle Java ServiceLoader.
Sources par défaut
Contrairement à l'interface ConfigProvider, l'interface ConfigBuilder possède au départ un ensemble vide de sources de propriétés de configuration. L'ajout de sources par défaut produit les effets suivants :
- Les variables d'environnement des processus sont incluses dans la configuration. Liberty affiche les variables d'environnement des processus hôte dans la méthode Java System.getenv() et ajoute en plus des propriétés du fichier server.env du serveur. Ces variables sont ensuite disponibles dans l'API MicroProfile Config.
- Les propriétés système Java disponibles au moyen de System.getProperties() sont incluses dans la configuration. Liberty ajoute les propriétés des fichiers bootstrap.properties et jvm.options du serveur aux propriétés système Java.
- Fichiers chargés du chemin d'accès aux classes ThreadContextClassLoader de l'application avec un resourceName de META-INF/microprofile-config.properties. Dans ces fichiers de propriétés, les propriétés sont stockées avec la même syntaxe que celle qui est utilisée par les fichiers de propriétés Java standard. Dans une application Liberty, l'emplacement du répertoire META-INF peut être un sous-répertoire à la racine d'un fichier JAR ou le répertoire WEB-INF\classes\META-INF\ d'un fichier WAR, ou dans un JAR dans le répertoire lib d'un fichier EAR, ou dans un JAR de bibliothèque partagée de niveau serveur. Le ClassLoader et donc le chemin d'accès aux classes utilisé peut être modifié à l'aide de la méthode forClassLoader du générateur.
Sources de configuration fournies par l'utilisateur
Une classe d'utilisateur qui implémente org.eclipse.microprofile.config.spi.ConfigSource peut être enregistrée avec un ConfigBuilder. De cette manière, elle est ensuite incluse plus tard dans les configurations que le générateur produit.
MySource source = new MySource();
builder.withSources(source);
Chargement des sources de configuration avec Java ServiceLoader
Le modèle Java ServiceLoader peut également être utilisé pour localiser des objets de source de configuration personnalisés. Une classe d'utilisateur qui implémente l'interface ConfigSource est chargée si le nom de classe complet de son package est répertorié dans un fichier au format ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource.
Convertisseurs
L'API MicroProfile Config peut également extraire des propriétés en tant que types d'objet Java avec une méthode rendue générique qui prend le type de l'objet de propriété souhaité. Cette méthode peut fonctionner sur n'importe quel type ayant un convertisseur intégré ou fourni par l'utilisateur. Par exemple, le code utilisé dans l'exemple suivant peut être écrit pour utiliser le convertisseur String intégré comme :
appName = config.getOptionalValue(“APP_NAME”, String.class).orElse(“MicroDemo”);
Convertisseurs intégrés
L'API MicroProfile Config inclut des convertisseurs intégrés pour les types suivants : boolean, Boolean, int, Integer, long, Long, float, Float, double, Double, Duration, LocalTime, LocalDate, LocalDateTime, OffsetDateTime, OffsetTime, Instant et URL.
Les variables appartenant à l'un de ces types peut être injectées directement ou extraites à l'aide de l'appel générique getValue si la valeur de chaîne de la propriété peut être convertie correctement au type avec valueof, parse ou à l'aide de la méthode de construction en prenant un seul paramètre String.
Convertisseurs personnalisés
Les convertisseurs personnalisés qui implémentent l'interface org.eclipse.microprofile.config.spi.Converter<T> peuvent être enregistrés et utilisés dans des configurations à l'aide de l'API ConfigBuilder.
ConfigBuilder builder = ConfigProviderResolver.getBuilder();
builder.addDefaultSources();
Converter<CustomProperty> converter = new MyConverter();
builder.withConverters(converter);
Config config = builder.build();
Optional<CustomProperty> opt = config.getOptionalValue(“PROPOBJ”, CustomProperty.class);
La méthode withConverters utilise le reflet pour déterminer le type auquel s'adresse le convertisseur. Le code Java Lambda n'offre
actuellement pas d'informations suffisamment spécifiques aux API de reflet de sorte qu'un code qui implémente explicitement une interface Converter<T> est requis pour un
convertisseur personnalisé.Priorité des convertisseurs
Si plusieurs convertisseurs du même type existent, le convertisseur utilisé peut être contrôlé à l'aide d'une annotation @Priority. Cette méthode permet de substituer l'implémentation du convertisseur plus tard dans la durée de vie de l'application. Un convertisseur substitue tout autre convertisseur du même type ayant une priorité inférieure.
import javax.annotation.Priority;
import org.eclipse.microprofile.config.spi.Converter;
@Priority(200)
publicclass StringPrefixConverter implements Converter<String> {
@Override
public String convert(String value) throws IllegalArgumentException {
return"Converted:" + value;
}
}
La priorité par défaut d'un convertisseur est 100 si l'annotation @Priority n'est pas utilisée.
Prise en charge de Java ServiceLoader pour convertisseurs
Le modèle Java ServiceLoader peut également être utilisé pour localiser des convertisseurs personnalisés si leur noms de classe complets apparaissent dans un fichier de service au format ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.Converter.
Les convertisseurs par défaut inclus dans l'implémentation de l'API MicroProfile Config et les convertisseurs détectés à l'aide des modèles Java ServiceLoader sont disponibles pour toutes les configurations à utiliser.
Remplacement des valeurs de propriété
Lorsque plusieurs sources de configuration sont utilisées, les propriétés de toutes les sources sont collectées ensemble pour que l'application puisse y accéder en tant qu'un seul ensemble. Chaque source de configuration obtient une valeur ordinale. Si une propriété apparaît dans plusieurs sources, la valeur de propriété de la source ayant la valeur ordinale la plus élevée est prioritaire et est renvoyée à l'application. Les valeurs ordinales par défaut sont :
- Propriétés système - 400
- Variables d'environnement - 300
- /META-INF/microprofile-config.properties - 100
- Objets ConfigSource personnalisés - Le résultat getOrdinal de ConfigSource
Si deux objets ConfigSources fournissant la même propriété ont des valeurs ordinales identiques, l'ID ConfigSources est utilisé pour une comparaison, conformément aux règles de comparaison applicables aux chaînes.
Les sources qui sont normalement définies plus tôt dans le cycle de vie du développement ont des valeurs ordinales et une priorité inférieures. Ceci permet de pouvoir redéfinir une valeur de propriété existante plus tard dans le cycle de vie de l'application, par exemple durant l'assemblage de l'application ou l'installation.
Valeurs des propriétés dynamiques
Bien qu'une application de microservice bien conçue reste disponible lors des redémarrages d'applications individuels, il est souhaitable que les valeurs de configuration soient disponibles dans une application sans avoir à la redémarrer. Les valeurs de propriétés d'une configuration fournies par des objets ConfigSource enregistrés peuvent être actualisés avec n'importe quelle valeur mise à jour fournie par ConfigSources. La fréquence avec laquelle ConfigSources est consulté et avec laquelle les valeurs sont actualisées est contrôlée par la propriété de système Java microprofile.config.refresh.rate. Les unités qui sont utilisées sont des millisecondes et la valeur par défaut est 500, ce qui signifie que par défaut, les valeurs fournies par ConfigSources sont transmis à n'importe quelle configuration à laquelle ils contribuent en approximativement une seconde.
Les sources de configuration non programmables comme les fichiers microprofile-config.properties ne sont pas relues dynamiquement après la construction de la configuration initiale.
Pour pouvoir voir les mises à jour apportées aux valeurs suite à l'injection des propriétés, un objet ConfigValue peut être utilisé. Celui-ci a des méthodes d'accès get pour la valeur de propriété de configuration et un Optional<T> de la valeur de propriété de configuration, qui renvoient la valeurs en cours à chaque fois que la méthode d'accès get est appelée. Par exemple :
@Inject
@ConfigProperty(name="propertyName3")
Provider<MyClass> propertyName3;
MyClass mc = propertyName3.get();
Vous pouvez également voir que la classe ConfigValue est rendue générique et qu'elle peut être utilisée pour extraire une propriété d'un type spécifique si un convertisseur approprié est présent.
Mise en cache de la configuration
Pour garantir une meilleure efficacité, un ConfigProvider met en cache la configuration renvoyée par sa méthode getConfig pour une application particulière (ou module) identifiée par son ClassLoader. Si la configuration est générée à l'aide de ConfigBuilder, l'objet de configuration n'est pas mis en cache. Cependant, le ConfigProviderResolver contenu dans le package org.eclipse.microprofile.config.spi a une méthode registerConfig qui peut être utilisée pour mettre en cache les objets Config et une méthode releaseConfig pour libérer l'objet Config.
Pour en savoir plus sur l'implémentation de MicroProfile Config dans Liberty, voir le site du projet de MicroProfile Config.