Java-Quelldatei-Encoding auf UTF-8 umstellen

Die TopLogic-Engine verwendet historisch ISO-8859-1 als Quell-Encoding (project.build.sourceEncoding in den Parent-POMs, Eclipse-Settings, Resource-Bundles, Doclet-Generator). Das ist im Umgang mit modernen Werkzeugen, Browsern, Diff-Viewern und externen Editoren unhandlich und fuehrt regelmaessig zu Mojibake bei Umlauten.

Dieses Ticket stellt die Engine vollstaendig auf UTF-8 um.

Umfang

• *.java-Quelldateien neu kodiert (970+ Dateien im Engine-Reactor).
• *.properties-Dateien neu kodiert (handgepflegte Resource-Bundles unter WEB-INF/conf/resources und generierte META-INF/messages_*.properties).
• project.build.sourceEncoding=UTF-8 in den drei Parent-POMs.
• data.proto (msgbuf-Quelle in com.top_logic.graphic.blocks) hatte selbst U+FFFD-Replacements bei °`; repariert, damit msgbuf nicht den Fix in `ImageOrientation.java bei jedem Build ueberschreibt.
• Eclipse-Settings:
  • <project>, src/main/java, src/test/java auf UTF-8; obsolete =ISO-8859-1-Overrides entfernt.
  • Pro .properties-Datei eine explizite encoding//<pfad>=UTF-8-Zeile in .settings/org.eclipse.core.resources.prefs (1392 Eintraege). Ordner-Level- oder Project-Default-Overrides wirken bei .properties nicht, weil der Java-Properties-Content-Type von Eclipse mit ISO-8859-1 belegt ist; nur File-Level-Overrides setzen sich gegen die Content-Type-Default durch.
• Core-Resource-I/O (ResourcesModule, ResourceFile/`LineReader`) liest und schreibt UTF-8.
• Doclet-Generator (MessagesGenerator, TLDoclet) schreibt UTF-8 ohne \uXXXX-Escaping. Die Normalize-Mojos (tl:normalize, tl:normalize-resource-file) ersetzen dadurch auch verbliebene \u-Escapes in handgepflegten Bundles durch echte UTF-8-Zeichen.
• Util-Loader (PropertiesHelper, Country, XMain, FileCompiler, RefactorResources, ConvertThemeSettings, StackTraceDecoder, HelpPageIndex, DocumentationImporter, StreamUtilities.storeNormalized, ResourceResolver, ResourceMappingUtil, Ticket26529TransferVariantsToDynamicStorage Write-Seite) umgestellt. Audit via tl-mcp callers_of(Properties.load)/`store`.
• Ticket26529TransferVariantsToDynamicStorage (Read-Seite) und MigrateResourcesToJavaDoc bleiben absichtlich bei ISO-8859-1 (Legacy-Migrationswerkzeuge fuer alte Dateiformate). Kafka- und ZooKeeper-Starter bleiben beim Properties.load-Default (externe Configs, andere Konvention).
• tl-archetype-app: Template-POMs und .settings/org.eclipse.core.resources.prefs so angepasst, dass neu generierte Projekte initial UTF-8-tauglich sind.
• tl-maven-plugin in tl-parent-all <pluginManagement> aufgenommen (lazy, kein Chicken-and-Egg beim Fresh-Build). Damit funktioniert mvn tl:<goal> aus dem Engine-Root, und hardcodierte <version>8.0.0-SNAPSHOT</version>-Eintraege in den anderen Parent-POMs entfallen.

Code-Migration

Fuer TopLogic-basierte Anwendungen, die auf eine UTF-8-Engine upgraden, gibt es ein neues Maven-Goal:

mvn tl:migrate-to-utf8

Kein Versions-Suffix noetig: das Plugin kommt aus tl-parent-app per Vererbung, sobald die Customer-pom.xml die <parent>-Version auf die neue Release hochgezogen wurde.

Das Goal erledigt vier Schritte in einem Aufruf:

1. **Source-Files**: konvertiert .java- und .properties-Dateien von ISO-8859-1 auf UTF-8. Pro Datei wird klassifiziert:
   • Reine ASCII: unveraendert.
   • Bereits gueltiges UTF-8: uebersprungen und im Bericht als already-utf8 gelistet (Hinweis auf Absicht oder vorhandenes Mojibake).
   • Echte ISO-8859-1: in UTF-8 umgeschrieben.
2. **POMs**: flippt project.build.sourceEncoding in jeder pom.xml von ISO-8859-1 auf UTF-8.
3. **Eclipse-Prefs**: in .settings/org.eclipse.core.resources.prefs werden encoding/<project>, encoding/src, encoding//src/main/java und encoding//src/test/java auf UTF-8 gesetzt, obsolete =ISO-8859-1-Overrides entfernt.
4. **Eclipse .properties-Overrides**: fuer jede gefundene .properties-Datei wird eine encoding//<pfad>=UTF-8-Zeile angelegt (verhindert das ISO-8859-1-Verhalten des Java-Properties-Content-Type in Eclipse).

Parameter:

• -DbaseDir=<pfad> — Zielverzeichnis (Default: Projekt-Verzeichnis bzw. CWD).
• -Dextensions=java,properties[,xml,...] — zu konvertierende Endungen.
• -DdryRun=true — Berichten ohne Schreiben.
• -DskipSources=true / -DskipPoms=true / -DskipEclipse=true — einzelne Phasen ueberspringen.

Customer-Upgrade-Flow

1. Lokale Aenderungen committen oder stashen — das Goal schreibt direkt.
2. In der pom.xml die <parent>-Version auf das neue Release hochziehen.
3. mvn tl:migrate-to-utf8 (optional vorher -DdryRun=true zur Vorschau).
4. mvn install.
5. Bereits in Eclipse geoeffnete .properties-Editoren schliessen und neu oeffnen, damit der Tooltip nicht mehr determined from content type zeigt.

Customer-eigene Module mit .properties-Dateien werden mitkonvertiert; Werte mit Umlauten landen danach als echte UTF-8-Bytes statt als \uXXXX-Escapes auf der Platte.

Status

Umgesetzt in Branch CWS/CWS_29286_java_utf8. Validiert: Fresh-Checkout-Reactor-Build (leeres lokales Repo) faehrt durch; tl:migrate-to-utf8 ist idempotent gegen den Engine-Reactor; tl:normalize-resource-file ersetzt nachweislich verbliebene €`-Escapes durch `€.