Literale Projektion

Projektion - Kurzfassung

Zweck: Gibt im Kontext einer Suche einen simplen Festwert zurück.

images/download/attachments/78251658/image-2023-10-24_11-29-0-version-1-modificationdate-1698139752387-api-v2.png

Eine Literale Projektion gibt im Kontext einer Suche einen Festwert zurück, der ausschließlich durch die Wert-Konfiguration für den Parameter Literal bestimmt ist.

Die Literale Projektion wird häufig (und oft auch mehrfach) im Kontext einer Textverkettungsprojektion verwendet, um statische Komponenten zu einem verketteten Text beizusteuern.

Konfiguration

Parameter

Typ

Beschreibung

Name

String

Der optionale Parameter Name kann verwendet werden, um der Projektion einen (Alias-)Namen zuzuweisen.

  • Wenn kein Name angegeben ist, wird als Spaltenname (sofern relevant) das String-Abbild des Wertauflösers aus der Wert-Konfiguration für das Literal verwendet, der den Rückgabewert erzeugt. "Statische Wertauflöser" liefern dabei in der Regel ihren Wert bzw. ein String-Abbild davon (z. B. "true")..
    HINWEIS◄ Der automatisch erzeugte Spaltenname eignet sich nur in Ausnahmefällen als Spaltenname. Sofern die Literale Projektion überhaupt relevant für den Namen einer Ausgabespalte ist, empfiehlt es sich daher für die Spalte ausdrücklich einen (Alias-)Namen anzugeben.

Literal

unbestimmt

Die Wert-Konfiguration bestimmt einen Rückgabewert, der einmalig ermittelt wird und als Konstante in die Ausführung der Abfrage auf der Datenbank eingeht.

  • Eine Literale Projektion wird also nicht etwa für jede Zeile individuell "aufgelöst", die von der Datenbank zurückkommt.

Per Standard wird ein Text-Wertauflöser (s. Statische Werte) vorgeschlagen, da die Rückgabe einer Zeichenfolge der häufigsten Verwendung für einen statischen Wert entspricht.

Technisch können beliebige Wertauflöser (einzeln oder in Kombination, s. Verketteter Wertauflöser) verwendet werden, um ein Literal zu definieren. Allerdings eignen sich nicht alle Datentypen als Rückgabewert für ein Literal.

  • Im Allgemeinen können komplexe Werte (Datenobjekte mit mehreren Feldern z. B. ein "Datum mit Zeit", eine "Zahl mit Einheit" oder ein Dynamischer Aufzählungswert) nicht verarbeitet werden.

  • Nur in besonderen Fällen werden bestimmte Datentypen automatisch in in einen für die Literale Projektion geeigneten Datentyp übersetzt (z. B. "Statischer Aufzählungswert" → Long für das "Ordinal").

Beispiele

Typisches Beispiel: Textverkettung mit statischen Komponenten

Die Literale Projektion wird besonders häufig eingesetzt, um in einer Projektion einer CSV- oder Tupel-Suche Feldinhalte mit statischen Textzeichen in einer Textverkettungsprojektion zu verbinden.

Im folgenden Beispiel soll in einer Suche auf der Entität Orte ein Hinweis auf das "Bundesland" (state) eingeklammert an den Ortsnamen (placeName) angehängt werden.

Der Screenshot zeigt eine Textverkettungsprojektion mit vier Textkomponenten:

  • An Position 1 und 3 greift je eine Feldprojektion auf ein Feld der Entität zu.

  • An Position 2 und 4 ergänzt je eine Literale Projektion eine statische Zeichenfolge, durch die die verkettete Zeichenfolge strukturiert wird:

    • Das erste Literal " (" enthält ein Leerzeichen und die öffnende Klammer.

    • Das zweite Literal ")" enthält nur eine schließende Klammer.

HINWEIS◄ Alle verwendeten Projektionen verzichten hier auf eine Angabe für den Parameter Name. Effektiv wird deshalb der Spaltenname für die Textverkettungsprojektion wird daher systematisch aus den Standard-Namen für die verketteten Projektionen zusammengesetzt. Die Literale steuern dabei das komplette Literal bei.


Laufzeitbeispiel:

placeName (state)
Neukirchen (Oberösterreich)
Neukirchen (Schleswig-Holstein)
Neukirchen (Hessen)
Neukirchen (Bayern)

images/download/attachments/78251658/image-2023-10-24_9-7-1-version-1-modificationdate-1698131233688-api-v2.png

Einfaches Beispiel: Nummernkreiswert ins Abfrageergebnis schreiben

Bei jedem Aufruf einer Suche soll über einen Nummernkreiswert-Wertauflöser eine eindeutige Zeichenfolge generiert werden, die einerseits den ausführenden Benutzer (Benutzer der Session) über seine ID (id) identifiziert und andererseits eine "Laufnummer" für die Anfrage enthält.

