Map-Wert

Wertauflöser - Kurzfassung

Zweck: Adressiert den Schlüssel einer Map oder das Feld eines "Client-Objekts" im Eingabewert für einen Lese- oder Schreibzugriff.

Tooltip

• Verwendung: Der Wertauflöser erwartet als Eingabewert entweder eine Map oder ein "Client Objekt". Er ermöglicht den Lese- oder Schreibzugriff auf einen Schlüssel bzw. ein Feld mit dem per Schlüssel definierten Namen. Abhängig vom Kontext (Lese-/Schreibzugriff, Client/Server) werden wie beim Variable-Wertauflöser Funktionen zur Typprüfung, Typumwandlung oder zum Nachschlagen von Entitäten oder Aufzählungswerten verwendet werden (Details s. Handbuch).

• Parameter:

  • Der Parameter Schlüssel definiert den Schlüsselwert in einer Map bzw. den Feldnamen eines Objekts. Während ein Feldname als String definiert sein muss. eigenen sich als Schlüsselwerte beliebige Datentypen.

  • Die optionalen Parameter Wert Typ und Ist Liste von deklarieren den Datentyp für den Wert, der gelesen oder zugewiesen werden soll.

• Hinweis: Im Unterschied zum Objekt-Feld-Wertauflöser ermöglicht der Map-Wert-Wertauflöser den Zugriff auf Felder eines "Client Objekts" über erst zur Laufzeit dynamisch bestimmten Feldnamen.

Siehe auch: Alle Map-Schlüssel-Wertauflöser, Variable-Wertauflöser

Der Map-Wert-Wertauflöser adressiert den Schlüssel einer Map oder das Feld eines "Client-Objekts" im Eingabewert für einen Lese- oder Schreibzugriff.

►WICHTIG◄ Für ein "Client-Objekt" als Eingabewert werden nur Schlüssel vom Typ String akzeptiert.

Für einen Schreibzugriff muss der Map-Wert-Wertauflöser analog zum Variable-Wertauflöser oder einem Objekt-Feld-Wertauflöser auf der linken Seite einer Wertzuweisung (z. B. per Setze Wert oder Setze Werte) verwendet werden.

Sonderfälle:

• Wenn als Eingabewert kein Datenobjekt des Typs Map (java.util.Map) oder "Client-Objekt" vorliegt, lautet der Rückgabewert beim Lesezugriff "Kein Wert" ($null). Ein Schreibzugriff ist wirkungslos.

• Wenn keine Konfiguration für den Parameter Schlüssel vorliegt oder diese zur Laufzeit "Kein Wert" ($null) als "Schlüssel" ergibt, lautet der Rückgabewert beim Lesezugriff "Kein Wert" ($null). Ein Schreibzugriff ist wirkungslos.
  ►HINWEIS◄ Ein leerer String kann in einer Map als Schlüssel und in einem "Client-Objekt" als Feldname verwendet werden, "Kein Wert" ($null) dagegen nicht.

• Wenn der parametrierte Schlüssel im Eingabewert nicht als Schlüsselwert bzw. Feldname verwendet wird, lautet der Rückgabewert bei einem Lesezugriff "Kein Wert" ($null).

  • Ein Schreibzugriff fügt einer Map einen Eintrag mit dem angegebenen Schlüssel und dem durch die Zuweisung bestimmten Wert hinzu.

  • Einem "Client-Objekt" wird bei einem Schreibzugriff das über den Schlüssel adressierte Feld nur dann hinzugefügt, wenn der Schlüssel ein String ist.

• Wenn der parametrierte Schlüssel bei einen Schreibzugriff bereits als Schlüsselwert bzw. Feldname im Eingabewert verwendet wird, überschreibt der zugewiesene Wert den vorhandenen.

• Das Zuweisen von "Kein Wert" ($null) zu einem bestehenden Schlüssel ist möglich.

  • Handelt es sich beim Eingabewert um eine Map, wird der auf $null gesetzte Schlüssel selbst dadurch nicht aus der Map gelöscht.

  • Handelt es sich beim Eingabewert um ein "Client-Objekt", wird das auf $null gesetzte Feld dagegen aus dem "Client Objekt" gelöscht.

