API "MicroProfile Config"

Konfigurationsinjektion

Die API " MicroProfile Config" erfasst die Standardkonfigurationsquellen und Konfigurationsquellen, die von Java ServiceLoader configsourcesgeladen werden, und wird später in diesem Abschnitt erläutert. Es ist möglich, Java CDI (Contexts and Dependency Injection) zu verwenden, um das Konfigurationsobjekt direkt in eine Anwendung einzufügen.

@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 in unaufbereiteter Form wie Java-Standardeigenschaften 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;

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 erfasst die Standardkonfigurationsquellen und Konfigurationsquellen, die von Java ® ServiceLoader configsourcesgeladen werden.

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 einer Reihe von Positionen stammen, einschließlich Eigenschaftendateien und Benutzerklassen, die entweder von der Anwendung registriert oder mit dem Java ServiceLoader -Muster 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:

1. Prozessumgebungsvariablen werden in die Konfiguration eingeschlossen. Liberty zeigt Umgebungsvariablen für Hostprozesse in der Java-Methode System.getenv() und fügt zusätzlich Eigenschaften aus der Datei server.env des Servers hinzu. Diese Variablen stehen daraufhin der API "MicroProfile Config" zur Verfügung.
2. Die über System.getProperties() verfügbaren Java-Systemeigenschaften sind in der Konfiguration enthalten. Liberty fügt Eigenschaften aus den Dateien bootstrap.properties und jvm.options des Servers zu den Java-Systemeigenschaften hinzu.
3. 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 auch von Java-Standardeigenschaftendateien verwendet wird. Für eine Liberty -Anwendung kann die Position des Verzeichnisses META-INF als Unterverzeichnis im Stammverzeichnis einer JAR-Datei oder im Verzeichnis WEB-INF\classes\META-INF\ für eine WAR-Datei oder in einer JAR-Datei im Verzeichnis "lib" einer EAR-Datei oder in einer JAR-Datei einer gemeinsam genutzten Bibliothek auf Serverebene angegeben werden. 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 ConfigBuilderregistriert werden. Auf diese Weise wird diese Benutzerklasse später in Konfigurationen eingeschlossen, die der Builder erstellt.

MySource source = new MySource();
builder.withSources(source);

Konfigurationsquellen mit dem Java-Muster "ServiceLoader" laden

Das Java-Muster ServiceLoader kann auch verwendet werden, um angepasste Konfigurationsquellenobjekte zu lokalisieren. 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 auch Eigenschaften als Java-Objekttypen mit einer generizisierten Methode abrufen, die den Typ des gewünschten Eigenschaftsobjekts verwendet. 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 Typen: boolean, Boolean, int, Integer, long, Long, float, Float, double, Double, Duration, LocalTime, LocalDate, LocalDateTime, OffsetDateTime, OffsetTime, Instantund URL.

Variablen eines beliebigen dieser Typen können direkt injiziert oder mithilfe des generizisierten getValue -Aufrufs abgerufen werden. Wenn der Zeichenfolgewert der Eigenschaft mithilfe der relevanten valueof-, parse-oder Konstruktormethode erfolgreich in den Typ konvertiert werden kann, indem ein einzelner Zeichenfolgeparameter verwendet wird.

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);

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 lokalisieren, wenn ihre paketqualifizierten Klassennamen in einer Servicedatei im Format ${CLASSPATH}/META-INF/services/org.eclipse.microprofile.config.spi.Converterangezeigt werden.

Beide Standardconverter, die in der Implementierung der MicroProfile Config-API enthalten sind, und Converter, die mit dem Java ServiceLoader -Muster erkannt werden, sind für alle Konfigurationen verfügbar.

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.

Für Versionen des Features mpConfig vor Version 1.4 können die Eigenschaftswerte einer Konfiguration, die von registrierten ConfigSource-Objekten bereitgestellt werden, mit beliebigen aktualisierten Werten aktualisiert werden, die ConfigSources zur Verfügung stellt. Die Häufigkeit, mit der ConfigSources abgefragt und alle Werte aktualisiert werden, wird durch die 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.

Die Art und Weise, wie zwischengespeicherte Werte aus der MicroProfile -Konfiguration abgerufen werden, wurde mit dem Feature mpConfig-1.4 geändert. Weitere Informationen finden Sie im Blog zu Open Liberty.

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. Zum 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.