Eclipse Scout Migration Guide

About This Document

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

Obtaining the Latest Version

Scout Runtime for Java

Scout Runtime artifacts for Java are distributed using Maven Central:

Usage example in the parent POM of your Scout application:

<dependency>
    <groupId>org.eclipse.scout.rt</groupId>
    <artifactId>org.eclipse.scout.rt</artifactId>
    <version>24.2.16</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

Scout Runtime for JavaScript

Scout Runtime artifacts for JavaScript are distributed using npm:

Usage example in your package.json:

{
  "name": "my-module",
  "version": "1.0.0",
  "devDependencies": {
    "@eclipse-scout/cli": "24.2.16",
    "@eclipse-scout/releng": "^24.1.0"
  },
  "dependencies": {
    "@eclipse-scout/core": "24.2.16",
    "jquery": "3.7.1"
  }
}

The pre-built Scout JavaScript assets are also available using a CDN (e.g. to be directly included in a html document): https://www.jsdelivr.com/package/npm/@eclipse-scout/core?path=dist

IDE Tooling (Scout SDK)

Scout officially supports IntelliJ IDEA and Eclipse for Scout Developers.

IntelliJ IDEA

You can download the Scout plugin for IntelliJ IDEA from the JetBrains Plugin Repository or you can use the plugins client built into IntelliJ IDEA. Please refer to the IntelliJ Help on how to install and manage plugins.

Eclipse

You can download the complete Eclipse IDE with Scout SDK included here:
Eclipse for Scout Developers

To install the Scout SDK into your existing Eclipse IDE, use this P2 update site:
https://download.eclipse.org/scout/releases

For nightly beta builds use this P2 update site: https://download.eclipse.org/scout/nightly

Typed PermissionId

A new org.eclipse.scout.rt.api.data.security.PermissionId was introduced to be used as typed identifier for permissions instead of the untyped name as String which was previously used.

The argument of the org.eclipse.scout.rt.security.AbstractPermission.AbstractPermission only constructor was changed from String to PermissionId, a new AbstractPermission#getId() method was introduced which will return an id equal to the supplied id (actually internally the name is still stored as String and just wrapped on request). → All permission names should be changed from String to PermissionId identifiers.

With this change the following data objects have been adjusted:

Type name Attribute type Attribute name New type New name

scout.PermissionCollection

Map<String, ? extends Collection<PermissionDo>>

permissions

Map<PermissionId, ? extends Collection<PermissionDo>>

(unchanged)

scout.Permission

String

name

PermissionId

id

Primary sort order for IDoValueMigrationHandler

Untyped data object value migration handlers need to be applied before regular value migrations because they may convert typed values to the expected target type. A typical use case is the conversion from UnknownId to a typed target ID in case of renaming a type ID name.

Classes implementing IDoValueMigrationHandler directly need to implement the new method IDoValueMigrationHandler.primarySortOrder(). It’s highly recommended to extend AbstractDoValueMigrationHandler which defines DEFAULT_PRIMARY_SORT_ORDER by default instead of implementing only the interface.

The primary sort order can be used to group different types of value migrations. Regular value migrations (i.e. sub-classes of AbstractDoValueMigrationHandler use IDoValueMigrationHandler.DEFAULT_PRIMARY_SORT_ORDER) and are applied after untyped value migrations (i.e. sub-classes of AbstractDoValueUntypedMigrationHandler) which use IDoValueMigrationHandler.UNTYPED_PRIMARY_SORT_ORDER.

Data object mapper support reading of unknown ids in lenient mode

The Scout data object mapper was improved to allow to deserialize qualified ids with unknown type (e.g. a serialized qualified id whose id type class is no longer available). In lenient mode such ids are now deserialized as instance of UnknownId allowing to retain the unknown id value for further usage and migration of those ids. The former implementation returned null in this case. The default (non-lenient) deserialization remains unchanged and throws a PlatformException if a qualified id with an unknown type is deserialized.

Check usages of org.eclipse.scout.rt.dataobject.ILenientDataObjectMapper and org.eclipse.scout.rt.dataobject.id.IdCodec.fromQualifiedLenient and change the existing code which checks for a null value accordingly to retain the existing code behavior.

IId id = BEANS.get(IdCodec.class).fromQualifiedLenient(idString);
return id instanceof UnknownId ? null : id;

BasicCache: Removal of Deprecated Constructors

The two constructors of BasicCache not supporting the label supplier were removed. As replacement, use the constructor including label supplier as second argument. The label supplier can be retrieved via CacheBuilder#getLabelSupplier().

Calendar: Support for Multiple Calendars

The calendar widget is now capable of handling multiple calendars. See multiple calendar support in the release notes for details.

In most cases no changes have to be done. Some minor API changes have been made in the TypeScript part of the widget (Calendar.ts).

Max Row Count and Limited Result for Scout JS Pages

Pages written in TypeScript now support a maximum row count and inform the user if there would be more data than allowed to fetch (limited result). If you want to use this feature for your Scout JS pages as well, follow these instructions:

  1. The page must tell the maximum numbers of rows it would like to load. This is done using the new function _withMaxRowCountContribution.

  2. The data source must read this maximum value and limit the number of rows in case there are more. It reports back if there would have been more data available. This is done with the MaxResultsHelper.

There are several Examples which explain how to use these new components.

SplitBox (Scout JS)

The following constants have been deprecated.

SplitBox.SPLITTER_POSITION_TYPE_RELATIVE_FIRST
SplitBox.SPLITTER_POSITION_TYPE_RELATIVE_SECOND
SplitBox.SPLITTER_POSITION_TYPE_ABSOLUTE_FIRST
SplitBox.SPLITTER_POSITION_TYPE_ABSOLUTE_SECOND

Use the new enum instead: SplitBox.SplitterPositionType.

Logical Grid Layout Config (Scout JS)

The properties on the LogicalGridLayoutConfig are not writable anymore. Setting them will no longer have an effect. If you need to adjust the properties you have to use the new clone method.

Listing 1. New way to modify the logical grid layout configuration
tileGrid.setLayoutConfig(tileGrid.layoutConfig.clone({columnWidth: 130}));

So you need to check whether you write the properties directly, e.g. using layoutConfig.columnWidth = 130 and replace that by using the clone method.

The layout configuration is available on several widgets like GroupBox, RadioButtonGroup, TileGrid and more.

DateFormat: format()

The format() function on the DateFormat class accepts two arguments. The first argument date specifies the Date object to format. The optional second boolean argument was used specify a hint for the formatting of a previously analyzed user input.

The second argument was replaced with an options object with the following properties:

analyzeInfo

The result of a previously analyzed user input when formatting it again. It helps the internal format functions to adjust the length of an accepted term to match to the corresponding user input. Normally, it is not necessary to set this value.

Migration:

  • No migration is necessary if the format() function is called with a single Date argument.

  • If the second argument was set to false, it can simply be removed (that was the default, anyway).

  • If the second argument was set to true, replace it with an options object with the analyzeInfo property set.