Eclipse Scout Migration Guide

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

It is recommended that all REST operations which consume a request entity body message have a Consumes annotation set to restrict invalid input. Therefore, a test has been added which fails if there are such operations which do not have a Consumes annotation. The AbstractRestResourceAnnotationTest has to be extended in your modules to run this test.

It is recommended that all REST resource classes explicitly declare a @Path annotation.

According to the Jakarta RESTful Web Services specification, JAX-RS annotations — including @Path — are not inherited from superclasses or interfaces. While Jersey, the implementation we use, does attempt to locate a @Path annotation on parent classes, this behavior is not defined by the specification and should not be relied upon.

To ensure compliance, a test has been introduced that fails if any REST resource is missing a @Path annotation. To activate this validation for your module, extend the AbstractRestResourceAnnotationTest class accordingly.

The methods isAutoPrefixWildcardForTextSearch and setAutoPrefixWildcardForTextSearch on IDesktop have been removed. They have not been used since years and were never supported in Scout JS.

If you need a prefix wildcard, add it to your search texts manually where required.

The Maven Build no longer uses npm to run scripts. Npm is now only used to install pnpm and @eclipse-scout/releng. Then, pnpm is used to run build and test scripts. Accordingly, the following Maven-Master properties have been removed and can be deleted without replacement:

The following Java code was deprecated since at least one release and has been removed:

The following TypeScript code was deprecated since at least one release and has been removed:

The following Less mixins have been removed as they are no longer necessary:

AbstractRestLookupCall was moved from the client to the shared module: org.eclipse.scout.rt.client.services.lookup.AbstractRestLookupCall → org.eclipse.scout.rt.shared.services.lookup.AbstractRestLookupCall.

For the org.eclipse.scout.rt.mail.smtp.SmtpConnectionPool in the past idle timeouts could be defined in seconds. However, connections were only checked once per minute, hence idle timeouts less than one minute were not respected. This check interval has been decreased from one minute to 20 seconds (default value), it is now configurable by config property scout.smtp.pool.closeIdleConnectionsJobSchedule. Also the default idle timeout has been decreased from one minute to 20 seconds (existing config property scout.smtp.pool.maxIdleTime).

Also the connection error handling has been changed, connection error codes 421 and 451 are now also treated as failed connection (according to RFC 5312 3.8 connection failures and at least error codes 451 should be treated the same way).

Returning true in a visitor used for Tree.visitNodes now stops visiting completely instead of just skipping the subtree, see also Release Notes.

Please check your JavaScript / TypeScript code for occurrences of visitNodes and if the visitor explicitly returns true, replace it with TreeVisitResult.SKIP_SUBTREE.

org.eclipse.scout.rt.server.commons.GlobalTrustManager.getTrustedCertificatesInRemoteFiles() has been removed. As a result, all trusted certificates now have to be provided locally.

The following service operations have also been removed:

The BoundedResolveCacheWrapper (used implicitly by ICacheBuilder.withMaxConcurrentResolve) has been changed to allow multiple resolve operations for one thread (default is now reentrant) to avoid a potential deadlock cause. That is, one thread will only be counted once towards the limit.

However, this is just one potential deadlock cause, deadlocks may still occur if the resolve operation also relies on external semaphores.

To restore the previous behavior the BoundedResolveCacheWrapper may be added directly as custom wrapper with the second constructor allowing to disable this reentrant behavior.

As part of the move toward a stateless backend server, the server session support was extracted into separate modules for legacy support.

The new default setup is to use the Scout backend without session-support.

Several shared classes were moved into a .session package, adapt the imports in your UI-server modules.

The unit test annotation @RunWithServerSession has become obsolete if you do not use backend sessions any longer. Remove the annotation and make sure your test is annotated with @RunWithSubject.

The client notification dispatching was refactored as preparation step for a stateless Scout backend. The API of org.eclipse.scout.rt.server.clientnotification.ClientNotificationRegistry changed.

The central change is the removal of the boolean distributeOverCluster overloads: notifications are now always distributed within the cluster and published to all UI server nodes. The only exception is the new (but deprecated, legacy) putTransactionalForAllNodesWithoutClusterNotification(Serializable) method which allows to publish a notification only for UI nodes attached to the current backend node.

The HybridManager provides API to dispose formerly created widgets. Former implementations calling the hybrid Action scout.DisposeWidgets manually using the remote ids can be migrated.

The EventSupport provides API to register callback functions in order to handle events with subtypes. Consider e.g. a FancyEvent that is always triggered with the type fancy but has a property subType which can hold the values foo or bar. In order to support listeners for fancy:foo or fancy:bar such a callback needs to be registered. Earlier this was done using a subtype predicate, that was handed over the event and the subtype and returned a boolean flag whether the subtype matches. This was changed to a subtype provider, that is handed over the event and returns the subtype. All places using these subtype callbacks need to be migrated.

In case these timeouts are too low for your setup, update the corresponding config properties.

The defaults of the following properties have changed:

If you use the WrappedFormField in your Scout JS code, please verify the layout still looks and behaves as expected.

The method has been moved to IOutline and renamed to drillDown.

It is called when double-clicking a table row in the detail table of a page to select and expand the corresponding child page. But, expanding is actually not desired for table pages, so now only node pages are expanded.

If you need a specific table page or IJsPage to be expanded on this operation, you can override the method IPage.computeExpandOnDrillDown.

ITabBox.MARK_STRATEGY_EMPTY has been renamed to ITabBox.MARK_STRATEGY_NOT_EMPTY because the tab is marked if it is not empty.

A tab item is now marked if it has content or if it needs to be saved (if used in a search form).

In most cases, this should work as expected without a code migration. However, it may happen that a tab item will be marked even it looks empty at first glance, for example if it has a hidden field with a value. In that case you can set checkEmpty on the field to false, or provide a function to implement a custom empty computation. When providing a function, it may be necessary to call updateEmpty whenever a condition changes that you use in your empty computation.

To disable the marking completely without affecting the mandatory handling, you can set TabBox.markStrategy to null.

The tab items of a tab box (TabBox.tabItems) need to have the type TabItem. This is nothing new, but until now it kind of worked with a regular GroupBox as well. This was never intended.

To ensure the tab items have the correct type, the tab box now throws an error if a tab item doesn’t have the type TabItem.

To make sure you won’t get the error, you should check your tab boxes and extensions for tab boxes. You should find most of them by searching for objectType: TabBox and property: 'tabItems'.

The protected method FormFeld._updateEmpty() has been made public and renamed to FormFeld.updateEmpty().

The function System.getEndpointUrl only takes one argument now. The first one has been removed and only the second argument (default URL) is used for both the endpoint identifier and default URL.

Migrate from System.getEndpointUrl('name', 'default/url') to System.getEndpointUrl('default/url').

In case an existing named URL has been replaced using System.setEndpointUrl('name', 'new/url') it must be migrated to System.setEndpointUrl('default/url', 'new/url').

Scout includes support to lock the Node dependencies. See the Technical Guide for details.

To enable the feature perform the following: