UX-Bridge - Entwicklerhandbuch

Ausgangspunkt für die Entwicklung im UX-Bridge-Kontext ist die Installation der Komponenten.

Dazu sollte zunächst das mitgelieferte Modul in den Server-Einstellungen des FirstSpirit-Servers installiert werden. Dadurch wird der UX-Bridge-Service gestartet und die UX-Bridge-Komponenten sind in den Projekten des FirstSpirit-Servers verfügbar.

Neben dem FirstSpirit-Modul ist auch die Installation des UX-Busses notwendig. Zur lokalen Entwicklung ist die Installation im Standalone-Betrieb empfohlen.

Weitere Informationen erhalten Sie in der UX-Bridge Installationsanleitung.

Die Architektur der UX-Bridge erlaubt es, die Entwicklung von Lösungen auf Basis der UX-Bridge auf zwei Rollen zu verteilen:

Werden die Rollen durch unterschiedliche Personen wahrgenommen, so sollte während der Konzeption ein gemeinsames Datenaustauschformat definiert werden. Hiermit ist das Datenformat gemeint, was durch die Vorlagen erzeugt und über den UX-Bus als Nachricht an den Adapter verschickt wird.

Das Datenaustauschformat bildet die Schnittstelle zwischen den Komponenten und damit auch zwischen den beiden Rollen. Aus Sicht des Vorlagenentwicklers handelt es sich hierbei um das Endprodukt seiner Arbeit. Für den (Web-)Applikationsentwickler stellt es den Input für den Adapter dar. Dabei wird seitens der UX-Bridge nur ein äußerer Container vorgegeben. Der Rest kann frei definiert werden (siehe auch Kapitel Ausgabekanal anlegen und befüllen).

Ein geschickt gewähltes Datenaustauschformat kann den Implementierungsaufwand deutlich reduzieren.

Folgende Fragestellungen können bei der Wahl helfen:

Um die UX-Bridge zu nutzen, sollte zunächst unter Projekteinstellungen → Vorlagensätze ein neuer Vorlagensatz (UXB) angelegt werden. Als Präsentationskanal sollte XML als Konvertierungsregel Unicode to XML und als Zieldateierweiterung xml konfiguriert werden.

Abbildung 1. Vorlagensatz anlegen

Die Konvertierungsregel Unicode to XML dient dazu, Sonder- und Steuerzeichen in korrespondierende XML-Entitäten umzuwandeln, die sonst in XML als Teil der Markupsprache interpretiert werden bzw. ungültige Zeichen darstellen würden.

Um Nachrichten an den UX-Bus zu schicken, sind in der entsprechenden Vorlage, die die Nachrichten erzeugen soll, die Felder, die im Datenaustauschformat definiert wurden, in Form von XML auszugeben.

Abbildung 2. Ausgabekanal im SiteArchitect

Vorgegeben ist lediglich folgende Struktur:

<uxb_entity uuid = String destinations = String  language = String command = String objectType = String>
 <uxb_content>
   […] definiertes Datenaustauschformat […]
 </uxb_content>
</uxb_entity>

Die Attribute language, command und objectType sind optional, haben sich aber bei den von e-Spirit implementierten Adaptern als hilfreich erwiesen.

Um die Daten von FirstSpirit in Nachrichten umzuwandeln, die vom UX-Bus weiterverarbeitet werden können, muss zwingend ein Auftrag angelegt oder ein bestehender Auftrag so erweitert werden, dass er XML generiert und dieses an den UXB-Service weiterreicht, der daraus eine Nachricht erzeugt und diese an den UX-Bus versendet. Der Auftrag kann später über einen Workflow gestartet werden. In diesem Kapitel sollen nun zwei Aufträge erklärt werden, die wahrscheinlich in jedem Projekt, welches die UX-Bridge nutzt, benötigt werden.

Teilgenerierung

Um neue Inhalte schnell auf der Webseite zu publizieren, bietet es sich an, einen Auftrag anzulegen bzw. so zu erweitern, dass er die folgenden beschriebenen Schritte durchführt und hierbei nur die neuen Inhalte generiert und veröffentlicht.

