Listenwert
Wertauflöser - Kurzfassung
Zweck: Ermöglicht den Schreib- oder Lesezugriff auf genau einen existierenden oder neu zu erstellenden Eintrag einer als Eingabewert vorliegenden "Liste".
Siehe auch: Liste modifizieren, Erzeuge Liste
Der Listenwert-Wertauflöser ermöglicht den Schreib- oder Lesezugriff auf genau einen existierenden oder neu zu erstellenden Eintrag einer als Eingabewert vorliegenden "Liste".
Als Eingabewert bzw. Bezugsobjekt muss ein konkretes Datenobjekt bereitgestellt werden, dass als "Liste" behandelt werden kann.
Der Zugriff auf einen Listeneintrag per Listenwert-Wertauflöser impliziert unter keinen Bedingungen das Erzeugen der übergeordneten Liste.
Für den Parameter Modus stehen vier Optionen zur Verfügung, die man paarweise gruppieren kann:
Die Modi Wert (vom Anfang) und Wert (vom Ende) zielen vorrangig darauf ab, einen bestehenden Listeneintrag für einen Lese- oder Schreibzugriff als Rückgabewert bereitzustellen.
Die Modi Hinzufügen (am Anfang) und Hinzufügen (am Ende) dienen zum Erweitern der Liste um einen Eintrag, der für einen Lese- oder Schreibzugriff als Rückgabewert bereitgestellt wird.
Der Parameter Offset definiert dabei die Indexposition des angeforderten bzw. eingefügten Listeneintrags relativ zum Bezugspunkt (Anfang/Ende der Liste) für den gewählten Modus.
Typischerweise wird der Parameter Offset durch die Direkteingabe einer Ganzzahl in der Konfiguration statisch definiert.
Ein Offset-Wert von 0 verweist dabei immer direkt auf den Bezugspunkt.
Ganzzahlige Offset-Werte <0 verweisen auf Positionen vor dem Bezugspunkt.
Ganzzahlige Offset-Werte >0 verweisen auf Positionen nach dem Bezugspunkt.
Um den Wert für den Parameter Offset dynamisch - also: zur Laufzeit variabel - zuweisen zu können, muss der entsprechende Ganzzahlwert über eine Variable bereitgestellt werden, deren Name in der Konfiguration als Textwert anstelle eingegeben wird.
►HINWEIS◄ Verweist die Konfiguration für den Offset auf eine Variable, die zur Laufzeit nicht belegt ist oder deren Wert nicht in eine Ganzzahl umgewandelt werden kann, wird ein Offset von 0 angenommen.
►WICHTIG◄ Welche Datentypen können einer Liste hinzugefügt werden?
Einer "Liste", die z. B. per Erzeuge Instanz-Wertauflöser mit dem Typ "Liste" (java.util.List) oder per Erzeuge Liste-Wertauflöser ohne Einträge angelegt wurde, können Einträge beliebiger unterschiedlicher Datentypen zugewiesen werden.
Als Datentyp für Listeneinträge gilt in diesen Fällen der übergeordnete Datentyp "Objekt" (Object), der Zuweisungen jeder Art ermöglicht.
Andererseits kann eine "Liste" mit einem spezifischen Datentyp verknüpft sein, z. B. in den folgenden Situationen:
Wenn die Erzeuge Liste-Ereignisaktion zum Initialisieren einer Liste mit Einträgen desselben Typs verwendet wird, dann wird dieser Typ mit der "Liste" verknüpft und erscheint dann auch im Typhinweis für den Rückgabewert des Wertauflösers (z. B. Long[]).
Wenn eine Erzeuge Liste-Ereignisaktion zum Initialisieren einer Liste mit Einträge unterschiedlicher Typen verwendet wird, wird die "Liste" mit einem übergeordneten Typ verknüpft, der alle enthaltenen Datentypen abdeckt (z. B. "Schnittstelle > Benutzer" für Benutzer und Gastbenutzer).
In diesem Fall sind Zuweisungen von Instanzen der abgedeckten konkreten Datentypen (z. B.: Benutzer oder Gastbenutzer) immer möglich.
Das Erzeugen einer Instanz des übergeordneten Datentyps über einen der Hinzufügen-Modi des Listenwert-Wertauflösers wird dagegen ggf. nur im Client-Kontext unterstützt und ist bedingt sinnvoll.
Wenn eine Suche-Ereignisaktion die "Ergebnisliste" einer Suche nach Instanzen eines bestimmten Entitätstyps (s. Gastbenutzer) in eine Variable schreibt, enthält die Variable eine Liste, die für Listeneinträge den Typ "Gastbenutzer" definiert.
Wenn der Listenwert-Wertauflöser zum Hinzufügen eines Eintrags zu einer "Liste" dienen soll, die für Listeneinträge einen spezifischen Datentyp erwartet, sind folgende Szenarien zu unterscheiden:
Der hinzuzufügende Eintrag entspricht dem erwarteten Datentyp für Listeneinträge.
Dann wird er hinzugefügt.Der Eintrag entspricht dem erwarteten Datentyp nicht, aber es wird eine automatische Typumwandlung in einen erwarteten Datentyp unterstützt.
Dann wird der Eintrag soweit möglich (s. Fall 3) umgewandelt und hinzugefügt.
►WICHTIG◄ Für die automatische Typumwandlung können spezifische Regeln je Ausführungskontext (Server/Client) gelten.
Im Server-Kontext kann z. B. der Textwert "2.5e3" in den Long-Wert 2500 umgewandelt und zu einer Long[]-Liste hinzugefügt werden, im Client-Kontext scheitert die Typumwandlung (s. Fall 3).
►HINWEIS◄ In diesem Zusammenhang gilt das Abrufen einer Entität ausgehend von einem Long-Wert, der in anderen Zusammenhängen (z. B. Eingabeobjekt (Typsicher) oder Variable) als Referenz auf deren "ID" (id) interpretiert wird, nicht als Typumwandlung unterstützt. Allerdings wird beim Versuch einer Long[]-Liste eine Entität als Eintrag hinzuzufügen, automatisch der Long-Wert aus dem Feld "ID" (id) extrahiert.Der Eintrag entspricht einem abweichenden Datentyp, für den keine automatische Typumwandlung in den erwarteten Datentyp vorgesehen ist oder eine Typumwandlung wäre vorgesehen (s. Fall 2), scheitert aber für den konkreten Wert des Eintrags.
Dann wird der Eintrag nicht hinzugefügt. Dabei wird keine Fehlermeldung ausgelöst.
►ANMERKUNG◄ Mit dem Listenwert-Wertauflöser können beim Hinzufügen von Listeneinträgen nicht unbedingt dieselben Ergebnisse erzielt werden, wie mit der Liste modifizieren-Ereignisaktion (s. Liste modifizieren / Hinzufügen).
Konfiguration
Modus |
Parameter |
Wirkung |
Wert (vom Anfang) |
Offset (Ganzzahl) |
... ermittelt in der per Verkettung übergebenen Liste ausgehend vom Anfang das Element an der per Offset spezifizierten Position.
Falls der Offset auf eine Position vor dem Anfang oder nach dem Ende der Liste verweist, werden ggf. mehrere leere Elemente bis zur adressierten Listenposition ergänzt, falls der Wertauflöser auf der linken Seite einer Zuweisung z. B. per Setze Wert verwendet wird. |
Wert (vom Ende) |
Offset (Ganzzahl) |
... ermittelt in der per Verkettung übergebenen Liste ausgehend vom Ende das Element an der per Offset spezifizierten Position.
Falls der Offset auf eine Position vor dem Anfang oder nach dem Ende der Liste verweist, werden ggf. mehrere leere Elemente bis zur adressierten Listenposition ergänzt, falls der Wertauflöser auf der linken Seite einer Zuweisung z. B. per Setze Wert verwendet wird. |
Hinzufügen (am Anfang) |
Offset (Ganzzahl) |
... erzeugt in der per Verkettung übergebenen Liste an der ausgehend vom Anfang per Offset spezifizierten Position ein neues Element und gibt es zurück.
Falls der Offset auf eine Position vor dem Anfang oder nach dem Ende der Liste verweist, werden mehrere leere Elemente bis zur adressierten Listenposition ergänzt, ohne dass eine Wertzuweisung an das zurückgegebene Element erfolgt. |
Hinzufügen (am Ende) |
Offset (Ganzzahl) |
... erzeugt in der per Verkettung übergebenen Liste an der ausgehend vom Ende per Offset spezifizierten Position ein neues Element und gibt es zurück.
Falls der Offset auf eine Position vor dem Anfang oder nach dem Ende der Liste verweist, werden mehrere leere Elemente bis zur adressierten Listenposition ergänzt, ohne dass eine Wertzuweisung an das zurückgegebene Element erfolgt. |
Beispiele
Lesezugriff auf den ersten Eintrag einer sortierten Liste
Für eine gegebenes Firmenkonto (s. Firmen) soll eine Regel genau dann zutreffen, wenn die Firma der Session im Listenfeld "Übergeordnete Firmen" (parentCompanies) nicht nur enthalten, sondern unter allen dort gelisteten Firmen auch diejenige mit der geringsten "ID" (id) ist.
Konfiguration:
In einem Kontext, in dem das zu prüfende Firmenkonto als Bezugsobjekt gilt (ggf. eine Mit-Regel) wird eine Verknüpfung wie im Screenshot rechts abgebildet:
|
|
Lesezugriff auf einen zufälligen Eintrag aus einer Liste
Aus einer gegebenen Vorauswahl für Benutzer die als Liste per Variable candidates gegeben ist, soll ein "Kandidat" zufällig ausgewählt werden, für den ein Eigenes Aktionsevent (SEND_EMAIL) ausgelöst werden soll.
Konfiguration:
Alle notwendigen Schritte sind im Aktionsblock einer Ausführen mit-Ereignisaktion konfiguriert, die als temporäres Bezugsobjekt über den Parameter Objekt-Wertauflöser die Listenvariable candidates mit der Liste der in Frage kommenden Benutzer definiert:
|
|
Schreibzugriff: Zusätzlichen Listeneintrag erstellen
Beim Kopieren eines Firmenkontos soll automatisch sichergestellt werden, dass die als "Besitzer" (ownerId) des Orginals angegebene Firma auch in der Liste "Übergeordnete Firmen" (parentCompanies) enthalten ist.
Konfiguration:
Der Screenshot rechts zeigt die Konfiguration für eine Ereignisbehandlung, die auf "Kopieren" (s. Allgemein (Ereignisse)) als Auslösendes Ereignis reagiert. Als Prüfende Regel wird eine Typprüfung ausgeführt, um sicherzustellen, dass ein "Firmenkonto" kopiert wird. Als einzige Aktion bei bestandener Regel wird eine Setze Wert-Ereignisaktion verwendet:
|
|
►HINWEIS◄ Der Datentyp für das Listenfeld "Übergeordnete Firmen" (parentCompanies) ist "Eindeutige Liste" (Set), was im Beispiel zwei wichtige Auswirkungen auf das Hinzufügen hat:
Ist der hinzuzufügende Long-Wert bereits in der Liste enthalten, enfält das Hinzufügen (ohne Fehlermeldung). Es muss also nichts unternommen werden, um Duplikate zu verhindern.
Einstelllungen für Modus und Offset haben nur bedingt Einfluss auf die Position eines hinzugefügten Eintrags, da die Klasse "Eindeutige Liste" (Set) die Reihenfolge der Einträge eigenmächtig handhabt.
►ANMERKUNG◄ Strenggenommen sollte noch sichergestellt werden, dass die Aktion bei bestandener Regel nur ausgeführt wird, wenn das "Besitzer" (ownerId)-Feld im Original-Firmenkonto einen Wert >0 enthält. Falls dort zum Zeitpunkt des Kopierens kein Besitzer ausgewählt sein sollte, lautet der ownerId-Wert nämlich -1. Dieser Wert sollte nicht der Liste der "Übergeordneten Firmen" (parentCompanies) hinzugefügt werden.
Schreibzugriff: Bestehenden Listeneintrag ersetzen
Aus einer gegebenen komma-separierten Liste von Parametern (im Beispiel statischer Text: YEAR=2024,WEEK=42,AREA=7) soll der zweite Parameter durch eine neue Zeichenfolge (im Beispiel: MONTH=10) ersetzt werden.
Anschließend soll die Zeichenfolge für die Parameterliste URL-gerecht (mit "&" als Trennzeichen anstelle des Kommas) in eine Variable params geschrieben werden.
Konfiguration:
Im Kontext einer Ausführen mit-Ereignisaktion wird der Parameter Objekt-Wertauflöser genutzt, um die Eingangsliste von Parametern bereitzustellen:
Ergebnis: (Textwert von Variable params) YEAR=2024&MONTH=10&AREA=7 ►ANMERKUNG◄ Natürlich könnte man dasselbe Ergebnis auch auf anderen Wegen erreichen (z. B. Text ersetzen), aber die hier vorgestellte Methode löst die Aufgabenstellung sehr übersichtlich und robust, |
|
Lesezugriff zum Schreiben: Bestehenden Listeneintrag verändern
In Anlehnung an das vorherige Beispiel sei dieselbe "Parameterliste" nun nicht mehr als Zeichenfolge sondern als Liste von Objekten mit den Feldern name und value gegeben.
Im Kontext einer Ereignisbehandlung soll der Eigenschaft value für den vorletzten Listeneintrag (Parameter "WEEK") der Wert 48 zugewiesen werden.
►HINWEIS◄ Der Listenwert-Wertauflöser wird im folgenden Beispiel primär zum Lesen des Eintrags genutzt. Dieser Zugriff ermöglicht allerdings indirekt einen Schreibzugriff auf ein Feld des enthaltenen Objekts.
Konfiguration:
Im Kontext einer Ausführen mit-Ereignisaktion wird der Parameter Objekt-Wertauflöser genutzt, um die Eingangsliste von Parametern bereitzustellen:
|
|
Ergebnis: [{"name":"YEAR","value":"2024"}, |
{ |
Schreibzugriff: Zusätzlichen Listeneintrag "einschieben"
In Anlehnung an das vorherige Beispiel soll an der vorletzten Position ein zusätzlicher "Parameter" mit dem Namen (name) "COUNTRY" und dem Wert (value) "NL" eingeschoben werden.
Konfiguration:
In der rechts gezeigten Konfiguration wurde gegenüber dem vorherigen Beispiel nur der Aktionsblock verändert:
►WICHTIG◄ Diese Konfiguration funktioniert in dieser Form ausschließlich im Client-Kontext, wo der "Hinzufügen"-Modus ohne weitere Vorkehrungen die Anlage eines neuen Objekts für den zusätzlichen Parameter unterstützt. Im Server-Kontext muss dagegen explizit dafür gesorgt werden, dass das hinzuzufügende Objekt als "Client-Objekt" erstellt wird, sonst laufen die Wertzuweisungen per Setze Werte ins Nichts. Im Allgemeinen könnte man dies über einen Erzeuge Instanz mit Werten-Wertauflöser erreichen, dessen Rückgabewert insgesamt als hinzuzufügender Listeneintrag zugewiesen wird. |
|
Die im Screenshot rechts aufgezeigte Alternative zeigt, wie die obige Konfiguration auf für den Server-Kontext lauffähig gemacht werden kann:
Das Ergebnis lautet mit dieser Variante für Server-Kontext und Client-Kontext gleich: { Dagegen würde im Server-Kontext mit der ursprünglichen Konfiguration an der vorletzten Position nur ein leerer Objekt-Eintrag ohne Feldwerte eingefügt: { "class": "java.lang.Object" } |
|
Schreibzugriff: Listeneintrag hinzufügen mit Typumwandlung
Eine Liste wird beim Erzeugen als Liste von Long-Werten definiert. Nachträglich soll ein Wert eingefügt werden, der über einen Benutzereingabe (Wertauflöser) als Textwert (String) bereitgestellt wird.
Konfiguration:
Im Objekt-Wertauflöser einer Ausführen mit-Ereignisaktion wird mit dem Erzeuge Liste-Wertauflöser eine Liste von statischen Long-Werten erzeugt. Im Aktionsblock soll an der zweiten Position ein "fehlender" Wert ergänzt werden, der über den Benutzereingabe (Wertauflöser) vom Benutzer abgefragt wird.
Da die Liste für Einträge den Typ Long vorsieht, muss auch der hinzugefügte Eintrag diesem Typ entsprechen. Sofern die eingegebene Zeichenfolge in eine Ganzzahl umgewandelt werden kann, wird ein Long-Wert eingefügt. Anderenfalls wird kein Eintrag hinzugefügt. |
|
►WICHTIG◄ Für die Typumwandlung können spezifische Regeln bzw. Einschränkungen für den Ausführungskontext (Server/Client) relevant sein:
|