Die Parameter Wert Typ und Ist Liste von deklarieren einerseits im Kontext der Konfiguration den für nachfolgende Elemente erwarteten Datentyp.

Andererseits sind die beiden Parameter bei Lese- und Schreibzugriffen auf Map-Werte abhängig vom Kontext für die folgenden Funktionen analog zum Eingabeobjekt (Typsicher)-Wertauflöser relevant:

►WICHTIG◄ Falls bei einem Schreibzugriff der Map-Wert-Wertauflöser mit den Parametern Typ und/oder Ist Liste von auf der Zielseite der Zuweisung (z. B. links in einer Setze Wert-Ereignisaktion) eingesetzt wird, führt das Scheitern einer Typprüfung, Typumwandlung oder des Nachschlagens eines Aufzählungswerts nicht etwa zur Zuweisung von "Kein Wert" ($null), sondern zu einem "stillen" Abbruch der Zuweisung. Der als Ziel definierte Schlüssel behält also seinen vorherigen Wert unverändert bei und der Ausführungskontext wird ohne Fehlermeldung fortgesetzt. Lediglich im Kontext von Tests ist der Abbruch über den Reiter "Log" eine UnsupportedOperatonException nachvollziehbar.

Konfiguration

Als Eingabewert erwartet der Map-Wert-Wertauflöser immer eine Map (java.util.Map) oder ein "Client-Objekt".

►HINWEIS◄ Der Eingabewert muss ggf. über den Erzeuge Instanz-Wertauflöser (mit "Typ" java.util.Map) erzeugt werden, damit über den Map-Wert-Wertauflöser lesend und schreibend zugegriffen werden kann.

Beim Zugriff auf "Listen" als Werte sind außerdem folgende Aspekte zu beachten:

• Ist die Option Ist Liste von abgewählt (Standard) und kein Wert Typ ausgewählt dann findet keine Typprüfung statt. Man kann auf diesem Weg also nicht spezifizieren, dass nur ein Rückgabewert "erwünscht" ist, der keine Liste ist.
  
  

• Solange die Option Ist Liste von abgewählt ist, wird eine Liste wie jedes andere in einer Variablen gespeicherte Datenobjekt direkt zurückgegeben bzw. zugewiesen.
  
  

• Ist beim Zugriff auf eine Liste die Option Ist Liste von abgewählt, dann kann der Parameter Wert Typ für eine Typumwandlung für die Liste als Ganzes genutzt werden.
  Beispiel: Eine Schlüssel route enthält eine normale "Liste" (java.util.List) von String-Werten, die über IATA-Codes von Flugziele entlang eines "Reiseschemas" definiert:
  In JSON-Notation könnte die Liste im Wert für den Schlüssel route für eine "Rundreise" z. B. so aussehen: [MUC,JFK,GIG,CDG,MUC]Wird auf die Variable route per Wert Typ "Liste" (java.util.List) oder ohne Angabe eines Typs zugegriffen, entspricht der Rückgabewert exakt dem gespeicherten Wert.
  Erfolgt der Zugriff auf den Schlüssel route dagegen per Wert Typ "Eindeutige Liste" (java.util.Set), dann wird die "Liste" in eine "Eindeutige Liste" umgewandelt, was die Reihenfolge und die Anzahl der Einträge verändern kann.
  Im konkreten Beispiel könnte der Rückgabewert so aussehen: [GIG,CDG,MUC,JFK]

Beispiele

Lesezugriff auf einen Schlüssel einer Map oder ein Client Objekt (als Standardwert)

Eine Ereignisbehandlung soll ausgewählte Inhalte (hier: name und id) aus einer per Variable author übergebenen Map in einer Benachrichtigung wiedergeben.

Falls die Variable author keine Map enthält, sollen Feldwerte aus einem "Client Objekt" angezeigt werden, das zu diesem Zweck aus statisch hinterlegtem JSON-Text generiert wird.

Laufzeitbeispiel:

Konfiguration:

Daten in einer Map sammeln (Schreibzugriff)

Eine Suche (Ereignisaktion) mit dem Modus "Suchwert" liefert in einer Variablen users eine Liste von Benutzerkonten (s. Benutzer), die hier als "Benutzergruppe" bezeichnet werden soll.