Ein typischer Generierungsauftrag, der die UX-Bridge nutzt, gliedert sich in mehrere Aktionen, wie nachfolgend beschrieben:

Abbildung 3. Auftragsübersicht

Zunächst sollten in einer Generierungsaktion die komplett statischen Seiten, die zur Anzeige auf der Webseite notwendig sind (z.B. News-Übersichtsseiten), generiert werden. Diese Generierungsaktion findet sich auch in den bisher üblichen Deployment-Aufträgen und muss dann nicht angepasst werden.

Im nächsten Schritt sollten dann die im vorherigen Schritt generierten Inhalte wie gewohnt auf den Webserver übertragen werden (im Beispiel über rsync). Auch in diesem Schritt sind in der Regel keine Anpassungen notwendig.

Um die UX-Bridge einzusetzen, ist danach eine neue, weitere Aktion hinzuzufügen, die mittels Skriptaufruf die Generierung für die UX-Bridge aktiviert:

UX-Bridge Generate. 

#! executable-class
com.espirit.moddev.uxbridge.inline.UxbInlineUtil

In der darauf folgenden Generierungsaktion sollten dann genau die Seite generiert werden (z.B. News-Detailseite), die das XML erzeugt, das an den UXB-Service weitergereicht werden soll. Wichtig zu beachten ist, dass in den erweiterten Eigenschaften auch der UXB-Vorlagensatz aktiviert wurde.

Abbildung 4. Aktivierung des Vorlagensatzes

Die Delta-Generierung in FirstSpirit 5 passt die Generierungsaktion automatisch so an, dass nicht mehr alle Seiten, sondern nur noch die gewünschte Seite generiert wird. Dazu kann z.B. in einem Workflowskript, das die Generierung anstößt, die zu generierende Seite an den Auftrag übergeben werden.

Die letzte Aktion UX-Bridge Statistics Report ist optional und ermöglicht es, die Durchlaufzeiten für die Nachrichten im UX-Bus bis zur Veröffentlichung auf der Webseite zu messen.

INFO  22.08.2012 09:59:54.631 (de.espirit.firstspirit.server.scheduler.ScheduleManagerImpl): starting task 'UX-Bridge Statistics Report' - schedule entry 'UX-Bridge-Test (News)' (id=5142)
INFO  22.08.2012 10:00:04.645 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Time for #uxb/pressreleasesdetails/UXB/EN/256 (postgres): 242ms
INFO  22.08.2012 10:00:04.645 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Time for #uxb/pressreleasesdetails/UXB/DE/256 (postgres): 224ms
INFO  22.08.2012 10:00:04.645 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): 2/2 deployed successfully (overall: 233ms, postgres: 233ms).
INFO  22.08.2012 10:00:04.646 (de.espirit.firstspirit.server.scheduler.ScheduleManagerImpl): finished task 'UX-Bridge Statistics Report' - schedule entry 'UX-Bridge-Test (News)' (id=5142)

Dazu ist folgender Skriptaufruf notwendig:

UX-Bridge Statistics Report. 

#! executable-class
com.espirit.moddev.uxbridge.inline.UxbResultHandler

Der Service wartet maximal den in der Servicekonfiguration der UX-Bridge definierten Zeitraum, bis die Antworten der Adapter ausgewertet werden. Kommt in diesem Zeitfenster keine Antwort, so gilt die Nachricht als fehlerhaft zugestellt. Da die Antwortzeiten je nach Nachricht und System variieren können, ist dieser Wert konfigurierbar.

Alternativ zu diesem maximalen Zeitraum für den gesamten Auftrag, kann ein Heartbeat konfiguriert werden. Hierfür wird ein maximaler Zeitraum konfiguriert, der zwischen zwei Heartbeat-Nachrichten vergehen darf. Es ist zu beachten, dass alle verwendeten Adapter einen Heartbeat senden müssen. Empfängt der ResultHandler zu lange keinen Heartbeat, wird der Auftrag als fehlerhaft gewertet und eine Timeout-Nachricht angezeigt. Das Versenden von Heartbeat-Nachrichten muss auf Adapterseite implementiert werden. Eine Beispielimplementierung befindet unter https://github.com/e-Spirit/uxbridge-samples/blob/master/newsWidget/adapter/hibernate/src/main/java/com/espirit/moddev/examples/uxbridge/newswidget/jpa/ArticleHandler.java

