![[17.0.0.3 und höher]](../ng_v17003plus.gif)
API "MicroProfile Config"
Die API "MicroProfile Config" kann von Anwendungen als zentrale API verwendet werden, die Konfigurationsinformationen aus verschiedenen Quellen abruft.
- Es ist möglich, mehrere Konfigurationsquellen zu einer einzigen Konfiguration zusammenzufassen und über eine einzige API auf diese Konfiguration zuzugreifen.
- Konfigurationseigenschaftswerte können mit Werten aus Konfigurationsquellen, für die eine höhere Priorität definiert wurde, überschrieben werden.
- Werte können in benannten Eigenschaftendateien, Systemumgebungsvariablen oder Java™-Systemeigenschaften gespeichert werden.
- ConfigSource-Ressourcen werden mit einem Java-ClassLoader, dem ClassLoader des aktuellen Kontextes oder mit einem vom Benutzer bereitgestellten ClassLoader geladen.
- Werte können durch Registrieren einer Benutzerimplementierung einer ConfigSource-Schnittstelle bereitgestellt werden.
- Werte können als Zeichenfolgen oder mithilfe integrierter oder angepasster Typconverter als typisierte Objekte einer bestimmten Java-Klasse abgerufen werden.
- ConfigSource- und Converter-Implementierungen können mit dem Java-Muster ServiceLoader erkannt werden.
- Konfigurationswerte können für Basiselement, Standardtypen und benutzerdefinierte Typen mithilfe von Java CDI (Context and Dependency Injection) direkt eingefügt werden.
Konfigurationsinjektion
Die API "MicroProfile Config" stellt die Standardkonfigurationsquellen und die Konfigurationsquellen, die mit dem Java-Muster ServiceLoader configsources geladen werden und weiter hinten in diesem Abschnitt noch beschrieben werden, zusammen. Mit Java CDI (Contexts and Dependency Injection) kann das Konfigurationsobjekt direkt in die Anwendung eingefügt werden.
@Inject
Config config;
String appName = config.getValue(“APP_NAME”, String.class);
Es ist auch möglich, eine einzigen Konfigurationseigenschaftswert einzufügen.
@Inject
@ConfigProperty
String PROPERTY_NAME1;
Diese Eigenschaften werden wie Java-Standardeigenschaften in unaufbereiteter Form als Zeichenfolgen dargestellt. Das System verwendet die Standardeinstellungen für Konfigurationsquellen und ruft die Namen der Konfigurationseigenschaft aus dem Namen des Elements classname ab. Dabei ist der erste Buchstabe ein Kleinbuchstabe, dem nach dem Punkt als Trennzeichen der Variablenname folgt. Wenn das vorherige Snippet beispielsweise in der Klasse ClassA enthalten ist, lautet der aufgelöste Eigenschaftsname classA.PROPERTY_NAME1.
@Inject
@ConfigProperty(name="PROPERTY_NAME2")
String propertyTwo;
Mit dem Code-Snippet wird die obligatorische Eigenschaft PROPERTY_NAME2 aus den Konfigurationsquellen abgerufen. Wenn die Eigenschaft nicht vorhanden ist, wird eine Ausnahme des Typs "DeploymentException" ausgelöst.
@inject
@ConfigProperty(name="myName", defaultValue="Bob")
String name;
Mit dem Code-Snippet wird die Eigenschaft myName in den konfigurierten configsources-Elementen gesucht. Wenn die Eigenschaft nicht definiert ist, wird der Wert Bob
der Variablen name zugewiesen.Programmgestützte Konfigurationssuche
Die API "MicroProfile Config" stellt auch eine Schnittstelle für den Abruf der Konfigurationseigenschaften mit Methodenaufrufen bereit. Dieser Abruf kann auf zwei Arten erfolgen: mit einer einfach zu verwendenden Konfigurationsproviderklasse, die Standardeinstellungen verwendet, oder mit einer vollständig anpassbaren Konfigurationsbuilderklasse.
ConfigProvider-Klasse
Die einfachste Methode, eine Konfiguration zu verwenden, ist die Verwendung einer statischen Methode in der Klasse ConfigProvider. Diese API stellt die Standardkonfigurationsquellen und die Konfigurationsquellen, die mit dem Java-Muster ServiceLoader configsources geladen werden, zusammen.
Config config = ConfigProvider.getConfig();
String appName = config.getValue(“APP_NAME”, String.class);
ConfigBuilder-Klasse
Benutzer, die angepasste Konfigurationen erstellen möchten, können eine Konfigurationsbuilder-API verwenden, mit der vor der Generierung der Konfiguration verschiedene Optionen definiert werden können. In diesem Beispiel wird das Buildermuster verwendet, um eine äquivalente Konfiguration zu der aus dem vorherigen Beispiel zu erstellen.
ConfigBuilder builder = ConfigProviderResolver.getBuilder();
builder.addDefaultSources();
Config config = builder.build();
Beim Aufruf von builder.addDefaultSources() wird dieselbe Gruppe von Standardquellen hinzugefügt, die auch ConfigProvider für das Erstellen von Konfigurationen verwendet. Sie können auch weitere Konfigurationsquellen hinzufügen.
Konfigurationsquellen
Konfigurationseigenschaften können von verschiedenen Positionen geladen werden, darunter Eigenschaftendateien oder Benutzerklassen, die von der Anwendung registriert oder mit dem Java-Muster ServiceLoader geladen werden.
Standardquelle
Anders als die Schnittstelle ConfigProvider hat die Schnittstelle ConfigBuilder zunächst eine leere Gruppe von Konfigurationseigenschaftsquellen. Das Hinzufügen der Standardquellen hat folgende Auswirkungen:
- Prozessumgebungsvariablen werden in die Konfiguration eingeschlossen. Liberty zeigt der Java-Methode System.getenv() die Umgebungsvariablen für den Hostprozess an und fügt außerdem Eigenschaften aus der Serverdatei server.env hinzu. Diese Variablen stehen daraufhin der API "MicroProfile Config" zur Verfügung.
- Mit der Methode System.getProperties() abgerufene Java-Systemeigenschaften werden in die Konfiguration eingeschlossen. Liberty fügt den Java-Systemeigenschaften Eigenschaften aus den Serverdateien bootstrap.properties und jvm.options hinzu.
- Dateien werden aus dem Anwendungsklassenpfad ThreadContextClassLoader mit dem resourceName-Wert META-INF/microprofile-config.properties geladen. In diesen Eigenschaftendateien werden Eigenschaften mit derselben Syntax gespeichert, die von Java-Standardeigenschaftendateien verwendet wird. Bei einer Liberty-Anwendung kann die Position des Verzeichnisses META-INF ein Unterverzeichnis des Stammverzeichnisses einer JAR-Datei oder das Verzeichnis WEB-INF\classes\META-INF\ einer WAR-Datei sein, sich in einer JAR-Datei im Verzeichnis "lib" einer EAR-Datei oder in der JAR-Datei einer gemeinsam genutzten Bibliothek auf Serverebene befinden. Der ClassLoader und damit der verwendete Klassenpfad können mit der Methode forClassLoader des Builders (Erstellungsprogramms) geändert werden.
Vom Benutzer bereitgestellte Konfigurationsquellen
Eine Benutzerklasse, die org.eclipse.microprofile.config.spi.ConfigSource implementiert, kann bei einem ConfigBuilder registriert werden, um sie auf diese Weise später in Konfigurationen einzuschließen, die der Builder erzeugt.
MySource source = new MySource();
builder.withSources(source);
Konfigurationsquellen mit dem Java-Muster "ServiceLoader" laden
Das Java-Muster "ServiceLoader" kann ebenfalls verwendet werden, um angepasste Konfigurationsquellenobjekte zu suchen. Eine Benutzerklasse, die die Schnittstelle ConfigSource implementiert, wird geladen, wenn deren vollständig qualifizierter Paketklassenname in einer Datei im Format ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource aufgelistet ist.
Converter
Die API "MicroProfile Config" kann Eigenschaften auch als Java-Objekttypen abrufen. Sie verwendet dazu eine generische Methode, die den Typ des gewünschten Eigenschaftsobjekts übernimmt. Diese Methode funktioniert für jeden Typ, der einen integrierten oder vom Benutzer bereitgestellten Converter hat. Der Code aus dem vorherigen Beispiel kann beispielsweise wie folgt geschrieben werden, sodass ein integrierter Zeichenfolgenconverter verwendet wird:
appName = config.getOptionalValue(“APP_NAME”, String.class).orElse(“MicroDemo”);
Integrierte Converter
Die API "MicroProfile Config" enthält integrierte Converter für die folgenden Datentypen: boolean, Boolean, int, Integer, long, Long, float, Float, double, Double, Duration, LocalTime, LocalDate, LocalDateTime, OffsetDateTime, OffsetTime, Instant und URL.
Variablen dieser Typen können direkt eingefügt oder mit dem generischen Aufruf getValue abgerufen werden. Wenn der Zeichenfolgewert der Eigenschaft mit der relevanten valueof-, parse- oder Konstruktormethode unter Verwendung eines einzigen Zeichenfolgeparameters erfolgreich in den Typ konvertiert werden kann.
Angepasste Converter
Angepasste Converter, die die Schnittstelle org.eclipse.microprofile.config.spi.Converter<T> implementieren, können mit der API ConfigBuilder in Konfigurationen registriert und verwendet werden.
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);
Die Methode withConverters verwendet Reflexion, um festzustellen, für welchen Typ der Converter bestimmt ist.
Java-Lambda-Code liefert den Reflexions-APIs momentan nicht genügend Typinformationen, sodass für einen angepassten Converter Code erforderlich ist, der explizit eine Schnittstelle Converter<T> implementiert.Converterpriorität
Wenn mehrere Converter für denselben Typ vorhanden sind, kann mit einer Annotation @Priority gesteuert werden, welcher Converter verwendet wird. Diese Methode lässt das Überschreiben der Converterimplementierung zu einem späteren Zeitpunkt im Anwendungslebenszyklus zu. Ein Converter überschreibt einen Converter mit einer niedrigeren Priorität für denselben Typ.
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;
}
}
Wenn die Annotation @Priority nicht verwendet wird, hat ein Converter standardmäßig die Priorität 100.
Unterstützung des Java-Musters "ServiceLoader" für Converter
Das Java-Muster "ServiceLoader" kann auch verwendet werden, um angepasste Converter zu suchen, wenn deren qualifizierten Paketklassennamen in einer Servicedatei im Format ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.Converter angegeben sind.
Allen Konfigurationen stehen sowohl die in der Implementierung der API "MicroProfile Config" enthaltenen Standardconverter als auch die Converter, die mit dem Java-Muster ServiceLoader erkannt werden, zur Verfügung.
Eigenschaftswert überschreiben
Wenn mehrere Konfigurationsquellen verwendet werden, werden die Eigenschaften aus allen Quellen zusammengefasst, sodass die Anwendung auf eine einzige Gruppe zugreifen kann. Jeder Konfigurationsquelle wird ein Ordinalwert zugewiesen. Wenn eine Eigenschaft in mehreren Quellen vorkommt, hat der Eigenschaftswert aus der Quelle mit der höchsten Ordinalzahl Vorrang und dieser Wert wird an die Anwendung zurückgegeben. Im Folgenden sind die Standardordinalwerte aufgelistet:
- Systemeigenschaften - 400
- Umgebungsvariablen - 300
- /META-INF/microprofile-config.properties - 100
- Angepasste ConfigSource-Objekte - getOrdinal-Ergebnis für die ConfigSource
Wenn zwei ConfigSources mit derselben Eigenschaft identische Ordinalzahlen haben, wird entsprechend den Regeln für Zeichenfolgevergleich die ConfigSources-ID für den Vergleich verwendet.
Quellen, die normalerweise zu einem früheren Zeitpunkt im Entwicklungszyklus definiert werden, haben kleinere Ordinalwerte und damit einen niedrigere Vorrangstellung. Auf diese Weise wird das Überschreiben eines vorhandenen Eigenschaftswerts zu einem späteren Zeitpunkt im Anwendungslebenszyklus, z. B. während der Anwendungsassemblierung oder -installation, unterstützt.
Dynamische Eigenschaftswerte
Obwohl eine ordnungsgemäß entworfene Mikroserviceanwendung die Verfügbarkeit über mehrere Anwendungsneustarts hinweg aufrecht erhält, sollten Änderungen an Konfigurationswerten einer Anwendung vorzugsweise ohne Neustart der Anwendung zur Verfügung stehen. Die Eigenschaftswerte einer Konfiguration, die von registrierten ConfigSource-Objekten bereitgestellt werden, können mit beliebigen aktualisierten Werte aktualisiert werden, die ConfigSources zur Verfügung stellt. Die Häufigkeit, mit der ConfigSources abgerufen und beliebige Werte aktualisiert werden, wird von der Java-Systemeigenschaft microprofile.config.refresh.rate gesteuert. Die Einheiten werden in Millisekunden angegeben und der Standardwert ist 500, d. h., die von ConfigSources einer beliebigen Konfiguration bereitgestellten Werte werden in ungefähr einer halben Sekunde zur Verfügung gestellt.
Nicht programmgestützte Konfigurationsquellen wie die Dateien microprofile-config.properties werden nach der Erstellung der Erstkonfiguration nicht dynamisch neu gelesen.
Damit Wertaktualisierungen nach der Injektion von Eigenschaften sichtbar werden, könne Sie ein ConfigValue-Objekt verwenden. Dieses Objekt hat Getter für den Konfigurationseigenschaftswert und Optional<T> des Konfigurationseigenschaftswerts, die den aktuellen Wert zurückgeben. Beispiel:
@Inject
@ConfigProperty(name="propertyName3")
Provider<MyClass> propertyName3;
MyClass mc = propertyName3.get();
Sie können auch sehen, dass die Klasse ConfigValue generisch ist und zum Abrufen einer Eigenschaft eines bestimmten Typs verwendet werden kann, wenn ein geeigneter Converter vorhanden ist.
Konfigurationscaching
Zur Unterstützung der Effizienz speichert ein ConfigProvider die Konfiguration, die von seiner Methode getConfig für eine bestimmte mit dem ClassLoader angegebene Anwendung (oder ein Modul) zurückgegeben wird, im Cache. Wenn die Konfiguration mit ConfigBuilder generiert wurde, wird das Konfigurationsobjekt nicht zwischengespeichert. Der ConfigProviderResolver im Paket org.eclipse.microprofile.config.spi jedoch enthält eine registerConfig-Methode, die verwendet werden kann, um Config-Objekte in den Cache zu stellen und eine releaseConfig-Methode, um das Config-Objekt freizugeben.
Weitere Informationen zur Implementierung der MicroProfile-Config-API in Liberty finden Sie unter MicroProfile Configuration project site.