enhancement
major
minor
major
minor
major
#29630
TL Views: Ein in Blöcke unterteilter, transaktionsbasierter Job-Körper für „ <start-job> “ – skriptgesteuerte Initialisierung / Elemente / Schritte / Abschluss, eine Transaktion pro Block, Wiederholungsversuche und Überspringen auf Elementebene, Phasen und Fortschritt, die sich aus den Schritten ableiten
Problem
<start-job> (#29600) führt seinen Hauptteil in einem Worker-Thread außerhalb einer Transaktion aus; „das Speichern der Ergebnisse des Jobs ist Aufgabe der nachfolgenden Aktionen“. Das gilt für eine Berechnung, nicht für einen Import: Der Trac-Import des Issue-Trackers tl-dev erstellt oder aktualisiert über XML-RPC etwa 15.000 Tickets mit Kommentaren und Anhängen, und sein Vorgänger in der klassischen Benutzeroberfläche (ChunkedProgressCommand in der App) hat jeden Block von 200 Elementen in einer eigenen Transaktion festgeschrieben, mit Wiederholungs- und Überspringungsmöglichkeiten pro Element, sodass der Speicherverbrauch begrenzt bleibt, bei einem Fehler gegen Ende der Ausführung das Festgeschriebene erhalten bleibt und eine erneute Ausführung idempotent fortgesetzt wird.
Nach der Portierung auf die React-Benutzeroberfläche kann ein <start-job function="…"> -Body weder persistente Objekte erstellen (new() außerhalb einer Transaktion schlägt fehl) noch Blöcke festschreiben: TL-Script verfügt über keine Funktion, die einen Block in einer Transaktion ausführt (modelSearchConf.config.xml bietet try, log, revisionForCommit, aber nichts, was eine Transaktion startet oder festschreibt), und ScriptJobBody eröffnet keine. Ein einzelnes <with-transaction> nach dem Job würde 15.000 Tickets in einem Commit zusammenfassen und bei einem Fehler alles verlieren.
Die App verfügt daher über einen eigenen generischen Java-JobBody (<body class="…"> innerhalb von <start-job>), der mit init, elements, chunk-size, steps und finish-Skripten konfiguriert ist, der pro Chunk eine Transaktion eröffnet, Wiederholungsversuche und Überspringungen pro Element durchführt, Phase, Fortschritt und Meldungen über den JobMonitor meldet und die log(...) -Zeilen der Skripte in die Meldung des Monitors spiegelt – die Logik des klassischen ChunkedProgressCommand, neu implementiert als Job-Body.
Anfrage
Einer der beiden in der Engine, sodass eine Anwendung einen transaktionalen Langzeitjob ohne Java deklariert:
- ein in Blöcke unterteilter, transaktionaler Job-Body neben dem ScriptJobBody: <body class="…ChunkedScriptJobBody" chunk-size="200"><init>…</init><elements>…</elements><step>…</step><finish>…</finish></body>, eine Transaktion pro Chunk, Wiederholungsversuche und Überspringen pro Element werden als Meldungen gemeldet, Phasen werden aus den Schritten abgeleitet; oder
- eine TL-Script-Funktion, die einen Block in einer Transaktion ausführt, transaction(fn) (Commit bei Rückkehr, Rollback bei Fehler), die ein Skript-Job-Körper dann pro Block verwendet, zusammen mit try für das Überspringen pro Element.
Die erste Variante passt direkt zur Phasenanzeige von <start-job>; die zweite ist die kleinere Primitive.
Lösung
Die erste Option: Der in Blöcke unterteilte, transaktionale Job-Körper ist Teil der Engine und befindet sich im Paket von <start-job> (com.top_logic.layout.view.job) als zwei Klassen:
- ChunkedJobBody – der transaktionale Rahmen mit Java-Hooks (init, elements, step, finish sowie hasInit / hasFinish / stepCount, die dem Rahmen mitteilen, welche davon vorhanden sind): Er durchläuft die Arbeitselemente in Blöcken einer konfigurierten Größe, führt für jeden Block ein eigenes Commit in einer eigenen Transaktion durch, wiederholt fehlgeschlagene Blöcke Element für Element und überspringt die Elemente, die nicht verarbeitet werden können (jedes davon wird in einer Meldung benannt und gezählt), meldet die Phasen des Jobs (Vorbereitung, eine pro Durchlauf, Abschluss), berichtet über den Fortschritt eines Durchlaufs in Blöcken und reagiert auf eine Abbruchanforderung zwischen zwei Blöcken. Ein Fehler bei der Vorbereitung oder beim Abschluss beendet den Job mit einem eigenen Fehler. Ein in Java geschriebener Import baut direkt auf dieser Klasse auf.
- ChunkedScriptJobBody – das Framework mit seinen an TL-Script gebundenen Hooks:
<start-job job="importJob" cancelable="true">
<body class="com.top_logic.layout.view.job.ChunkedScriptJobBody" chunk-size="200">
<init-label><en>Projektstruktur</en></init-label>
<init>Auftrag -> Anfrage -> { … ; $project }</init>
<elements>Auftrag -> Projekt -> $project.get(`…#tickets`)</elements>
<steps>
<step>
<label><en>Tickets</en></label>
<expr>Auftrag -> Chunk -> Projekt -> $chunk.foreach(t -> …)</expr>
</step>
</steps>
<finish-label><en>Index</en></finish-label>
<finish>Auftrag -> Projekt -> { … ; $project }</finish>
</body>
</start-job>
Gemeinsamer Zustand. „init“ wird einmal in einer eigenen Transaktion ausgeführt, und was es zurückgibt, ist der Zustand, den jedes nachfolgende Skript erhält: „elements“ liefert die Arbeitselemente daraus, jeder Schritt wird mit dem Chunk und dem Zustand aufgerufen, „finish“ mit dem Zustand. Der Zustand ist das, was die Durchläufe erreichen müssen – der Container, in dem die Elemente erstellt werden, eine Zuordnung mehrerer Objekte oder ein temporäres Objekt, das von den Durchläufen verändert werden muss. Ohne „init“ ist das erste Argument, mit dem der Job gestartet wurde, der Zustand.
Berichterstellung. Jedes Skript wird mit dem Monitor des Jobs als erstem Argument aufgerufen, genau wie die Funktion eines <start-job>, und gibt Berichte mit $job.jobMessage(…); aus; Die Durchläufe sind die Phasen, die auf dem Display angezeigt werden, mit „init-label“, den Bezeichnungen der Schritte und „finish-label“ als Text (Standardwerte: „Vorbereitung“, „Durchlauf n“, „Abschluss“), sodass der <start-job> für einen solchen Körper keine <phases> deklariert. Ein Bericht aus einem Chunk heraus reagiert sofort auf einen Abbruch: Der gerade ausgeführte Chunk wird zurückgesetzt, die zuvor festgeschriebenen Chunks bleiben erhalten. Der log(...) -Spiegel des App-Körpers wird nicht übernommen.
Ergebnis: Der Job endet mit dem, was „finish“ zurückgibt; ohne „finish“ mit einem Text, der angibt, wie viele Elemente verarbeitet und wie viele übersprungen wurden. Dieser Text wird in beiden Fällen als letzte Meldung des Jobs gesetzt, sodass die Anzeige die Zahlen anzeigt.
„elements“ wird einmalig ausgewertet, ist schreibgeschützt und erfolgt außerhalb jeglicher Transaktion. Die TL-Script-Primitive „transaction(fn)“ ist nicht Bestandteil dieses Tickets.
Demo und Dokumentation. Die Long-Job-Demo von tl-demo-react (demo/long-job-demo.view.xml) verfügt über einen „chunked import“, der in einem Durchgang 500 Tickets erstellt (jede 97. Nummer schlägt fehl und wird übersprungen) und in einem nächsten Durchgang jedes zweite Ticket schließt, sowie über die „chunked removal“ der erstellten Tickets; docs/faq/react-view-layer.md beschreibt den Hauptteil im Abschnitt über lang laufende Jobs.