Die Daten der "Benutzergruppe" sollen hinsichtlich der Kombinatorik für die Felder "Sprache" (locale) und "Land" (address.countryCode) ausgewertet werden. Das Auswertungsergebnis soll als Map bereitgestellt werden, die als eindeutige "Schlüssel" alle in der Benutzergruppe verwendeten Sprachen verwendet. Jedem Schlüssel soll als Wert eine Liste der "Herkunftsländer" von Benutzern zugeordnet werden, in deren Konto die jeweilige Sprache ausgewählt ist.

►ANMERKUNG◄ Eine Auswertung der Kombinatorik ist auch innerhalb der Suche (Ereignisaktion) denkbar, wenn entsprechende Kriterien für eine Gruppierung verwendet werden. Im Beispiel soll die Auswertung der Kombinatorik allerdings ausdrücklich entkoppelt vom Abruf der Detaildaten für die Benutzergruppe und mit einer Map als Ergebnis erfolgen.

Konfiguration:

Server-XML einer Map mit Länder-Listen in Sprache-Schlüsseln

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:core="CORESYSTEM">
   <entry>
      <key enumName="core:Locale" name="en" xsi:type="core:DynamicEnumValue"/>
      <value xsi:type="set">
         <entry enumName="core:Country" name="US" xsi:type="core:DynamicEnumValue"/>
         <entry enumName="core:Country" name="DE" xsi:type="core:DynamicEnumValue"/>
       </value>
   </entry>
   <entry>
      <key enumName="core:Locale" name="de" xsi:type="core:DynamicEnumValue"/>
      <value xsi:type="set">
         <entry enumName="core:Country" name="DE" xsi:type="core:DynamicEnumValue"/>
         <entry enumName="core:Country" name="IT" xsi:type="core:DynamicEnumValue"/>
         <entry enumName="core:Country" name="AT" xsi:type="core:DynamicEnumValue"/>
      </value>
   </entry>
   <entry>
      <key enumName="core:Locale" name="fr" xsi:type="core:DynamicEnumValue"/>
       <value xsi:type="set">
         <entry enumName="core:Country" name="MU" xsi:type="core:DynamicEnumValue"/>
      </value>
     </entry>
</map>

Dies Auswertung der Kombinatorik von Sprache und Land in der ausgewerteten "Benutzergruppe" ergibt im Klartext:

• Die Sprache "Englisch" (en) ist für je einen oder mehrere Benutzer aus den USA (US) und Deutschland (DE) ausgewählt.

• Die Sprache "Deutsch" (de) ist für je einen oder mehrere Benutzer aus Deutschland (DE), Italien (IT) und Österreich (AT) ausgewählt.

• Die Sprache "Französisch" (fr) ist für einen oder mehrere Benutzer aus Mauritius (MU) ausgewählt.

Dynamisch bestimmte Feldnamen in einem Client-Objekt (Schreibzugriff)

Eine Ereignisbehandlung soll einen zufälligen "Wurf" mit einer parametrierbaren Anzahl an Würfeln (Variable numberOfDice) simulieren und ein "Client-Objekt" zurückgeben, das die geworfenen Augenzahlen in systematisch benannten Felder (die0, die1, die2, ...) wiederspiegelt.

Laufzeitbeispiel: "Wurf mit 3 Würfeln" (numberOfDice=3)

Client-Objekt in JSON-Notation

{
	"die2": {
		"class": "java.lang.Long",
		"value": "1"
	},
	"die1": {
		"class": "java.lang.Long",
		"value": "3"
	},
	"die0": {
		"class": "java.lang.Long",
		"value": "6"
	}
}

Konfiguration:

Der Knackpunkt für die Konfiguration ist, dass der typischerweise für Wertzuweisungen an Felder eines Objekts verwendete Objekt-Feld-Wertauflöser keine dynamische Zuweisung für den Feldnamen sondern nur eine statische Auswahl eines Felds in der Konfiguration unterstützt.

Daher muss der Map-Wert-Wertauflöser verwendet werden, dessen dynamisch definierbarer Schlüssel im Kontext eines Client-Objekts als Feldname interpretiert wird.