Eclipse Scout Migration Guide

This document describes all relevant changes from Eclipse Scout 11.0 to Eclipse Scout 22.0. If existing code has to be migrated, instructions are provided here.

The Java 8 support has been dropped in Scout 22. Scout 22 older than 22.0.11 only supports Java 11. Scout 22.0.11 or newer supports Java 17 too. Check the chapter Migrating to Java 17 if you plan to use Java 17. You can get a Java 11 or 17 runtime from the Adoptium page.

Ensure you have at least Maven 3.6.3 installed. Older versions are no longer supported. You can get a new Maven runtime at the Maven download site.

Ensure you have at least Node 16.13.0 installed. Older versions will not work. A new version can be obtained from the Node download page.

Scout now requires at least pnpm 6.22.2. You can install it as described on the pnpm installation page.

To update your application the following steps might be required:

If your launch group contains an action that waits for a specific console output before starting the ui and backend servers, you probably need to adjust the regular expression. Otherwise, the launch is likely to get stuck at about 63%.

To do so, edit your launch configuration and change the regular expression of the js build program from Built at: to compiled .*successfully. Or remove the action completely if you prefer the launchers to be started in parallel.

The following changes have been made to the Scout releng. Please apply the necessary migration steps in your files and build scripts (may also affect continuous integration environments):

The property prefer-workspace-packages is new and important if you have multiple npm modules in your project.

The Support for Log4j logging has been dropped as Log4j 1 is end-of-life. If you still rely on Log4j 1 please update to another logger implementation. Scout supports java.util.Logging and Logback (recommended) out of the box but other SLF4j compatible loggers can be configured as well.

The type version of a data object is used to identify a certain structure version of the stored data object. A data object may be stored in a database or be available as a container to export certain data for import in a different compatible system. Such a data object may evolve over time and undergo structural changes. Some structural changes make it necessary to apply migrations to existing serialized data objects to comply with the new structure.

In order to prepare for migration support, the value type of the @TypeVersion annotation was changed from String to Class<? extends ITypeVersion>. A ITypeVersion represents a namespace/version and its dependencies.

Migration:

For each different String value used in type version annotation, create an implementation of ITypeVersion as described in Data Objects: Namespace and ITypeVersion in the technical documentation.

DataObjectInventory#getTypeVersion now returns NamespaceVersion instead of String. Use NamespaceVersion#unwrap to access the text representation.

@EnumVersion was designed for migration support similar as the TypeVersion but was never part of any serialization output of a data object, therefore couldn’t be used as indicator for migrations. Support for @EnumVersion was removed.

Migration:

Remove @EnumVersion annotations on IEnum implementors.

The new notifications displayed by the browser use the application logo configured in AbstractDesktop#getConfiguredLogoId() by default.

If you use native notifications, you should provide a logo with a resolution of at least 150x150 px. If your application logo already has such a resolution, it should be fine. If your application logo has a lower resolution or is an SVG, you should use a different image for the notifications (SVGs are not supported by Chrome notifications). To do so, just configure the native notification defaults on your desktop.

