Erweiterungen des OSGi-Metatypservice
Die Liberty-Laufzeitumgebungs- und Entwicklertools erkennen einige Erweiterungen der OSGi-Metatypspezifikation, um komplexere Konfigurationen handhaben und eine bessere Darstellung in einer Benutzerschnittstelle erzielen zu können.
Metatyperweiterungen der Laufzeitumgebung
xmlns:ibm="http://www.ibm.com/xmlns/appservers/osgi/metatype/v1.0.0"
- ibm:alias
Die Aliaserweiterung wird verwendet, um einen verwendbaren Namen für die Konfiguration zu definieren und gleichzeitig das Risiko von Namenskonflikten bei Konfigurationselementen in der Datei server.xml zu verringern.
Das folgende Beispiel zeigt die Erweiterung "ibm:alias":
<OCD id="com.ibm.ws.jdbc.dataSource.properties" name="%properties" description="%properties.desc" ibm:alias="properties"> <AD id="username".../> </OCD>
In diesem Beispiel ist properties der verwendbare Name für die Konfiguration. Der Aliasname darf nicht identisch mit der ID sein.
Wenn der Eintrag "ibm:alias" in der Datei server.xml verwendet wird, muss er mit dem Namen der Produkterweiterung präfigiert werden. Der Name der Produkterweiterung für Erweiterungen, die in der Standardbenutzerposition installiert werden, ist usr. Bei Produkterweiterungen, die über eine Datei mit dem Namen Erweiterungsname.properties im Verzeichnis wlp/etc/extension im Installationsverzeichnis von Liberty definiert werden, entspricht der Name der Produkterweiterung dem Namen, der für Erweiterungsname ausgewählt wird.
Wenn beim Metatyp aus dem vorherigen Beispiel das Feature im Standardverzeichnis usr installiert wird, sind die folgenden Einträge Beispiele für gültige Einträge in der Datei server.xml:<usr_properties username="JANE"/>
<com.ibm.ws.jdbc.dataSource.properties username="JANE"/>
- ibm:type
Standardattributtypen werden in der Metatypspezifikation definiert. Es sind verschiedene erweiterte IBM® Typen verfügbar. Weitere Informationen finden Sie im Artikel Erweiterte Typen.
- ibm:reference
Das Referenzattribut gibt den OCD-Typ an, den eine PID referenziert. Er wird nur mit dem Attribut "ibm:pid" verwendet und unterstützt die Verschachtelung von Elementen in der Datei server.xml. Weitere Informationen finden Sie unter Konfigurationselemente verschachteln.
Das folgende Beispiel zeigt die ibm:reference-Erweiterung:
<AD id="fooRef" type="String" ibm:type="pid" ibm:reference="com.ibm.ws.foo".../>- ibm:final
Das letzte Attribut zeigt, dass der Wert nicht in der Konfiguration angegeben werden kann. Stattdessen wird immer der Standardwert des Metatyps verwendet. Verwenden Sie die Einstellung name="internal", um anzugeben, dass Tools diese Eigenschaft nicht anzeigen.
Das folgende Beispiel zeigt die ibm:final-Erweiterung:
<AD id="foo" name="internal" ibm:final="true" type="String" default=${someVariable}"/>- ibm:variable
Das Attribut "variable" wird verwendet, um eine Variable anzugeben, die als Standardwert verwendet werden soll, wenn keine Variable angegeben ist. Es werden nacheinander folgende Werte ausgewählt:
- Der Wert, der in der Datei server.xml angegeben ist.
- Der Wert, der als Systemeigenschaft angegeben ist, z. B. in der Datei bootstrap.properties.
- Der Standardwert aus dem Metatyp.
Das folgende Beispiel zeigt "ibm:variable":
<AD id="traceString" ibm:variable="trace.string" default=*.all=enabled".../>- ibm:unique
- Das Attribut unique gibt an, dass ein Konfigurationswert in allen Attributdefinitionen, die dieselbe eindeutige Attributgruppe verwenden, eindeutig sein muss. Die folgenden eindeutigen Attributgruppen werden unterstützt:
-
jndiName: Verwenden Sie diese Gruppe für Attribute, die einen Service mit der Eigenschaft "osgi.jndi.service.name" mit dem JNDI-Namen registrieren. Weitere Informationen enthält der Abschnitt Entwicklung mit dem JNDI-Standardnamespace in einem Liberty-Feature.
-
- Syntax des Standardwerts
Sie können die Syntax "${prop-name}" in Standardausdrücken verwenden, um Zeichenfolgen aus anderen Konfigurationseigenschaften zu erstellen.
Das folgende Beispiel zeigt die Syntax eines Standardwerts:
<AD id="httpEndpoint.target" name="internal" description="internal use only" ibm:final="true" required="false" type="String" default="(&(virtualHost=${id}) (enabled=true))"/>
Erweiterte Typen
- duration
Der Typ "duration" wird verwendet, um Zeiträume auszudrücken, und kann in verschiedenen Zeiteinheiten angegeben werden. Beispielsweise gibt "1h30m" einen Zeitraum von anderthalb Stunden an. "1d5h10s" bedeutet 1 Tag, 5 Stunden und 10 Sekunden.
In der folgenden Liste sind die verfügbaren Einheiten aufgelistet:
- d - Tage
- h - Stunden
- m - Minuten
- s - Sekunden
- ms - Millisekunden
Standardmäßig wird der vom Benutzer eingegebene Wert in Millisekunden angegeben, wenn der Typ "duration" verwendet wird. Zum Beispiel entspricht der Wert "10s" dem langen Wert "10000" im Wörterbuch. Wenn ein Benutzer einen Wert ohne Einheit angibt, wird dieser Wert in Millisekunden ausgewertet. Der Wert "10" wird beispielsweise als 10 Millisekunden ausgewertet. Sie können den Typ "duration" jedoch auch in einer anderen Einheit angeben. Wenn Sie beispielsweise den Wert "10" mit ibm:type="duration(s)" angeben, wird dieser Wert als 10 Sekunden ausgewertet und als 10 im Wörterverzeichnis gespeichert.
In der folgenden Liste sind die möglichen Typen aufgelistet:
- duration(h)
- duration(m)
- duration(s)
- duration(ms)
- duration
Es gibt keinen Unterschied zwischen der Angabe von "duration" und "duration(ms)".
Anmerkung:Bewährtes Verfahren: Geben Sie immer eine Einheit mit dem Wert an und drücken Sie den Wert in der Einheit aus, die am besten lesbar ist. Geben Sie beispielsweise anstelle von "7200" mit ibm:type="duration(s)" den Wert "2h" an.
Die folgenden Beispiele beziehen sich auf den Typ "duration":
- <AD id="timeout" type="String" ibm:type="duration(s)".../>
- <AD id="timeout" type="String" ibm:type="duration".../>
- Location
Der Typ "location" ermöglicht Tools der Benutzerschnittstelle, eine effizientere Darstellung von Attributen, die verschiedene Datei- und Verzeichnispositionen repräsentieren, vorzunehmen. Die Verarbeitung durch die Laufzeitumgebung bleibt davon unberührt. Das Wörterbuchobjekt ist immer eine Zeichenfolge.
Die folgenden Beispiele zeigen die möglichen Typen:
- location
- Referenziert eine Datei. Dies kann eine absolute Datei, eine relative Datei oder eine URL für eine Datei sein.
- location(file)
- Referenziert eine Datei mit einem absoluten oder relativen Dateipfad.
- location(dir)
- Referenziert ein Verzeichnis mit einem absoluten oder relativen Dateipfad.
- location(url)
- Referenziert eine Datei am Ende einer URL.
Das folgende Beispiel zeigt den Typ "location":
<AD id="location" name="%appmgr.location.name" description="%appmgr.location.desc" type="String" required="true" ibm:type="location"/>- Password
Der Typ "password" wird für Kennwortfelder verwendet. Wenn es verwendet wird, ist das Wörterbuchobjekt eine Instanz von com.ibm.wsspi.kernel.service.utils.SerializableProtectedString. Der Wert des Kennwortfeldes wird nicht in der Tracedatei protokolliert. In den Entwicklertools werden die Codierungsoptionen angezeigt, die für ein Kennwortfeld verwendet werden können. Die gültigen Codierungsoptinen sind xor und aes.
Das folgende Beispiel zeigt den Typ "password":
<AD id="password" type="String" ibm:type="password".../>- Hashverschlüsseltes Kennwort
Der Typ "passwordHash" ähnelt dem Typ "password" und wird für hashverschlüsselte Kennwortfelder verwendet. Wenn es verwendet wird, ist das Wörterbuchobjekt eine Instanz von com.ibm.wsspi.kernel.service.utils.SerializableProtectedString. Der Wert des hashverschlüsselten Kennwortfelds wird nicht in der Tracedatei protokolliert. In den Entwicklertools werden die Codierungsoptionen angezeigt, die für ein verschlüsseltes Kennwortfeld verwendet werden können. Die gültigen Codierungsoptionen sind xor, aes und hash.
Prüfen Sie ein neues Kennwort anhand eines hashverschlüsselten Kennworts mit der Methode PasswordUtil.encode(String, String, Map) und folgenden Parametern:- Neues Kennwort.
- Hashalgorithmus, der mit der Methode PasswordUtil.getCryptoAlgorithm abgerufen wird. Der Hashalgorithmus muss mit dem Algorithmus des hashverschlüsselten Kennworts übereinstimmen.
- Eigenschaftsobjekt, in dem eine der Eigenschaften PasswordUtil.PROPERTY_HASH_ENCODED für den Schlüssel und das hashverschlüsselte Kennwort für den Wert verwendet.
Das folgende Beispiel zeigt den Typ "passwordHash":
<AD id="hashedPassword" type="String" ibm:type="passwordHash".../>- pid
Der Typ "pid" wird verwendet, um ein anderes Objekt in der Konfiguration zu referenzieren. Er wird mit dem Attribut "ibm:reference" verwendet und unterstützt die Verschachtelung von Elementen in der Datei server.xml. Weitere Informationen finden Sie unter Konfigurationselemente verschachteln.
Das folgende Beispiel zeigt den Typ "pid":
<AD id="fooRef" type="String" ibm:type="pid" ibm:reference="com.ibm.ws.foo".../>- OnError
Der Typ "onError" erzeugt eine Instanz der onError-Auflistung im Wörterbuch. Die gültigen Werte sind: WARN, FAIL und IGNORE.
Das folgende Beispiel zeigt den Typ "onError":
<AD id="errorBehavior" type="String" ibm:type="onError".../>- token
Mit dem Typ "token" wird angegeben, dass alle Leerzeichen vor und hinter der Zeichenfolge in dem in der Konfiguration angegebenen Wert entfernt werden müssen.
Das folgende Beispiel zeigt ein mit dem Typ "token" definiertes Attribut:
<AD id="name" type="String" ibm:type="token" .../>
Metatyperweiterungen der Benutzerschnittstelle
xmlns:ibmui="http://www.ibm.com/xmlns/appservers/osgi/metatype/ui/v1.0.0"
- ibmui:localization
Die Lokalisierungserweiterung wird verwendet, um die Lokalisierungsdatei für Metatypen anzugeben. Die Lokalisierungsdatei für Metatypen wird verwendet, um die Umsetzungen für Kennungen und Beschreibungen anderer Benutzerschnittstellenerweiterungen zu suchen. In den meisten Fällen stimmt der Wert der Erweiterung "ibmui:localization" mit dem Lokalisierungsattribut im Element <Metadata> überein.
Das folgende Beispiel zeigt die Erweiterung "ibmui:localization":
<OCD id="com.ibm.ws.jdbc.dataSource.properties" name="%properties" description="%properties.desc" ibmui:localization="OSGI-INF/l10n/metatype"> <AD id="username".../> </OCD>
- ibmui:extraProperties
Die Erweiterung "extraProperties" wird verwendet, um anzu zeigen, dass eine beliebige Menge Konfigurationsattribute in dieser Konfiguration gesetzt werden kann.
Das folgende Beispiel zeigt die Erweiterung "ibmui:extraproperties":
<OCD id="com.ibm.ws.jdbc.dataSource.properties" name="%properties" description="%properties.desc" ibmui:extraProperties="true"> <AD id="username".../> </OCD>
Die Kennunge und die Beschreibung, die der Erweiterung zugeordnet sind, werden in der Lokalisierungsdatei für Metatypen (falls eine solche Datei mit der Erweiterung "ibmui:localization" angegeben ist), gesucht. Für die Erweiterungskennung wird zunächst der Schlüssel extraProperties.<OCD-ID>.name und dann der Schlüssel extraProperties.name überprüft. Für die Erweiterungsbeschreibung wird zuerst der Schlüssel extraProperties.<OCD-ID>.description und dann der Schlüssel extraProperties.description überprüft.
- ibmui:group
Die Erweiterung "group" wird verwendet, um anzugeben, dass das Attribut zu einer Gruppe gehört. In der Benutzerschnittstelle werden die Attribute, die mit derselben Gruppe annotiert werden, zusammengefasst.
Die folgenden Beispiele zeigen die Erweiterung "ibmui:group":
- <AD id="username" ibmui:group="userInfo".../>
- <AD id="password" ibmui:group="userInfo".../>
- <AD id="port" ibmui:group="hostInfo".../>
Die Gruppenkennung und die Beschreibung werden in der Lokalisierungsdatei für Metatypen (falls eine solche Datei mit der Erweiterung "ibmui:localization" angegeben ist), gesucht. Für die Gruppenkennung wird zunächst der Schlüssel <group.<OCD-ID>.name und dann der Schlüssel <group.name überprüft. Für die Gruppenbeschreibung wird zuerst der Schlüssel <group.<OCD-ID>.description und dann der Schlüssel <group.description überprüft.