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
.propertiesfiles; - new parameters in the TL-Script function
tree(...)of flow diagrams (#29267, section 4.1) — relevant only for calls that passcssClassoruserObjectpositionally; - the reorganized resource provider classes (#28388, section 5.1) — relevant only for
applications with Java subclasses of
AbstractTLItemResourceProviderorWrapperResourceProvider.
How to use this document
- 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.
- 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). - For background on an engine feature, read the developer articles shipped with the engine
(tl-mcp
list_docs/read_doc). - Section 7 lists behavior changes for information only; they need no change in the application.
- Finish with the verification checklist (section 8).
- 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.sourceEncodingis nowUTF-8in the engine parent POMs (tl-parent-all,tl-parent-build); an application inheriting fromtl-parent-app/tl-parent-corecompiles its Java sources as UTF-8 unless it overrides the property.- The engine reads and writes resource bundles (
WEB-INF/conf/resources/*.properties, generatedMETA-INF/messages_*.properties) as UTF-8. An ISO-8859-1 encoded bundle with umlauts shows broken characters at runtime. - The doclet that generates
messages_*.propertieswrites UTF-8 without\uXXXXescapes; the normalize goals (tl:normalize,tl:normalize-resource-file) also replace remaining\uXXXXescapes 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:
- Commit or stash local changes first — the goal writes files directly.
- Do the version bump (step 1.1) first; the goal is inherited from
tl-parent-appwith the new parent version, no plugin version is needed on the command line. - Optionally preview:
mvn tl:migrate-to-utf8 -DdryRun=true - Run:
If the application does not inherit from a TopLogic parent POM (prefixmvn tl:migrate-to-utf8tlnot resolvable), use the full coordinates:mvn com.top-logic:tl-maven-plugin:8.0.0-alpha4:migrate-to-utf8 mvn install.- In Eclipse, close and reopen
.propertieseditors 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)bysuper.getLabel(x). - A subclass that only implemented
getLabel(Object)to reproduce the default (ID column /name) can drop the override. - Imports of
quote/getTooltipNonNullvia the old class need no change as long as the subclass still extendsAbstractTLItemResourceProvider(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
mvn clean installof the application (with tests if possible). There must be no compiler warnings about unmappable characters for encoding UTF-8.- Start the application and read the startup log for configuration and migration errors.
- 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). - 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.