The image application_logo_large and the constant AbstractIcons.ApplicationLogo have been removed. The name was confusing and it was only used for the ScoutInfoForm. The info form now uses the logo of the desktop (IDesktop#getLogoId()) by default. So if you prefer to use a different logo for the info form, just extend the info form, override the method getProductLogo() and return the name of your preferred image.

In case you don’t use SVG logos yet, you should consider doing so to prevent blurry logos.

Views (forms with display hint = view) are now closable by default. Until now, only dialogs containing a close or cancel button showed the close icon in the top right corner. If you have views that must not be closable, set closable to false explicitly.

The type of the data argument for the callback execPostMessage was changed from String to Object. This allows for the widest variety of data that can be sent from an embedded page to the application:

In previous Scout versions, all messages were always converted to text. Now, the data type is preserved as accurately as possible. JSON objects or arrays are converted to IDoEntity or DoList with the help of the IObjectMapper bean. To use this feature, an implementation of IDataObjectMapper needs to be present at runtime. If no implementation is available, the data will be converted to text automatically.

Migration:

Adjust the signature of all implementations of AbstractBrowserField#postMessage in your code.

In the past when a page was created the embedded detail forms and tables have been created together with the page. This may lead to a bad performance when an outline containing lots of complex pages is created.

Therefore the containing tables and forms are now only created when the page is activated (e.g. selected by the user). This is the same behavior as already implemented in Scout Classic since several years. As a consequence accessing Page.detailForm or Page.detailTable may now return null if the page has not been activated yet.

Check all usages of the detailForm and detailTable properties of pages in your code and ensure it is guarded with a null check or is only executed when the page has already been activated.

Typically these properties are accessed in the _init() function of a page e.g. to attach listeners. This is no longer possible as these properties are no longer available at that moment.

As an alternative override the _initDetailForm(form) or _initDetailTable(table) methods if your code exists on a Page (don’t forget to add a super call). If outside a Page listen for the propertyChange events for detailForm or detailTable to execute your detailForm or detailTable dependant code.

Furthermore if you use the following methods on pages, please rename them as follows:

The tag field is not clickable by default anymore. If you need the tags to be clickable (and triggering a tagClick event), you have to activate it manually by setting clickable to true in the given tag field model. Or by using the dedicated setter: tagField.tagBar.setClickable(true).

The following classes were renamed:

When raw deserializing json using Jackson (e.g. by using JacksonDataObjectMapper#readValueRaw) the behavior changed for floating point numbers: In former releases float numbers fitting into a Double have been mapped to Double. Now always a BigDecimal is used. This helps to clarify and stabilize the API (the datatype does not suddenly change if the numbers get bigger) and it helps to map the value from the json to a more precise Java representation (a Double cannot hold all floats exactly).

Nothing changes if you deserialize json to a typed DataObject. Then the target type of the attribute in the DataObject is used.

If your code relies on a specific float type after raw deserialization, update it accordingly to handle BigDecimal instead.

The behavior of data objects without a @TypeName annotation was changed. In former releases such a data object was serialized into JSON including a "_type" : null type name. The new implementation does not include the null-TypeName in the serialized JSON document.

The static strings utility provides various string-related functions. The obsolete functions uppercaseFirstLetter and lowercaseFirstLetter were deprecated in favor of more robust and consistent alternatives, and should no longer be used. They will be removed eventually.

Migration:

Note the uppercase "C" in the new function names!

The StreamUtility utility provided some methods that were functionally identical to Java 9 methods of the same name. The methods not, takeWhile, and iterate were removed; the equivalent Java core library methods may now be used directly.

Migration:

Note that takeWhile now operates on the java.util.Stream object itself and no longer is a static method.

The style and colors for tooltips has been changed which may require the following migration:

The HTTP Session ID is a crucial factor of a web application’s security. Knowledge of the session ID can enable attackers to hijack the session of an active user. It must therefore not be made available to a malicious third party under any circumstances! Writing the ID to a log files might therefore pose a security risk, depending on who has access to the file.

Scout does not directly output the HTTP Session ID by default, but it provides a corresponding "diagnostics context value" (MDC). If the logger implementation is configured accordingly, the context value http.session.id is written to the log file.

In accordance with the security by default principle, the diagnostics context value no longer contains the full session ID. Instead, an obfuscated and truncated identifier is provided. It cannot be converted back to the original session ID but is still sufficiently unique to relate log entries for the same session for debugging purposes. See the class HttpSessionIdLogHelper for details.

Migration:

The class ScoutFieldStatus has been deleted. It can be replaced with org.eclipse.scout.rt.platform.status.Status.

The widgets Table.js, Tree.js, TileGrid.js and TileAccordion.js share a common filter API since 22.0. This API contains the methods addFilter(filter, applyFilter = true), removeFilter(filter, applyFilter = true) and setFilters(filters, applyFilter = true) and the property filters.

The corresponding methods of the TileAccordion.js used to be addTileFilter(filter), removeTileFilter(filter) and setTileFilters(filters). These methods were renamed to the ones above. The property tileFilters was renamed to filters as well.

Some of the above widgets also had addFilters and removeFilters methods to add or remove an array of filters. Those methods were removed as the new ones can handle single filters and arrays of filters.

The mentioned widgets used to have a different behavior whether after modifying the filters they were executed or not. All calls need to be checked and adjusted accordingly.

Examples:

Migration:

These widgets support a text filter that is shown while typing if the widget is focused. This behaviour is enabled by default and can be turned off using the property textFilterEnabled. Fields that provide this functionality may now be obsolete and can be removed.

For more information about the filter API and the filter field see Filter Field.

All classes that are related to the DataModel have been moved to separate modules. This includes IDataModel and the IComposerField. If these classes have been used you need to add the references to the new modules to the corresponding pom.xml. The packages for these classes remain unchanged so no further migration is needed besides adding the dependencies to the new modules. These packages are intended to be deleted in an upcoming release.

If you created custom JavaScript keystrokes (extending from KeyStroke.js), you might experience a different behavior: the keystroke is now only active if the widget and every parent widget is enabled. Previously, the state of the parents was ignored, which was inconsistent. If your keystroke should be active even if the widget is disabled, you can set inheritAccessibility = false on your keystroke. For more details, see https://github.com/eclipse-scout/scout.rt/commit/91f8465564e718702920a28edbb559041cfeb752

If you are implementing one of the interfaces ITokenVerifier or ITokenPrincipalProducer, you must add either the @ApplicationScope or @Bean annotation to your implementation class. Previously, the interfaces itself were annotated with @ApplicationScope, which is too strict. This prevents having multiple instances of BearerAuthAccessController with different configurations/states of an ITokenVerifier or ITokenPrincipalProducer.

Widgets which allow to upload a file inside the browser show an error message if the uploaded file exceeds the configurated maximum upload file size. The error message always refers to MB even if the configured maximum upload file size is much smaller than that (or much larger). The error message looked like this: The maximum file size exceeds the limit allowed (0.000976 MB).

The same message using KB is much more readable: The maximum file size exceeds the limit allowed (1 KB).

Hence, depending on the file size, a suitable unit (B, KB, MB, GB) is used for all upload-widgets (file chooser, file chooser button, file chooser field).

This change has also changed the translations of the text-key ui.FileSizeLimit. In case this text-key is directly used in your project (which you should not do anyway), the displayed error message is broken now. You have to adapt your code.

The colorHexValue property of a IChartValueGroupBean can now hold more than one hex value. These values are used to color the corresponding dataset in a ChartJS chart (bar, line, pie, bubble, etc.), if autoColor is turned off. The given colors are repeated for the whole dataset, e.g. if there are two colors given (blue and yellow) and the dataset contains 7 values, the elements are colored alternately in blue and yellow (starting and ending with blue). These colors are also used by the tooltip and the legend. If there are multiple colors for one legend label the first one will be used.

If one processes this values further the code needs to be changed to work with List<String> instead of String.