Migrating a TopLogic application from 8.0.0-alpha4 to 8.0.0-alpha5
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-alpha5/ and the
TopLogic Trac tickets of milestone TL_8.0.0-alpha5 (ticket numbers are given as #NNNNN; the
per-ticket page is https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha5/NNNNN/).
8.0.0-alpha5 has one migration topic besides the version bump: TL-Script converts numbers to text
without locale-dependent formatting (#29064, section 4.1), and the Java method
ToString.toString(Object) is gone (section 1.2). It is relevant only for applications that show
numbers as text via TL-Script and rely on the user's locale for their formatting, or that call
ToString.toString from Java.
How to use this document
- Do the version bump (section 1.1). 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.
- The Java API change (section 1.2) shows up as a compile error. The changed number formatting (section 4.1) shows up only at runtime, as differently formatted numbers in labels, tooltips, columns and texts.
- Section 7 lists behavior changes for information only; they need no change in the application.
- For background on an engine feature, read the developer articles shipped with the engine
(tl-mcp
list_docs/read_doc). - 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-alpha5 (parent tl-parent-app / tl-parent-core version, or
the tl.version property).
Detect:
grep -rn --include=pom.xml -e '8.0.0-alpha4' .
1.2 ToString.toString(Object) removed (#29064) — mandatory where applicable
The Java method com.top_logic.model.search.expr.ToString.toString(Object) no longer exists. Use
com.top_logic.model.search.expr.SearchExpression.asString(Object) (now static) instead. Note that
asString formats numbers without the user's locale (section 4.1).
Before:
String text = ToString.toString(value);
After:
String text = SearchExpression.asString(value);
Detect:
grep -rn -e 'ToString.toString' --include=*.java .
4. TL-Script in views and layouts
4.1 Number-to-text conversion no longer locale-dependent (#29064) — mandatory where applicable
The conversion of values to text in TL-Script is unified (SearchExpression.asString). Numbers are
no longer formatted according to the user's language, but without thousands separators and with a
decimal point; integral values are written without decimal places (1234.5 instead of 1.234,5,
2019 instead of 2.019).
Affected are:
- the function
toString(...), - string concatenation with
+, join(...),- label, tooltip, icon and column providers defined in TL-Script (
LabelProviderByExpression,TooltipProviderByExpression,IconProviderByExpression,ComputedColumnProviderByExpression), InstanceResolverByExpression.
Where a locale-dependent representation is needed, format the number explicitly.
Before (number shown as 1.234,5 for a German user):
"Total: " + $total
After:
"Total: " + numberFormat("#,##0.00").format($total)
Check every hit that converts a number to text; leave expressions that work with strings, objects or dates unchanged. Expressions configured in-app (stored in the database or in overlay files of the running application) are not found by the search; ask the user whether such configurations exist.
Detect:
grep -rn -e 'toString(' -e 'ByExpression' -e 'join(' --include=*.xml .
7. Further notes (no action required)
7.1 TL-Script: database query optimization with parameters (#29064)
A filter over all(...) that the engine turns into a database query is now also optimized when it
is moved into a function and called with a parameter, e.g.
calcValue = id -> {
all(`myModule:myType`).filter(x -> $x.get(`myModule:myType#id`) == $id)
};
$calcValue("4711")
Previously only the form with a literal value was optimized. Results are unchanged; such expressions (e.g. in REST endpoints with parameters) just run faster.
7.2 Generator errors are marked as errors in the build output (#29292)
The output of the Java binding generation (tl-maven-plugin:generate-java) now prefixes each line
with [ERROR] or [INFO], so the actual cause of a failed generation can be found in the Maven
log. In addition, an error while writing a messages file of the generated bindings now aborts the
generation; previously it was only logged and the build reported success with a missing file.
7.3 Known issue in 8.0.0-alpha5: optimized queries with transient objects (#29340)
A TL-Script expression that is optimized into a database query (section 7.1) fails in 8.0.0-alpha5 when a transient object is passed as a parameter (follow-up of #29064). This is fixed in 8.0.0-alpha6; no workaround is required in the application.
7.4 Bug fixes
- Attributes with a fallback value on transient objects (#29304): a value set on a transient object (e.g. in the detail dialog of a composition row) is now stored where it is read again and is taken over into the row object.
- Configured TL-Script functions (#29305): defining a function in the service editor with a
description in only one language no longer fails with a
NullPointerException. - Undo (#29314): reverting changes whose commit message is a literal text (e.g. set by an
application-specific undo button) no longer fails with
UnsupportedOperationException: Must not resolve literal text as key. - Change log (#29318): the change set analysis no longer fails with a
NullPointerExceptionwhen a created object belongs to a non-versioned type.
8. Verification checklist
mvn clean installof the application (with tests if possible). If the Java binding generation fails, search the build log for[ERROR]lines of the generator (section 7.2).- Start the application and read the startup log for configuration and migration errors.
- Log in and open every view of the application; check that numbers in labels, tooltips, table columns and generated texts are formatted as intended (section 4.1).
- Report to the user every step that was skipped or needed a decision, and every TL-Script expression changed for section 4.1.