Eclipse Scout Migration Guide

About This Document

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

The here described functionality has not yet been released and is part of an upcoming release.

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>25.1.0-beta.2</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": "25.1.0-beta.2",
    "@eclipse-scout/releng": "^25.1.0"
  },
  "dependencies": {
    "@eclipse-scout/core": "25.1.0-beta.2",
    "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

New Build & Runtime Requirements

Scout 25.1 requires at least the following:

  • Build and runtime of Scout 25.1 require Java 21 (Java 17 support has been dropped).

  • Furthermore, the build requires

    • Maven >= 3.9.9

    • Node: >= 22.13.0

    • Pnpm: >= 9.15.4

Pnpm Settings Changes

Pnpm 9 changed the default of link-workspace-packages from false to true, see https://github.com/pnpm/pnpm/releases/tag/v9.0.0

Scout uses snapshot ranges (>=25.1.0-snapshot <25.1.0) in the package.json files instead of the workspace: protocol to link workspace packages together.

If the flag is false, pnpm install or pnpm update downloads the dependencies instead of using the ones from the workspace.

So this flag needs to be true when having more than one npm package in the workspace that depend on each other. To do so, add the property link-workspace-packages=true to your .npmrc file in your workspace or user home directory. We also recommend to put prefer-workspace-packages=true to ensure workspace packages are always preferred even if there are newer versions in the remote repository.

Build Changes

  • The Maven coordinates of the git-commit-id-plugin changed from pl.project13.maven:git-commit-id-plugin to io.github.git-commit-id:git-commit-id-maven-plugin.

  • The Maven coordinates of the download-maven-plugin changed from com.googlecode.maven-download-plugin:download-maven-plugin to io.github.download-maven-plugin:download-maven-plugin.

  • The support for the outdated org.apache.tomcat.maven:tomcat7-maven-plugin has been dropped. If you still rely on this plugin, you have to specify the desired version in your own scripts.

New version for Jakarta Activation and Jakarta Mail

For these dependencies the versions have been updated to the Jakarta EE 10 version:

  • Jakarta Activation 2.1

  • Jakarta Mail 2.1

As the groupId has been changed for these dependencies, exclusions for the older version com.sun.activation:jakarta.activation (resp. mail) have been added for other dependencies which did depend on these (maven duplicate-finder should point them out). Existing exclusions for jakarta.activation:jakarta.activation-api and org.eclipse.angus:angus-activation (resp. mail) should be removed for other dependencies (two new dependencies instead of one to differ between API and implementation).

Modules including dependencies to com.sun.activation:jakarta.activation should instead use org.eclipse.angus:angus-activation (same for mail) as dependency (which includes the API and implementation). If your implementation references implementation classes the package name needs to be adjusted (implementation has been moved).

ClientCallback renamed to UiCallback

org.eclipse.scout.rt.client.ui.desktop.ClientCallback has been renamed to org.eclipse.scout.rt.client.ui.desktop.hybrid.uicallback.UiCallback.

Furthermore, invoking TypeScript code from the client Java code has been simplified using org.eclipse.scout.rt.client.ui.desktop.hybrid.uicallback.UiCallbacks. See the UI Callback technical guide for more details.

LESS constant renamed

The LESS constant @icon-error for the font icon with the code point U+E001 was renamed to @icon-exclamation-mark-circle to align it with its corresponding Java and JavaScript constants.

Migration: Search for references to the constant @icon-error in your own *.less files and replace it with @icon-exclamation-mark-circle where appropriate.

Deprecated meta tag "apple-mobile-web-app-capable" removed

The <meta> tag "apple-mobile-web-app-capable" has been deprecated in iOS for several years. Chromium-based browsers recently started reporting this with a warning on the console. Because the tag had no effect anyway, it can simply be removed.

Migration: In existing projects, search for the text <meta name="apple-mobile-web-app-capable" content="yes"/> in all *.html files and remove it. The template in the Scout archetype was updated accordingly, so newly created projects will no longer contain the deprecated tag.

Mobile browsers will still offer the possibility to add a home screen icon for the application (which will just be a bookmark, opened in the regular browser). To properly configure it as an "app", consider adding a PWA manifest.

Use scout properties for selenium test module configuration

Test setup provided by module org.eclipse.scout.rt.ui.html.selenium now uses scout properties instead of system properties. The following table contains the mapping (see also class SeleniumProperties).

old system property scout config properties

web.app.url

scout.selenium.webAppUrl

query.params

scout.selenium.webQueryParams

take.screenshot.on.failure

scout.selenium.screenshotOnFailure

webdriver.chrome.driver

scout.selenium.driverConfig[webdriver.chrome.driver]

(now optional)

new property

scout.selenium.driver

Must be set either to chrome, edge or firefox.

new property

scout.selenium.driverRemoteServerUrl

May be set (usually to http://localhost:4444) in order to use selenium docker grid.

All driver-specific configurations may be set with the property scout.selenium.driverConfig. For example, the following setting will set up logging for the chrome driver as before:

scout.selenium.driverConfig[webdriver.chrome.logfile]=${java.io.tmpdir}webdriver.log
scout.selenium.driverConfig[webdriver.chrome.verboseLogging]=true

See also module org.eclipse.scout.widgets.ui.html.app.selenium for a sample properties file.

Scout JS

FormField: use _computeEmpty instead of _updateEmpty

If a widget implements _updateEmpty it should now implement _computeEmpty instead. This guarantees that a property change event is triggered and the render function called, if there is any.