Eclipse Scout Migration Guide

This document is referring to a past Scout release. Please click here for the recent version.

About This Document

This document describes all relevant changes from Eclipse Scout 23.2 to Eclipse Scout 24.1. 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.1.15</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.1.15",
    "@eclipse-scout/releng": "^24.1.0"
  },
  "dependencies": {
    "@eclipse-scout/core": "24.1.15",
    "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 24.1 requires at least the following:

  • The Java 11 support has been dropped. Build and runtime therefore require Java 17 now. Java 21 Support is planned for a future release.

  • Furthermore, the build requires

    • Maven >= 3.9.2

    • Node.js >= 20.10.0

    • pnpm >= 8.11.0

HTTP/2 Support

For Scout 24 and newer enabling HTTP/2 for your application is recommended. Please refer to the documentation on how to enable HTTP/2.

Build Changes

  • The Maven build has the enforcer rule dependencyConvergence enabled by default. Therefore, builds will fail if different versions for the same dependency are used. To fix this, ensure your dependencies converge and use the dependencyManagement where necessary to specify which version to use.

  • The property master_dependency_tycho-compiler_version has been deleted as the Tycho compiler is no longer used. Instead, the property master_dependency_ecj_version may be used to specify the Eclipse compiler (ECJ) version. By default version 3.31.0 is used which is part of Eclipse 4.27 (2023-03), IntelliJ 2023.2 and IntelliJ 2023.3.

  • Typescript has been updated from 4.9.5 to 5.3.2. See here for a list of breaking changes and update your code accordingly.

  • Update the version of the maven_rt_plugin_config-master in your pom.xml files to the newest 24.1.x release. See Maven central for a list of versions available.

  • Update the Scout versions (package.json and pom.xml) as shown in Obtaining the Latest Version.

  • If you are using Eclipse and web-service providers, update the .factorypath files as shown in JAX-WS Appendix.

3rd Party Libraries Update

Update to Jakarta EE

As part of the Jakarta EE version update all imports need to be renamed from javax to jakarta. The update also requires some changes on the usage of third party libraries.

  • Update Scout dependency to release 24.1

  • Check third party library dependencies in your project, upgrade to Jakarta version if necessary

  • Reload all maven projects in IntelliJ or Eclipse IDE

  • Migrate your own code to Jakarta (e.g. using IntelliJ Migrator or similar Eclipse tooling)

    • IntelliJ Menu: Refactor → Migrate Packages and Classes → Java EE to Jakarta EE

    • Eclipse see Eclipse Transformer tool

    • All packages and classes are updated automatically

JAX-WS Services

After the upgrade to 24.1, projects that use JAX-WS (Soap) as a provider should check the connection both on DEV and on the deployed system to ensure that everything is working as desired. This applies above all to cases when own libraries in /WEB-INF/lib are used or the corresponding resources in /META-INF/resources.

Update namespace in binding files

If your JAX-WS service uses bindings in jaxb-binding.xml or jaxws-binding.xml the namespace attribute must be updated. Use the new namespace https://jakarta.ee/xml/ns/jaxb.

If your JAX-WS service uses global bindings, the global-bindings.xml file must be updated according to the following example:

Listing 1. Example global-bindings.xml
<jaxb:bindings version="3.0"    (1)
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb">  (2)
<jaxb:globalBindings>
  <!-- your global mappings here -->
</jaxb:globalBindings>
</jaxb:bindings>
1 Update to version 3.0
2 Update to namespace https://jakarta.ee/xml/ns/jaxb

UI Server: Multipart Request Configuration

As part of the switch to Jakarta EE the third party library dependency to Apache File Upload was eliminated. Scout now relies on plain Jakarta EE API to process HTTP multipart requests. Servlets processing multipart requests using Jakarta EE API requires a multipart-config in their servlet registration.

Deployment Using web.xml

If you use a web.xml-based deployment (legacy only, see Removal of .war Modules), make sure to add a <multipart-config> section to your web.xml where the UiServlet is registered:

Listing 2. Example multipart-config in web.xml of Scout UI server
<servlet>
<servlet-name>UiServlet</servlet-name>
<servlet-class>org.eclipse.scout.rt.ui.html.UiServlet</servlet-class>
<multipart-config>
  <location>/tmp</location>
  <max-file-size>104857600</max-file-size> (1)
  <max-request-size>104857600</max-request-size>   (2)
  <file-size-threshold>20971520</file-size-threshold>   (3)
</multipart-config>
</servlet>
1 Maximum size of single file, e.g. 100mb
2 Maximum size of multi-part request, e.g. 100mb
3 Threshold for file chunking, e.g. 20mb
Deployment using Jetty server

If you switch to a Jetty-based deployment (see chapter Former JettyServer for Development Can Be Used in a Productive Environment for details) a default multipart configuration providing the ability to upload multipart requests with unlimited size is used by default (see chapter UIServlet). This corresponds to the same behavior as using the former Apache File Upload based implementation.

Unlimited request size means, there is no global request size limit at level of the UI servlet. In practice the upload size is limited by implementations of IUploadable and the corresponding implementations in various JSON form fields, see getConfiguredMaximumUploadSize() implementations for default value for each type of field: e.g. AbstractFileChooserField.getConfiguredMaximumUploadSize.

See UiServletMultipartConfigProperty and the config property scout.ui.servletMultipartConfig to provide a custom global multipart request configuration for your UI server.

Other Libraries

  • Mockito 5: Uses the inline mock maker as new default and change the behavior of any(), which does not match varargs anymore (use any(Class) instead).

Removed Deprecated Methods in ICacheBuilder and IFormHandler

The deprecated method ICacheBuilder#withAtomicInsertion was removed. No migration is required, as this method did not change behavior in any way.

The method IFormHandler#getHandlerId was removed without a replacement as there is no use for it.

Former JettyServer for Development Can Be Used in a Productive Environment

org.eclipse.scout.dev.jetty.JettyServer was so far only used for development environments. With this release it was improved so that it can be used in a productive environment too (instead of building a .war file to be used in an application server). The Scout Application class contains a main-method which may be started directly and itself starts an embedded Jetty server.

The support for using a web.xml was dropped when using the Scout Application, IServletContributor and IServletFilterContributer are used instead (see web.xml and Removal of .war Modules).

The following renaming/refactoring is applied.

Modules

  • org.eclipse.scout.dev.jetty → org.eclipse.scout.rt.app

    • Check dependencies within pom.xml

These modules were removed:

  • org.eclipse.scout.dev.jetty.test

  • org.eclipse.scout.dev.jetty.test.affix

Java classes

  • org.eclipse.scout.dev.jetty.JettyServer → org.eclipse.scout.rt.app.Application

    • Check run configurations etc.

Properties

  • scout.jetty.port → scout.app.port

  • scout.jetty.consoleInputHandler → scout.app.consoleInputHandlerEnabled

  • scout.jetty.webapp.contextpath → scout.app.contextPath

  • scout.jetty.keyStorePath → scout.app.keyStorePath

  • scout.jetty.autoCreateSelfSignedCertificate → scout.app.autoCreateSelfSignedCertificate

  • scout.jetty.keyStorePassword → scout.app.keyStorePassword

  • scout.jetty.privateKeyPassword → scout.app.privateKeyPassword

  • scout.jetty.certificateAlias → scout.app.certificateAlias

The following property was removed (not required anymore due to the drop of web.xml support)

  • scout.jetty.webapp.folder

Improved .app module structure

For each server (i.e. single server for Scout JS and UI/backend server for Scout Classic application), the following modules are used to build or run the application:

  • .app: main module serving as base for all dependencies

    • .app.dev: used for development

    • .app.image: used for docker image build

    • .app.zip: used for deployment via shell scripts

Each leaf module (.dev, .image, .zip) contains a config.properties, logback.xml and possible other resources relevant for the corresponding build/application run. Dependencies only relevant for a certain build (e.g. development) must only be added in the corresponding module. Dependencies relevant for all builds should be placed in the .app module. Make sure to move your dependencies accordingly.

The Scout archetypes (Classic and JS) were updated and generate the new .app module structure. Update your project structure as newly defined. This includes the migration from web.xml to servlet contributors and the removal of the .war module(s) as described in the next chapters too.

web.xml

Using a web.xml to define servlet filters and servlet is no longer supported when using the Scout application.

Migrate your entries within the web.xml to static inner classes implementing either IServletContributor or IServletFilterContributor. The static inner classes are placed in a container class in the .app module (i.e. ServerServletContributors, UiServletContributors or AppServletContributor as generated by the Scout archetype).

The contributors are Scout beans, so the module needs a scout.xml file. Copy an existing scout.xml file and paste it under resources/META-INF/scout.xml.

If you haven’t modified the web.xml, all entries as described below are already present in the container class generated by the Scout archetype or provided by dependencies. The new modules org.eclipse.scout.rt.server.app and org.eclipse.scout.rt.ui.html.app provide default servlet (filter) contributors for your Scout application. Make sure to add a dependency to the corresponding module in your .server.app and .ui.html.app modules. Only add own servlet (filter) contributors for those not already defined within the two container classes ServerServletContributors and UiServletContributors.

The @Order annotation might differ from the examples below. Make sure to add them in incrementing order (e.g. interval of 1000) within your container class (own order for servlet filters, own order for servlets).

WebappEventListener

<listener>
  <listener-class>org.eclipse.scout.rt.server.commons.WebappEventListener</listener-class>
</listener>

No migration required, automatically handled by the Scout application.

Listeners (e.g. HttpSessionMutex)

<listener>
  <listener-class>org.eclipse.scout.rt.server.commons.HttpSessionMutex</listener-class>
</listener>

results in

@Order(1000)
public static class HttpSessionMutexFilterContributor implements IServletFilterContributor {

  @Override
  public void contribute(ServletContextHandler handler) {
    handler.addEventListener(new HttpSessionMutex());
  }
}

Applies to other listeners too.

Servlet filter contributor for HttpSessionMutex is already provided by org.eclipse.scout.rt.ui.html.app.UiServletContributors.

Filters (e.g. HttpServerRunContextFilter)

<filter>
  <filter-name>HttpServerRunContextFilter</filter-name>
  <filter-class>org.eclipse.scout.rt.server.context.HttpServerRunContextFilter</filter-class>
  <init-param>
    <param-name>session</param-name>
    <param-value>false</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>HttpServerRunContextFilter</filter-name>
  <url-pattern>/api/*</url-pattern>
</filter-mapping>

results in

@Order(2000)
public static class ApiServerRunContextFilterContributor implements IServletFilterContributor {

  @Override
  public void contribute(ServletContextHandler handler) {
    FilterHolder filter = handler.addFilter(HttpServerRunContextFilter.class, "/api/*", null);
    filter.setInitParameter("session", "false");
  }
}

Applies to other filters too (init-params may be different/may not exist).

Servlets

<servlet>
  <servlet-name>api</servlet-name>
  <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
  <init-param>
    <param-name>jakarta.ws.rs.Application</param-name>
    <param-value>org.eclipse.scout.rt.rest.RestApplication</param-value>
  </init-param>
  <init-param>
    <param-name>jersey.config.server.wadl.disableWadl</param-name>
    <param-value>true</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>api</servlet-name>
  <url-pattern>/api/*</url-pattern>
</servlet-mapping>

results in

@Order(3000)
public static class ApiServletContributor implements IServletContributor {

  @Override
  public void contribute(ServletContextHandler handler) {
    ServletHolder servlet = handler.addServlet(ServletContainer.class, "/api/*");
    servlet.setInitParameter(ServerProperties.WADL_FEATURE_DISABLE, Boolean.TRUE.toString());
    servlet.setInitParameter(ServletProperties.JAXRS_APPLICATION_CLASS, RestApplication.class.getName());
    servlet.setInitOrder(1); // load-on-startup
  }
}

Applies to other servlets too (init-params may be different/may not exist, load-on-startup flag too).

UIServlet

<servlet>
  <servlet-name>UiServlet</servlet-name>
  <servlet-class>org.eclipse.scout.rt.ui.html.UiServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>UiServlet</servlet-name>
  <url-pattern>/*</url-pattern>
</servlet-mapping>

results in

@Order(2000)
public static class UiServletContributor implements IServletContributor {

  @Override
  public void contribute(ServletContextHandler handler) {
    handler.addServlet(UiServlet.class, "/*");
  }
}

Servlet contributor for UiServlet is already provided by org.eclipse.scout.rt.ui.html.app.UiServletContributors.

Session Config

<session-config>
  <!-- Session timeout in minutes -->
  <session-timeout>5</session-timeout>
  <cookie-config>
    <http-only>true</http-only>
  </cookie-config>
</session-config>

The session cookie config is now handled by the properties:

  • scout.app.httpSessionTimeout (timeout in seconds, default 5 minutes = 300 seconds for non-development mode, 60 minutes = 3600 seconds for development mode)

    • session-config/session-timeout in web.xml (was in minutes, convert to seconds for property)

  • scout.app.sessionCookieConfigHttpOnly (default true)

    • session-config/cookie-config/http-only in web.xml

  • scout.app.sessionCookieConfigSecure (default true for non-development mode)

    • session-config/cookie-config/secure in web.xml

  • scout.app.sessionCookieConfigSameSite (default Lax)

    • context.xml: CookieProcessor attribute sameSiteCookies

The property scout.auth.cookieSessionValidateSecure was removed. It was used in the UiServlet for validation of HTTP only and secure flags (to check if they were correctly defined in the web.xml). Because these two flags are now set via property, an additional property for validation isn’t required anymore.

logbackDisableServletContainerInitializer

<context-param>
  <param-name>logbackDisableServletContainerInitializer</param-name>
  <param-value>true</param-value>
</context-param>

No migration required, automatically handled by the Scout application.

Removal of .war Modules

The build of a .war file to be used within an application server (e.g. Tomcat) is deprecated now and might not work anymore in a further release (due to dependencies issues). Thus, it’s highly recommended to either use shell scripts to run your productive environment as a service or built docker images to be used in Kubernetes or a similar setup. Two new tutorial describe these scenarios in detail.

In case you still like to keep your .war build for now, follow the steps as described below. The examples are based on a classic Scout application with the group id org.eclipse.scout.apps and artifact ID helloscout as created by the archetype.

Create a new module (or keep your old .war modules) for each server with the suffix .app.war similar to .app.image.

  • helloscout.server.app.war

  • helloscout.ui.html.app.war

Place your old config.properties and logback.xml into the src/main/resources directory of the corresponding module. These two files will most likely be similar as the ones in .app.zip.

Place your old web.xml into src/main/webapp/WEB-INF. Some modification might be necessary, see Jakarta migration guide above.

Add entries to your parent pom.xml (within helloscout) referencing these two modules

<modules>
  ...
  <module>../helloscout.server.app.war</module>
  <module>../helloscout.ui.html.app.war</module>
  ...
</modules>

and the dependencies

<dependencyManagement>
  <dependencies>
    ...
    <dependency>
      <groupId>org.eclipse.scout.apps</groupId>
      <artifactId>helloscout.server.app.war</artifactId>
      <version>${org.eclipse.scout.apps.helloscout.version}</version>
    </dependency>
    <dependency>
      <groupId>org.eclipse.scout.apps</groupId>
      <artifactId>helloscout.ui.html.app.war</artifactId>
      <version>${org.eclipse.scout.apps.helloscout.version}</version>
    </dependency>
    ...
  <dependencies>
<dependencyManagement>

The main part of the pom.xml should look like this one (similar for the UI server):

<artifactId>helloscout.server.app.war</artifactId>
<packaging>war</packaging>

<name>Helloscout Server Application</name>

<build>
  <finalName>org.eclipse.scout.apps.helloscout.server</finalName>

  <!-- configure maven-resources-plugin to replace placeholders in resources -->
  <resources>
    <resource>
      <directory>${project.basedir}/src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
</build>

<dependencies>
  <dependency>
    <groupId>org.eclipse.scout.apps</groupId>
    <artifactId>helloscout.server.app</artifactId>
    <exclusions>
      <!-- exclusions required because for running in a tomcat, we must not include jetty -->
      <exclusion>
        <groupId>org.eclipse.jetty</groupId>
        <artifactId>jetty-webapp</artifactId>
      </exclusion>
    </exclusions>
  </dependency>

  <!-- provided by container -->
  <dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <scope>provided</scope>
  </dependency>
</dependencies>

Make sure to not forget the exclusion of jetty-webapp.

For the UI server’s pom.xml, additionally add the following section within the build tag.

<build>
  ...
  <plugins>
    <!-- configure maven-resources-plugin to use '\' as escape character  -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-resources-plugin</artifactId>
      <configuration>
        <escapeString>\</escapeString>
      </configuration>
    </plugin>
  </plugins>
</build>

Now when building your application, this should result in two .war files that can be deployed to an application server. As mentioned before, this might not be supported anymore in a future release of Scout.

Deprecation of WebappEventListener

org.eclipse.scout.rt.server.commons.WebappEventListener was responsible for the following tasks when the servlet context was initialized/destroyed:

  • Starting/stopping the Scout plattform

  • Setting context path to PlatformIdentifier

  • Registering the servlet context as accessible bean (ServletContext)

The first task remains, the other two were removed (see next two sections).

WebappEventListener is still available and might be used for legacy applications running within an application server (see Removal of .war Modules), but it is marked as deprecated and might be removed in a future release.

Removal of PlatformIdentifier

org.eclipse.scout.rt.platform.context.PlatformIdentifier was removed with replacement. Because deploying to an application server is legacy only, each application will have its own Java runtime and NodeIdentifier can be used instead.

ServletContext Not Accessible via BEANS.get/.opt Anymore

ServletContext could be accessed via BEANS.get/.opt so far because it was registered via WebappEventListener. It was only used within ServletContextMimeTypeDetector to ask the servlet context for its mime type mapping. This mime type detector was removed too.

Cleanup/Improving of NodeIdentifier#compute

NodeIdentifier previously used the first property with a value according to the following priority:

  1. scout.nodeId

  2. weblogic.Name

  3. jboss.node.name

As fallback a newly generated UUID was used.

Only the first one (scout.nodeId) is considered now because not running within an application server anymore.

Newly added was the computation of a node identifier in development mode. If no scout.nodeId is set, the local host name and the port of the Scout application is used as node identifier (e.g. mycomputer:8082). Therefore, for development mode, setting scout.nodeId in config.properties is not required anymore to have a static node identifier.

Add Streaming Support to Hashing (SecurityUtility)

org.eclipse.scout.rt.platform.security.SecurityUtility supports streaming:

  • byte[] hash(byte[] data, byte[] salt) → byte[] hash(byte[] data)

    • Use the new method where possible, if required use ILegacySecurityProvider.createHash(byte[] data, byte[] salt).

  • NEW: DigestInputStream toHashingStream(InputStream stream)

  • NEW: DigestOutputStream toHashingStream(OutputStream stream)

IdExternalFormatter Removed

The former deprecated class IdExternalFormatter was removed. This class was replaced by IdCodec and IdInventory in release 23.

Apache HttpComponents Client 5.2.x

With Scout version 7 the usage of Apache HttpComponents Client was introduced (for example for communication between frontend and backend server). At that time version 4.5.3 was used which received only minor updates between releases (for major defects and security issues), version 24.1 of Scout upgrades the Apache HTTP Client to the next major version - now version 5.2.x is used.

Scout does not depend itself on an older Apache HttpComponents Client version anymore; however the new client version can be co-located with earlier major version on the same classpath as package names and maven coordinates have been changed.

This may result in changes if your project references (imports) Apache HttpComponents classes itself, e.g. org.apache.http.HttpHeaders has been moved to org.apache.hc.core5.http.HttpHeaders, org.apache.http.impl.client.HttpClientBuilder has been moved to org.apache.hc.client5.http.impl.classic.HttpClientBuilder, for further details the Apache HttpClient 5.x migration guide may be consulted (at the moment the classic API is still used to avoid too many changes).

There is also behavior and API which has changed, the following behavioral changes have been noticed during development:

  • org.eclipse.scout.rt.shared.http.EnhancedLaxRedirectStrategy is removed, this strategy previously enforced a second HTTP POST request for certain HTTP redirect status codes (e.g. 302 Found). According to RFC 9110 in this case the POST request may be replaced with a GET request which the HttpClient will now respect. For redirects which require to re-send the POST request a different status code must be used (e.g. 307 Temporary Redirect). The config property scout.http.redirectPost has been removed.

  • Internal test org.eclipse.scout.rt.server.commons.http.HttpRetryTest.testPostWithUnsupportedRetryAndFailureWhileHeadersAreSent has been removed as retry-strategy has been changed, requests failing with a org.apache.hc.core5.http.ConnectionClosedException while sending the request are not retried anymore in general, furthermore only idempotent requests will be retried by default. However, the Scout specific implementation to retry requests dealing with a stale socket channel is kept (regardless of the request method).

For third-party dependencies which refer to an older HttpClient version either both versions will co-exist (see above) or it is necessary to search for updated third-party versions which reference the new version of the HttpClient.

To use the new version with the Google HTTP Client library a org.eclipse.scout.rt.shared.http.transport.ApacheHttpTransport is introduced (as the third party library itself does not support the newer version yet as the library itself refers to an older HttpClient version this older version is explicitly excluded).

For org.eclipse.scout.rt.server.commons.servlet.HttpProxy the Google HTTP Client library is not used anymore, instead a new class org.eclipse.scout.rt.shared.http.async.DefaultAsyncHttpClientManager (configurable using a config property) is used. The new concept uses the HttpClient directly as async variant. org.eclipse.scout.rt.shared.http.transport.ApacheHttpTransport still uses the classic variant.

org.eclipse.scout.rt.shared.http.BasicAuthHttpTransportManager was removed, users may provide pre-emptive basic authentication using a custom org.apache.hc.client5.http.protocol.HttpClientContext for specific hosts (e.g for the HttpProxy using org.eclipse.scout.rt.server.commons.servlet.HttpProxy.withHttpClientContextSupplier).

Login Form: Support for Second-Factor (Form-Based)

During form-based login, for second-factor enabled accounts, a token is requested (after first challenge has been completed successful). For this token a new text ui.Token has been added to the login form and must be added to the WebContent/login.html if you plan to use 2FA.

<scout:message style="tag" key="ui.Login" key="ui.LoginFailed" key="ui.User" key="ui.Password" key="ui.Token" />

To enable 2FA support in your application, see Two-factor Authentication.

UiTextContributor

The interface org.eclipse.scout.rt.ui.html.IUiTextContributor has changed its signature. The function contributeUiTextKeys has been renamed to contribute. All implementations of this interface must rename this method as well.

TypeScript CodeType API Changes

The TypeScript API to access CodeTypes and Codes has been streamlined and simplified:

  • codes utility

    • codes.get: only accepts one parameter now (for the CodeType class or CodeType id). Accordingly, it no longer returns a Code but a CodeType instead. Furthermore, it no longer throws an error if the CodeType could not be found but returns null instead. To access a Code within a CodeType use codes.get(MyCodeType).get(myCodeId).

    • codes.optGet and codes.codeType: has been deleted in favor of the new codes.get (see above).

  • CodeType

    • CodeType.add: has been marked protected as it should not be called from the outside.

    • CodeType.get: Throws no error anymore if the requested Code could not be found but returns null instead.

    • CodeType.optGet: Has been deleted as CodeType.get can be used now (see above).

    • CodeType.codes: It is no longer a property but a function instead which by default returns all Codes of the CodeType recursively. It has a parameter which allows to only return the root Codes.

    • CodeType.getCodes: has been removed. Use the new function CodeType.codes() instead (see above).

Tree: Improved Auto-Check Behavior When Checking Nodes

New Behavior Explained

When the autoCheckChildren property of the Tree or TreeBox widget is set to true (e.g. by overriding getConfiguredAutoCheckChildNodes()) the automatic check behavior has changed.

Assuming the following tree structure is given:

[ ] Node A
  [ ] Child node 1
  [ ] Child node 2


Legend:
[ ] -> Node unchecked
[-] -> Node partly-checked
[*] -> Node checked

Example 1

When checking or unchecking 'Node A' all its children are checked/unchecked too.

[*] Node A
  [*] Child node 1    <- Automatically checked
  [*] Child node 2    <- Automatically checked

Example 2

When some of the child nodes are checked, the parent nodes get partly-checked.

[-] Node A            <- Partly checked
  [*] Child node 1
  [ ] Child node 2

When 'Child Node 2' gets checked too, the parent node is checked automatically. Attention: The mechanism of auto-checking the parent is new. It may break the logic in your application.

[*] Node A            <- Automatically checked
  [*] Child node 1
  [*] Child node 2

API Changes in AbstractTree

execAutoCheckChildNodes

Before this change, the auto-check logic was implemented in Java and JavaScript. The org.eclipse.scout.rt.client.ui.basic.tree.AbstractTree#execAutoCheckChildNodes method implemented the logic on Java side. This method was removed. The complete auto-check logic is now only on JavaScript side.

Checking All Nodes

To check all nodes of a tree in java, it was possible to check the root node while autoCheckChildren was true. This is no longer supported. The new best practice is to use the org.eclipse.scout.rt.client.ui.basic.tree.AbstractTree#checkAllNodes method.

// No longer supported
tree.setNodeChecked(tree.getRootNode(), true);

// Use this
tree.checkAllNodes();

IOUtility: Removed Duplicate Method getFileExtension

Method getFileExtension from FileUtility should be used instead.