Kontext

Eine TopLogic-Anwendung musste bisher die Parent-Kette tl-parent-app → tl-parent-core → tl-parent-build → tl-parent-all erben. Diese Kette vermischt die Versionsverwaltung (rund 270 verwaltete Abhängigkeiten), den Build-Lebenszyklus (Annotation-Prozessor, Web-Fragment-Wars, Nachrichtengenerierung, App-Paket, Start mit tl-ide-jetty usw.) und Vorgaben für Properties. Ein Projekt mit eigenem Firmen-Parent oder ein Modul in einem bestehenden Multi-Modul-Projekt konnte TopLogic deshalb nicht nutzen. Auch die Funktionsauswahl war unmodular: Der Archetyp tl-archetype-app schrieb jedes Modul einzeln ins erzeugte pom.xml, die Gruppierung veraltete mit jeder Engine-Version.

Erweiterung

Anwendungen und Fragment-Module brauchen keinen TopLogic-Parent mehr:

• BOM tl-bom: die Versionen aller TopLogic-Module und Bibliotheken. Ein Projekt mit eigenem (oder ohne) Parent importiert sie (<scope>import</scope>). tl-bom ist zugleich Parent von tl-parent-all; für Projekte, die tl-parent-app erben, ändert sich nichts, auch das Überschreiben von Versions-Properties funktioniert dort weiter.
• Packaging tl-app / tl-fragment: tl-maven-plugin mit <extensions>true</extensions> baut ein solches Projekt mit der Konfiguration von tl-parent-app bzw. tl-parent-core (gleiche Version wie das Plugin), als wären diese der oberste Parent seiner eigenen Parent-Kette. Das Projekt und sein eigener Parent haben Vorrang. Übernommen werden Build, Plugin-Verwaltung, Properties, Profile und die Abhängigkeiten der Parents; die Versionen kommen aus dem eigenen Import von tl-bom (Maven prüft Abhängigkeitsversionen, bevor Erweiterungen laufen). BOM- und Plugin-Version müssen übereinstimmen: Verwaltet die importierte tl-bom eine andere Version von tl-maven-plugin als die des Plugins, bricht der Build mit einer Meldung ab. Empfohlen ist ein Property tl.version für BOM und Plugin. Die m2e-Lifecycle-Mappings der Parents werden für Eclipse übernommen. Das Packaging ist für Projekte außerhalb des Engine-Reaktors gedacht: Maven lädt Build-Erweiterungen vor dem Reaktor-Build, ein im selben Reaktor gebautes tl-maven-plugin steht dafür nicht zur Verfügung.
• Feature-Starter (Module vom Typ pom, verwaltet in tl-bom): tl-starter-react (React-Oberfläche inkl. Modelleditor tl-dev-tools), tl-starter-classic (klassische Oberfläche), tl-starter-ai (tl-ai-core, tl-chat, tl-ai-views, tl-ai-mcp-server, tl-ai-a2a, tl-layout-view-agent), tl-starter-ai-search (tl-ai-index, tl-ai-index-onnx). Eine Funktion wird durch eine Abhängigkeit ein- oder ausgeschaltet, auch nachträglich. Die Modulreihenfolge (Fragmente, Konfiguration) ist mit Startern identisch zur Einzelauflistung in der Reihenfolge des Starters. Ersetzt ein Projekt eine anders geordnete Einzelauflistung durch Starter, können voneinander unabhängige Fragmente ihre Position tauschen; das ändert nur die Reihenfolge zusammengeführter Dateien (metaConf.txt, theme.xml, Theme-Einstellungen, Tabs zusammengeführter Views).
• Demo-Anwendungen: tl-demo-react nutzt tl-starter-react, tl-demo nutzt tl-starter-classic, tl-ai-demo nutzt tl-starter-classic, tl-starter-ai und tl-starter-ai-search; die Anwendungen behalten ihren Parent tl-parent-app-internal (Packaging im Engine-Reaktor nicht möglich, s. o.). tl-ai-demo enthält damit zusätzlich tl-layout-view-agent und tl-graphic-blocks-server.
• Stylesheets von diagram-js: com.top_logic.umljs (diagram-js 15.9) und ext.io.bpmn.bpmn-js (bpmn-js 3.0.4) lieferten beide eine unterschiedliche Datei /style/diagram-js.css. Eine Anwendung mit beiden Modulen (z. B. klassische Oberfläche mit BPE) enthielt nur eine davon, abhängig von der zufälligen Reihenfolge der Fragmente; je nachdem waren UML-Diagramme bzw. der BPMN-Modellierer falsch gestylt. Jede Bibliothek liefert ihr Stylesheet jetzt unter eigenem Pfad (/style/umljs/diagram-js.css, /style/bpmn-js/diagram-js.css) und beschränkt es auf ihre eigenen Diagramme: die bpmn-js-Regeln auf .bjs-container, die Regeln von diagram-js 15.9 und uml-js.css per @scope auf das Diagramm-Element .djs-parent. Die globale Regel html, body {height: 100%; margin: 0} aus der Testseite von umljs ist aus uml-js.css entfernt.
• Debian-Paket: Der Build des Debian-Pakets (jdeb, Upload) liegt in tl-parent-app und ist per Vorgabe abgeschaltet (tl.deb.skip, tl.deb.skipDeploy); eine Anwendung setzt nur noch die tl.deb.*-Properties.
• Archetyp tl-archetype-app: erzeugt ein Projekt ohne Parent (Packaging tl-app, Import von tl-bom). Neue Optionen: moduleType = app | fragment (Fragment: META-INF/web-fragment.xml, ohne web.xml, deploy/, Debian-Paket, Docker, local.conf.xml.template, Start-/Setup-Launches), useAI (tl-starter-ai, bei klassischer Oberfläche zusätzlich tl-chat-classic), useAISearch (tl-starter-ai-search, setzt useAI voraus), useSSO (tl-security-auth-pac4j). ui wählt tl-starter-react und/oder tl-starter-classic. Die Option parentArtifactId entfällt. Ungültige Kombinationen brechen die Erzeugung mit einer Meldung ab. Die Sidebar-Fußzeile einer erzeugten Anwendung behält den TopLogic-Vermerk.
• Der Integrationstest des Archetyps läuft mit maven-archetype-plugin 3.4.1, führt damit das Post-Generate-Skript aus und prüft je Testprojekt (React-, klassische, kombinierte Anwendung, Fragment) die erzeugten Dateien und das POM.
• Der Entwicklerartikel application-project (in tl-core) beschreibt Archetyp, Projekt-POM, Firmen-Parent, Starter, Fragmente, Debian-Paket, die Umstellung eines bestehenden Projekts auf das Packaging und das weiterhin unterstützte Erben von tl-parent-app.