Konfiguration:

HINWEIS◄ Damit eine Literale Projektion im Suchergebnis erscheinen kann, muss eine Tupel- oder CSV-Suche ausgeführt werden. Im Beispiel gehen wir von einer CSV-Suche für eine nicht näher bezeichnete Entität aus.

Der Screenshot zeigt drei Projektionen für die (CSV-)Suche, von denen die erste - eine Literale Projektion - aufgeklappt dargestellt ist:

  • Der Parameter Name mit dem Wert "Search_ID" beschriftet die Spalte in der Ausgabe (s. u.).

  • Dei Wert-Konfiguration für das Literal verwendet den Nummernkreiswert-Wertauflöser für den zu diesem Zweck eingerichteten Nummernkreistyp "XF_SEARCH_CONTROL", um über diesen einmalig einen Wert zu beziehen, der als Konstante für die Projektion zugewiesen wird.

Die weiteren Projektionen mit den (Alias-)Namen "Booking" und "Status" beinhalten die eigentliche Nutzlast unseres Abrufs.

images/download/attachments/78251658/image-2023-10-19_17-4-52-version-1-modificationdate-1697727895880-api-v2.png

Laufzeitbeispiele:

Erster Abruf der CSV-Suche

Späterer Abruf der CSV-Suche

Search_ID,Booking,Status
USR:1901#QRY:1000007,RE01230858,NEW
USR:1901#QRY:1000007,RE01230857,NEW
USR:1901#QRY:1000007,RE01230856,NEW
USR:1901#QRY:1000007,RE01230849,NEW
USR:1901#QRY:1000007,RE01230846,NEW
USR:1901#QRY:1000007,RE01230845,NEW
USR:1901#QRY:1000007,RE01230841,NEW
USR:1901#QRY:1000007,RE01000000,NEW
Search_ID,Booking,Status
USR:1901#QRY:1000009,RE01230859,NEW
USR:1901#QRY:1000009,RE01230858,NEW
USR:1901#QRY:1000009,RE01230857,NEW
USR:1901#QRY:1000009,RE01230856,REJECTED
USR:1901#QRY:1000009,RE01230849,NEW
USR:1901#QRY:1000009,RE01230846,NEW
USR:1901#QRY:1000009,RE01230845,CONFIRMED
USR:1901#QRY:1000009,RE01230841,NEW
USR:1901#QRY:1000009,RE01000000,CONFIRMED
  • Der zweite Lauf ergibt im Vergleich zum ersten veränderte Statuswerte für einige Buchungen und eine zusätzliche neue Buchung.

Einfaches Beispiel: Einen Booleschen Wert "umcodieren" (z. B. in Klartext)

Über Felder mit Booleschen Werten können einer Entität qualitative Merkmale binär zu- oder abgesprochen werden. In einer direkten Projektion für so ein Feld erscheint dann jeweils ein Boolesche Wert (true/false), ohne dass beim Betrachten einer Ausgabezeile ersichtlich wäre, was dies konkret bedeuten soll.

Die "Lesbarkeit" der Daten in einem Suchergebnis kann dann gesteigert werden, indem anstelle des Booleschen Werts in jeder Ausgabezeile eine Textkennung zugeordnet wird, die das Vorhandensein oder Fehlen des ge-flag-ten Merkmal beschreibt.

Im folgenden sehr einfachen Fall soll der Status eines Benutzerkontos (s. Benutzer) anhand des Booleschen Felds "Aktiv" (active) in einer Projektion als Klartext "umcodiert" werden, sodass der Text "ACTIVE" oder "INACTIVE" erscheint.

Konfiguration:

HINWEIS◄ Damit eine Literale Projektion im Suchergebnis erscheinen kann, muss eine Tupel- oder CSV-Suche ausgeführt werden. Im Beispiel gehen wir von einer CSV-Suche für die Entität "Benutzer" (User) aus.

Der Screenshot zeigt zwei Projektionen für die Ausgabe einer Liste von Benutzerkonten mit einem klar verständlichen Hinweis darauf, ob das jeweilige Konto aktiv ("ACTIVE") ist oder nicht ("INACTIVE"):

  • Die erste Projektion mit dem Namen "ACCOUNT_STATUS" verwendet eine Wenn ( Case ) Projektion, um das Boolesche Feld "Aktiv" (active) des Benutzerkontos durch eine Feld Einschränkung auszuwerten, die erfüllt ist, wenn das active-Feld den Wert true enthält.

  • Die zweite Projektion soll das Benutzerkonto namentlich identifizieren - per Feldprojektion auf das Feld "Benutzername" (username).

images/download/attachments/78251658/image-2023-10-23_16-55-7-version-1-modificationdate-1698072918442-api-v2.png

Laufzeitbeispiel:

Im Ergebnis der CSV-Suche zeigt die Spalte ACCOUNT_STATUS unmittelbar verständlich an, ob das jeweilige Konto aktiv ist oder nicht.

Die Ausgabe von true/false wäre nur in Verbindung mit dem Spaltennamen verständlich.

ACCOUNT_STATUS,ACCOUNT_NAME
ACTIVE,mjmartinez123
ACTIVE,jmustermann
INACTIVE,jmmustermann
INACTIVE,jdsmith0815
....

Besondere Verwendung: Literale Projektion als Prüfwert in einer Feld Einschränkung

Konfiguration:

Der Screenshot zeigt die Konfiguration für die Einschränkung einer Eigenen Übersicht für Firmen auf der Grundlage einer ODER-Verknüpfung von zwei Instanzen der Feld Einschränkung:

  • Die erste Feld Einschränkung (links; zugeklappt) prüft, ob im Feld "Metatyp" (metaType) der Firma der Firmen-Metatyp "Firma" (COMPANY) ausgewählt ist. Dieses Kriterium definiert die Einschränkung, die für alle anderen Rollen als die Rolle "Administrator" greifen soll.

  • Die zweite Feld Einschränkung (rechts; aufgeklappt) soll feststellen, ob es sich bei der Rolle der Session um die Rolle "Administrator" handelt. Ist dies der Fall, dann wirkt die Feld Einschränkung "relaxierend" wegen der ODER-Verknüpfung "relaxierend" für das andere Kriterium, sprich: Ist ein "Administrator" angemeldet, dann wird die Einschränkung für den "Metatyp" effektiv nicht beachtet.

    • Als Vergleichswert (rechts) innerhalb der Feld Einschränkung kann direkt ein Rolle-Wertauflöser verwendet werden, um die "Administrator"-Rolle als Fixwert zu definieren.

    • Als Prüfwert (links) innerhalb der Feld Einschränkung kommt dagegen aus formalen Gründen nur eine Projektion in Frage. Hier verwenden wir die Literale Projektion, in der der Rolle der Session-Wertauflöser eingesetzt werden kann. Da dieser eine Entität des Typs "Rolle" (Role) zurückgibt, also ein komplexes Datenobjekt, müssen wir noch einen Objekt-Feld-Wertauflöser verketten, um aus dem Feld "ID" (id) einen als Literal geeigneten simplen Fixwert (hier: Long) zu erhalten.

      HINWEIS◄ Wie im Screenshot zu sehen, lösen wir auch im Vergleichswert (rechts) per Objekt-Feld-Wertauflöser explizit das für den Vergleich relevante "ID"-Feld auf, obwohl die Einschränkung dank einer automatische Typumwandlung (Entität → Long/id) auch ohne dies funktionieren würde.

images/download/attachments/78251658/image-2023-10-24_10-21-49-version-1-modificationdate-1698135720878-api-v2.png

ALTERNATIVE Konfiguration:

Die rechts dargestellte Konfiguration löst die Aufgabe gleichwertig allerdings noch etwas eleganter:

  • Die erste Feld Einschränkung (links; zugeklappt) wurde unverändert beibehalten.

  • Die zweite Feld Einschränkung (rechts; aufgeklappt) fungiert wieder als "Ausnahmeregel", also um die Einschränkung für den "Metatyp" zu neutralisieren, wenn ein "Administrator" angemeldet ist:

    • Den Prüfwert (links) definieren wir wiederum über eine Literale Projektion. Allerdings beziehen wir als Literal diesmal den Booleschen Rückgabewert einer Rollenregel über einen Regelwert-Wertauflöser. Das ist spätestens dann ein erheblicher Vorteil, wenn für die "Ausnahme" für mehr als eine Rolle gelten soll.

    • Als Vergleichswert (rechts) benötigen wir hier nur einen Wertauflöser für einen statischen Booleschen Wert true (s. Statische Werte).

ANMERKUNGEN◄ Über den Regelwert-Wertauflöser können nach diesem Schema beliebige Regeln in die Einschränkung einbezogen werden, was u. a. den Zugriff auf Zuordnungskriterien als Sub-Zuordnungskriterium ermöglicht. Allerdings ist zu berücksichtigen, dass die Rückgabewerte von Regeln auf diesem Weg nur als Konstante ins Spiel kommen, Sie können nicht auf Felder der gesuchten Entität angewendet oder in deren Kontext ausgewertet werden.

Liefert dagegen z. B. eine Feldprojektion einen Prüfwert aus einem Bool-Feld der gesuchten Entität kann diesem ein Boolescher Vergleichswert aus einem Regelwert gegenübergestellt werden, ohne dass dieser (auf der rechten Seite im Vergleich) zu diesem Zweck in eine Literale Projektion "verpackt" werden müsste.

images/download/attachments/78251658/image-2023-10-24_10-47-57-version-1-modificationdate-1698137289737-api-v2.png