TopLogic - the automated application engine
  • Releases
  • Dokumentation
  • Github
  • Discord
  1. Home
  2. Releases
  3. TL_8.0.0-alpha4
  4. Migration guide

8.0.0-alpha4
TopLogic Release

2026-05-21

Markdown version, e.g. for an LLM updating an application.

Migrating a TopLogic application from 8.0.0-alpha3 to 8.0.0-alpha4

Audience: an AI coding agent (or developer) upgrading a TopLogic application project. Sources: release notes https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha4/ and the TopLogic Trac tickets of milestone TL_8.0.0-alpha4 (ticket numbers are given as #NNNNN; the per-ticket page is https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha4/NNNNN/).

8.0.0-alpha4 has three migration topics besides the version bump:

  • the switch of the source and resource encoding from ISO-8859-1 to UTF-8 (#29286, section 1.2) — relevant for every application that has non-ASCII characters in its Java sources or .properties files;
  • new parameters in the TL-Script function tree(...) of flow diagrams (#29267, section 4.1) — relevant only for calls that pass cssClass or userObject positionally;
  • the reorganized resource provider classes (#28388, section 5.1) — relevant only for applications with Java subclasses of AbstractTLItemResourceProvider or WrapperResourceProvider.

How to use this document

  1. Work through the sections in order. Every step has a Detect line: run the search in the application's source tree. If it finds nothing, the step does not apply — skip it. Do not invent changes for steps that do not apply.
  2. Encoding problems (section 1.2) show up as compiler warnings/errors about unmappable characters and as broken umlauts in the UI (labels from resource bundles). Java API changes (section 5.1) show up as compile errors. A wrong positional tree(...) argument (section 4.1) shows up only when the flow diagram is rendered (wrong layout or a conversion error for the argument).
  3. For background on an engine feature, read the developer articles shipped with the engine (tl-mcp list_docs / read_doc).
  4. Section 7 lists behavior changes for information only; they need no change in the application.
  5. Finish with the verification checklist (section 8).
  6. Ticket descriptions on Trac are partly German; this document translates the relevant content.

Search commands below assume the project root as working directory and GNU grep.


1. Build and platform

1.1 Version bump — mandatory

Set the TopLogic version to 8.0.0-alpha4 (parent tl-parent-app / tl-parent-core version, or the tl.version property).

Detect:

grep -rn --include=pom.xml -e '8.0.0-alpha3' .

1.2 Source and resource encoding ISO-8859-1 → UTF-8 (#29286) — mandatory where applicable

The engine switched its source encoding from ISO-8859-1 to UTF-8:

  • project.build.sourceEncoding is now UTF-8 in the engine parent POMs (tl-parent-all, tl-parent-build); an application inheriting from tl-parent-app / tl-parent-core compiles its Java sources as UTF-8 unless it overrides the property.
  • The engine reads and writes resource bundles (WEB-INF/conf/resources/*.properties, generated META-INF/messages_*.properties) as UTF-8. An ISO-8859-1 encoded bundle with umlauts shows broken characters at runtime.
  • The doclet that generates messages_*.properties writes UTF-8 without \uXXXX escapes; the normalize goals (tl:normalize, tl:normalize-resource-file) also replace remaining \uXXXX escapes in hand-written bundles by the real UTF-8 characters.

An application with non-ASCII characters in ISO-8859-1 encoded .java or .properties files must convert them. The new Maven goal migrate-to-utf8 does this in one run:

  1. Commit or stash local changes first — the goal writes files directly.
  2. Do the version bump (step 1.1) first; the goal is inherited from tl-parent-app with the new parent version, no plugin version is needed on the command line.
  3. Optionally preview:
    mvn tl:migrate-to-utf8 -DdryRun=true
    
  4. Run:
    mvn tl:migrate-to-utf8
    
    If the application does not inherit from a TopLogic parent POM (prefix tl not resolvable), use the full coordinates:
    mvn com.top-logic:tl-maven-plugin:8.0.0-alpha4:migrate-to-utf8
    
  5. mvn install.
  6. In Eclipse, close and reopen .properties editors that were open, so that the encoding is no longer "determined from content type".

The goal performs four steps:

Phase What it does
Source files Converts .java and .properties files from ISO-8859-1 to UTF-8. Pure ASCII files stay unchanged; files that already decode as valid UTF-8 are skipped and listed as already-utf8 in the report (check them: intended UTF-8 or existing mojibake); real ISO-8859-1 files are rewritten as UTF-8.
POMs Changes project.build.sourceEncoding from ISO-8859-1 to UTF-8 in every pom.xml.
Eclipse prefs In .settings/org.eclipse.core.resources.prefs: sets encoding/<project>, encoding/src, encoding//src/main/java and encoding//src/test/java to UTF-8, removes obsolete =ISO-8859-1 overrides.
Eclipse .properties overrides Adds an encoding//<path>=UTF-8 line for every .properties file found (Eclipse's Java-properties content type defaults to ISO-8859-1; only file-level overrides win against it).

Parameters:

Parameter Meaning
-DbaseDir=<path> Target directory (default: project directory / current directory).
-Dextensions=java,properties[,xml,...] File extensions to convert (default java,properties).
-DdryRun=true Report only, do not write.
-DskipSources=true / -DskipPoms=true / -DskipEclipse=true Skip a single phase.

After the run, check the already-utf8 list of the report and the diff of a few converted files (umlauts must be intact). Values with umlauts in the application's own .properties files are now stored as real UTF-8 bytes instead of \uXXXX escapes.

Detect (any hit means the step applies):

grep -rn --include=pom.xml -i 'sourceEncoding>ISO-8859-1' .
LC_ALL=C grep -rlP '[\x80-\xFF]' --include=*.java --include=*.properties . | grep -v '/target/'
grep -rn 'ISO-8859-1' --include=org.eclipse.core.resources.prefs .

The second command lists every file with non-ASCII bytes, also files that are already UTF-8; the goal tells them apart.


4. TL-Script in views and layouts

4.1 Flow diagrams: new parameters of tree(...) (#29267) — mandatory where applicable

The TL-Script function tree(...) (flow diagrams, TreeLayout) has the new parameters childSplitThreshold, rowWise, subGridCols, subGridStartCol and bridgeGapY. They are inserted before cssClass and userObject. The full parameter order is now:

# Parameter # Parameter
1 nodes 11 parentAlign
2 connections 12 parentOffset
3 gapX 13 childSplitThreshold (new)
4 gapY 14 rowWise (new)
5 sibblingGapY 15 subGridCols (new)
6 subtreeGapY 16 subGridStartCol (new)
7 direction 17 bridgeGapY (new)
8 stroke 18 cssClass (was 13)
9 strokeWidth 19 userObject (was 14)
10 compact

Calls that pass cssClass or userObject positionally (13th or 14th argument) must switch to named arguments. Calls with at most 12 positional arguments and calls that already use named arguments are not affected.

Before:

tree($nodes, $connections, 40, null, null, null, null, "black", 1, false, 0.5, 0, "my-tree")

After:

tree($nodes, $connections, 40, null, null, null, null, "black", 1, false, 0.5, 0, cssClass: "my-tree")

or shorter, e.g. tree($nodes, $connections, cssClass: "my-tree").

Detect (then check each hit for 13 or more positional arguments):

grep -rn -e 'tree(' --include=*.xml . | grep -v -i -e 'subtree(' -e '[a-z]tree('

5. Classic UI / Java annotations / other APIs

5.1 Resource providers: logic moved to DefaultResourceProvider (#28388) — mandatory where applicable

The label and tooltip logic of com.top_logic.knowledge.gui.WrapperResourceProvider and com.top_logic.knowledge.gui.AbstractTLItemResourceProvider (tooltip format, label from the ID column or the name attribute) moved up into com.top_logic.mig.html.DefaultResourceProvider. Existing subclasses keep working; for untyped legacy persistent objects without tType() there is a fallback to TLNamed.getName().

Changed signatures for subclasses of AbstractTLItemResourceProvider:

Before After
getLabel(Object) abstract not abstract any more (inherited from DefaultResourceProvider)
public final String getDefaultLabel(Object) removed — call super.getLabel(object) instead
public final String getTooltip(Object) removed from this class; DefaultResourceProvider.getTooltip(Object) can now be overridden
protected ResKey getTooltipNonNull(Object) moved to DefaultResourceProvider (still protected)
protected static quote(Object) / quote(String) moved to DefaultResourceProvider (still protected static)

WrapperResourceProvider.getLabel(Object) is removed; its behavior (ID column, name attribute) is provided by DefaultResourceProvider.getLabel(Object). A super.getLabel(object) call in a subclass keeps compiling and behaves as before.

Steps:

  • Replace calls of getDefaultLabel(x) by super.getLabel(x).
  • A subclass that only implemented getLabel(Object) to reproduce the default (ID column / name) can drop the override.
  • Imports of quote/getTooltipNonNull via the old class need no change as long as the subclass still extends AbstractTLItemResourceProvider (they are inherited).

Before:

@Override
public String getLabel(Object object) {
    String label = getDefaultLabel(object);
    ...
}

After:

@Override
public String getLabel(Object object) {
    String label = super.getLabel(object);
    ...
}

New, no action needed: the model annotations <label> (TLLabel, label-provider, e.g. LabelProviderByExpression) and <tooltip> (TLTooltip, tooltip-provider, e.g. com.top_logic.model.search.providers.TooltipProviderByExpression) define label and tooltip of a type's instances in the model editor without a Java resource provider. In the <label> annotation only implementations with classifier label-provider can be chosen.

Detect:

grep -rn -e 'AbstractTLItemResourceProvider' -e 'WrapperResourceProvider' -e 'getDefaultLabel(' --include=*.java .

7. Further notes (no action required)

7.1 tUpdate / tAdd / tRemove check loosened again (#29240)

8.0.0-alpha3 rejected writing an attribute that does not belong to the object's type. 8.0.0-alpha4 loosens this check: an attribute of a subtype that overrides an attribute of the object's type may again be used to access the value, e.g. with B extends A and B#part overriding A#part, new(A).set(B#part, $value) works (needed e.g. when copying values to an instance of a super type). Writing an attribute of an unrelated type that merely shares the name (e.g. Medicine#code on a Door) remains forbidden.

7.2 Default label and tooltip of model objects (#28388)

DefaultResourceProvider (and thus MetaResourceProvider) now determines the label of a TLObject from its type: <label> annotation, then <id-column> annotation, then the name attribute, else "Object without name (<type>)". The tooltip comes from the <tooltip> annotation, else the previous format "<label> (<type>)". Annotations are inherited along the primary generalization chain and can be overridden in a subtype.

7.3 Failed checks are no longer reported as "internal error" (#29249)

A model constraint ("check") that fails on save is now shown as a validation message instead of an "Internal error" box, and is no longer logged as an ERROR.

7.4 Change log: subtree filter, undo/redo (#29236)

New: TL-Script functions changeLog(...) and revertChanges(...), command handlers UndoCommandHandler / RedoCommandHandler, the utility ChangeSetReverter. The type tl.changelog:ChangeSet gets the derived attributes isRevert and isRedo; the engine's automatic migration Ticket_29236_Added_isRevert_isRedo adds them to the model on the first start.

7.5 Browser tab title (#29262)

The title of the browser tab can now be set via <page-title> at the MainLayout, via the component resolvers DynamicPageTitle / TabPageTitle, or via the new property Page title in the layout editor. Without configuration the title stays as before.

7.6 Flow diagram tree layout (#29267)

The new tree(...) parameters (section 4.1) lay out nodes with many children in a 2D sub-grid (column-wise, or row-wise with rowWise). The default childSplitThreshold = 0 keeps the previous layout.


8. Verification checklist

  1. mvn clean install of the application (with tests if possible). There must be no compiler warnings about unmappable characters for encoding UTF-8.
  2. Start the application and read the startup log for configuration and migration errors.
  3. Log in and open every view of the application; check that labels with umlauts from the application's resource bundles display correctly, and that object labels and tooltips look as before (or as configured). Open every view with a flow diagram built by tree(...) and check its layout and styling (section 4.1).
  4. Report to the user every step that was skipped or needed a decision, the already-utf8 list of tl:migrate-to-utf8, and every file in which the encoding conversion changed characters other than the expected umlauts.
  • Get Started
  • Github
  • Discord
  • Das Unternehmen hinter TopLogic
  • Softwareentwicklung heute
  • Kontakt

© Copyright – Business Operation Systems GmbH

  • top-logic.com
  • Nutzungsbedingungen
  • Impressum
  • Rechtlicher Hinweis
  • Datenschutz
  • EN
  • Login