Zu beachten ist, dass jede Generierungsaktion, die zwischen UX-Bridge Activate Generation und UX-Bridge Statistics Report aufgerufen wird, eine UX-Bridge-Generierung durchführt. Soll im selben Auftrag eine weitere Generierung ins Dateisystem erfolgen, ohne dass zuvor das Skript UX-Bridge Statistics Report aufgerufen wurde, so muss vor dieser Generierung ein Skript zur Deaktivierung der UX-Bridge-Generierung eingefügt werden:

UX-Bridge Deactivate Generation. 

#! executable-class
com.espirit.moddev.uxbridge.inline.UxbDeactivate

Komplettabgleich

Es ist sinnvoll einen weiteren Auftrag anzulegen, der einen Komplettabgleich durchführt, um den Datenbestand im Content-Repository auf dem aktuellsten Stand zu halten. Hierfür müssen die in FirstSpirit gelöschten Daten ebenfalls auch im externen Repository gelöscht werden.

Es empfiehlt sich folgende Vorgehensweise:

cleanup-Skript. 

import com.espirit.moddev.uxbridge.api.v1.service.UxbService;
uxbService = context.getConnection().getService(UxbService.class);
uxbService.removeUxbEntriesByTime(context.getStartTime().getTime(), "news", "postgres,mongodb");

Historische Daten

Um historische Daten mittels der UX-Bridge zu generieren, muss eine neue Skript-Aktion vor der Aktion UX-Bridge - Activate Generation hinzugefügt werden z.B.

Skript. 

import java.util.Date;
Date d = new Date(114, 5, 24);
context.setStartTime(d);

Das gesetzte Datum wird dann in der folgenden Aktion (UX-Bridge - Activate Generation) berücksichtigt.

Auftrag Start / Ende im Adapter erkennen

Um im Adapter auf den Start bzw. das Ende eines Auftrags unter Umständen gezielt reagieren zu können, kann die UX-Bridge zu Beginn und am Ende der Generierung jeweils automatisch eine separate Nachricht versenden (siehe auch UX-Bridge Installationsanleitung).

Die Startnachricht besitzt dabei folgendes Format:

<uxb_entity projectName="PROJEKT_NAME" status="start" schedulerId="AUFTRAGS_ID" createTime="ZEITPUNKT_DER_NACHRICHT" projectId="PROJEKT_ID" startTime="STARTZEITPUNKT_DES_AUFTRAGS" />

Bei einer Vollgenerierung wird noch das Attribut command=“startMaintenanceMode“ hinzugefügt.

Die Endnachricht besitzt folgendes Format:

<uxb_entity projectName="PROJEKT_NAME" status="end" schedulerId="AUFTRAGS_ID" createTime="ZEITPUNKT_DER_NACHRICHT" projectId="PROJEKT_ID" startTime="STARTZEITPUNKT_DES_AUFTRAGS" />

Bei einer Vollgenerierung wird noch das Attribut command=“stopMaintenanceMode“ hinzugefügt.

Sollte bei einer Vollgenerierung die maximale Anzahl an erlaubten Fehlern bzw. Timeouts im Adapter überschritten werden, hat das Attribut command den Wert keepMaintenanceModeUp.

Root-Attribute erweitern

Die Wurzelknoten der über die UX-Bridge verschickten Nachrichten besitzen standardmäßig bereits einige Attribute, wie beispielsweise den Projektnamen oder die ID des Auftrags. Diese lassen sich durch beliebige, weitere Attribute erweitern. Zur Angabe dieser Root-Attribute muss dem Generierungsauftrag als erste Aktion das Skript Configure UXB Message Header hinzugefügt werden, welches den folgenden Inhalt besitzt:

Skript - Configure UXB Message Header. 

import java.util.HashMap;
attributeMap = new HashMap();
attributeMap.put("customAttribute1", "customAttributeValue1");
attributeMap.put("customAttribute2", "customAttributeValue2");
context.setProperty("uxbMessageRootAttributes", attributeMap);

Das Skript erzeugt eine HashMap, in der die gewünschten Attribute in Form von Key/Value-Paaren hinzugefügt werden können. Die HashMap wird anschließend an den Kontext des Auftrags übergeben, damit der UXBService während der Erzeugung der Nachrichten auf sie zugreifen kann.

Sollen bei der Nachrichtengenerierung Seiten übersprungen werden, so ist dies durch das setzen der Seitenvariable uxbSkipMessage möglich.

uxbSkipMessage. 

$CMS_SET(#global.pageContext["uxbSkipMessage"], true)$

Die Benutzung von stopGenerate (siehe Online Dokumentation für FirstSpirit → Vorlagenentwicklung → Vorlagensyntax → Systemobjekte → #global → vorschaubezogen → Abbruch einer Vorschau/Generierung) wird nicht unterstützt und führt in diesem Fall zu ungültigem XML und dadurch zu Fehlermeldungen im Log.

Die UX-Bridge kann zu Beginn der Generierung eine Nachricht mit erweiterten Projektinformationen verschicken (siehe UX-Bridge Installationsanleitung). Zu diesen Informationen zählen zurzeit die definierten Projektsprachen und Auflösungen.

Beispiel. 

<uxb_entity projectName="UXB" objectType="projectInfo" schedulerId="92460" createTime="1371037891875" projectId="88785"  startTime="1375346932923">
 <project key="UXB">
  <id>88785</id>
  <name>UXB</name>
  <languages>
   <language key="DE">
    <name>Deutsch</name>
    <abbreviation>DE</abbreviation>
    <isMasterLanguage>true</isMasterLanguage>
   </language>
  </languages>
  <resolutions>
   <resolution key="ORIGINAL">
    <name>Originalauflösung</name>
    <uid>ORIGINAL</uid>
    <height>0</height>
    <width>0</width>
    <isOriginal>true</isOriginal>
   </resolution>
  </resolutions>
 </project>
</uxb_entity>

Die Publikation von Inhalten über die UX-Bridge kann sowohl direkt über Skripte und Aufträge als auch indirekt über Workflows gestartet werden.

Release Workflow

Um Inhalte zu publizieren, muss ein bestehender Workflow lediglich um ein Workflow-Skript erweitert werden, das einen Auftrag startet, der neben Generierung und Deployment auch die XML-Nachrichten erzeugt und an den UXB-Service weiterreicht (siehe Kapitel Teilgenerierung).

Delete Workflow

Um Inhalte zu löschen, muss ein bestehender Löschworkflow um ein Workflow-Skript erweitert werden, das eine XML-Nachricht erzeugt, die an den UXB-Service weitergereicht wird.

Der Aufruf des UXB-Service im Skript lautet wie folgt, wobei msg (String) der XML-Nachricht entspricht:

Aufruf des UXB-Service. 

UxbService uxbService = context.getConnection().getService(UxbService.class);
uxbService.removeUxbEntry(msg);

Die XML-Nachricht folgt dabei folgendem Muster:

<uxb_entity uuid=STRING language=STRING destinations=STRING objectType=STRING command=STRING />

FirstSpirit erwartet eine Antwort in Form eines XML-Dokuments vom Adapter, nachdem eine Nachricht in ein Repository geschrieben wurde. Die Antwort wird sowohl bei einer erfolgreichen als auch bei einer fehlhaften Verarbeitung erwartet. Das Antwort-XML-Dokument ist wie folgt aufgebaut:

<uxb_entity command=STRING createTime= STRING destinations=STRING finishTime=STRING language=STRING path=STRING schedulerId=STRING startTime=STRING status=STRING uuid=STRING ><uxb_error>STRING </uxb_error></uxb_entity>