Die Konfiguration der LLM-Anbieter einer Anwendung mit KI-Modulen erzeugt der Archetyp nicht (#29965).

Test

• Archetyp-Integrationstest (mvn install -pl tl-archetype-app): vier Projekte werden erzeugt, mit Tests gebaut und geprüft.
• Mit den Vorgaben des Archetyps eine Anwendung erzeugen (mvn org.apache.maven.plugins:maven-archetype-plugin:3.4.1:generate -DarchetypeGroupId=com.top-logic -DarchetypeArtifactId=tl-archetype-app ...), bauen (mvn install) und starten (mvn exec:java): Das POM hat keinen Parent, die Anwendung startet mit der React-Oberfläche, Administration und Modelleditor funktionieren.
• Eine Anwendung mit eigenem Firmen-Parent: dessen Einstellungen gelten, übrige TopLogic-Vorgaben werden ergänzt.
• Ein erzeugtes Fragment (-DmoduleType=fragment) als Abhängigkeit einer Anwendung: es erscheint beim Start im Ressourcen-Stapel.
• Ein Projekt, dessen dependencyManagement tl-maven-plugin in einer anderen Version als der des Plugins führt: der Build bricht mit einer Meldung ab, die beide Versionen nennt.
• Demo-Anwendungen: Inhalt der App-Wars von tl-demo-react, tl-demo und tl-ai-demo vor und nach der Umstellung auf Starter vergleichen; außer den in tl-ai-demo hinzukommenden Modulen unterscheiden sie sich nur in der Reihenfolge zusammengeführter Dateien.
• tl-demo: Administration → Entwicklung → Prozess Editor → Ticketsystem: der BPMN-Modellierer zeigt Palette, Auswahlrahmen, Kontext-Pad und Ersetzen-Popup im Stil von bpmn-js 3.0.4. Administration → Entwicklung → Modell Editor → DemoTypes → Diagramm: das UML-Diagramm zeigt Palette mit Hintergrund und Rahmen sowie einen sichtbaren Auswahlrahmen.

Migration

Optional. Anwendungen, die tl-parent-app erben (Fragmente: tl-parent-core), bauen unverändert weiter; auch eine selbst konfigurierte Debian-Paketierung (Plugins jdeb, upload-maven-plugin aus einem älteren Archetyp) verschmilzt mit der Ausführung in tl-parent-app und erzeugt weiterhin genau ein Paket.

Umstellung auf das Packaging (sinnvoll für einen Firmen-Parent oder ein bestehendes Multi-Modul-Projekt), im POM des Projekts:

1. <parent> mit tl-parent-app / tl-parent-core entfernen; <groupId> und <version> explizit angeben, falls sie bisher vom Parent geerbt wurden.
2. <packaging>tl-app</packaging> (Fragment: tl-fragment) setzen und tl-maven-plugin mit <version>${tl.version}</version> und <extensions>true</extensions> unter <build><plugins> deklarieren.
3. Property tl.version mit der bisherigen Parent-Version anlegen und tl-bom in dependencyManagement importieren (<version>${tl.version}</version>, <type>pom</type>, <scope>import</scope>). BOM- und Plugin-Version müssen übereinstimmen.
4. Überschriebene Versions-Properties (z. B. jetty.version) wirken nicht mehr; die betreffende Bibliothek stattdessen mit Version im eigenen dependencyManagement deklarieren.
5. Die Repositories tl-releases und tl-snapshots als repository und pluginRepository deklarieren, sofern die Maven-Settings sie nicht liefern.
6. Die jdeb- und upload-maven-plugin-Blöcke sowie tl.deb.*-Properties mit Vorgabewert löschen.
7. Optional: einzelne Module einer Funktion durch ihren Starter ersetzen (tl-starter-react, tl-starter-classic, tl-starter-ai, tl-starter-ai-search). Unabhängige Fragmente können dabei ihre Position tauschen (siehe Feature-Starter).

Prüfung: mvn help:effective-pom und bei Anwendungen den Inhalt von target/<finalName>-app.war vor und nach der Umstellung vergleichen. Details im Entwicklerartikel application-project, Abschnitt "Switching a project from tl-parent-app to the packaging".

Eine Anwendung, die eigene Regeln für die diagram-js-Elemente (.djs-*) von UML-Diagrammen oder des BPMN-Modellierers definiert oder /style/diagram-js.css direkt referenziert, prüft ihr Styling: die Datei liegt jetzt unter /style/umljs/diagram-js.css bzw. /style/bpmn-js/diagram-js.css.