Eclipse Scout: Migration Guide

After the final Eclipse Photon release, there are no more Eclipse service releases (see the Simultaneous Release Cycle FAQ for details). Scout 8.0 will continue to be maintained for a while and a new build may be released from time to time. Beside bugfixes, these releases may even contain some minor features.

The following changes were made after the initial 8.0 release.

The required Java Runtime Environment (JRE) to run an Eclipse Scout application has changed: Starting with Eclipse Scout 8.0, a Java 8 runtime is required.

To reflect this change, some existing Scout classes have been migrated to the newly available Java 8 classes:

Removed deprecated method Date[] getCoveredDays() on org.eclipse.scout.rt.client.ui.basic.calendar.CalendarComponent.

Migration: Use Range<Date> getCoveredDaysRange() instead with start and end date.

Abstract implementation was replaced by default method in interface ICacheValueResolver.

Migration: Implement interface ICacheValueResolver directly instead of extending AbstractCacheValueResolver.

The methods SequenceBox#getConfiguredEqualColumnWidths(), SequenceBox#isEqualColumnWidths() and SequenceBox#setEqualColumnWidths() have been deprecated. As this property was not used by Scout since several releases it can be deleted.

You can search for these method names in your code to find any usages. Alternatively your IDE may mark the usage of deprecated methods (depends on settings).

Since the new Html UI was introduced with Scout 5.2 some constants and methods in ClientUIPreferences had no effect on the UI anymore. Since Scout is now a browser application we don’t have any control over the application window anymore. The form bounds are stored in the local browser storage thus they’re not required in the Java model anymore.

The following constants/methods were dropped:

Since the new Html UI was introduced with Scout 5.2 the property focusable had no effect on the UI anymore. Instead the UI uses sensible defaults for each field type. For instance: a LabelField is never focusable, a normal StringField is always focusable, as long as it is enabled. Since the property was rarely used, we removed the related code:

Migration: Since there is no replacement for the focusable property, remove all code that uses one of the methods/properties listed above.

In Scout 7.0 a new smart field implementation named SmartField2 was created. The old implementation was still available, but its use was discouraged. With Scout 8.0 the old SmartField implementation was finally dropped. The new implementation SmartField2 was renamed back to SmartField.

The following table lists the different names used in the past Scout releases. (The naming applies to all associated files, such as interfaces, abstract field classes, Java packages and JavaScript and LESS files.)

Migration:

The base class and interfaces of the old SmartField implementation was IContentAssistField. With the new SmartField implementation this interfaces and all classes containing the word "ContentAssist" in their name, have been either removed or renamed to "SmartField". If your code references one of these classes you should simply try to rename all references. Since the API of the new SmartField is almost the same as the old, this should work and should cause no or few changes in your code. The following classes have been removed without replacement:

Since the new SmartField implementation does not have a proposal chooser model anymore these classes have also been removed. If you must have a special implementation of a proposal chooser, you must implement a proposal chooser in JavaScript (see: ProposalChooser.js), which renders the data and lookup rows it receives from the server-side SmartField. The following classes have been removed without replacement:

The property minWidthInPixel has been moved to LogicalGridLayoutConfig.

Migration: Instead of using getConfiguredMinWidthInPixel you should now set the property as follows:

The goal was to harmonize all the init methods (initField, initTile, initForm etc.) and to make sure, init() is only executed once. This is important for dynamic widgets like accordion or tiles. These widgets initialize the newly added children by themselves so that the caller does not need to take care of it. For these cases it is important that init() is not called multiple times.

But: there may be cases which require init() to be called multiple times, like reseting a search form. For such cases, reinit() has to be used from now on. Also, after the widget is disposed, init() may be called again. So remember: execInit may be called more than once in some circumstances. This is existing behavior!

We also renamed the initConfig guard of IFormField from isInitialized to isInitDone to make clear what initialization has been done. It has furthermore been moved to AbstractWidget so that individual widgets don’t have to care about it and to use the same pattern as for init and dispose.

These new methods (init(), dispose() and reinit()) handle the whole widget tree including all child widgets recursively. Child items that need initialization and are NO widgets must be initialized explicitly as it is already now. All children that are widgets must NOT be initialized because this is done automatically by the AbstractWidget implementation. To modify that behavior use the methods initChildren() or disposeChildren() (e.g. if you want to exclude a child widget from automatically getting initialized). This also means that the methods ActionUtility.initActions(), ActionUtility.disposeActions(), FormUtility.postInitConfig(), FormUtility.initFormFields() and FormUtility.disposeFormFields() have been removed because the corresponding method can be called directly on the instance instead. Use widget.init() or widget.dispose() instead of these utility functions.

Please note that the phase postInit has been removed for the items that supported it. The corresponding code can be moved to the end of the initConfigInternal() method instead.

We also renamed the initConfig guard of IFormField from isInitialized to isInitDone to make clear what initialization has been done. It has furthermore been moved to AbstractWidget so that individual widgets don’t have to care about it and to use the same pattern as for init and dispose.

Migration:

If you used one of the deprecated methods (initField, initAction etc.), replace them with one of the following methods: init, reinit or initInternal.

Replaced init parameters get_pattern and post_pattern with content_types. If you set these init parameters in your web.xml, replace or remove them accordingly.

The argument pathInfo has been removed from the method HttpCacheControl.checkAndSetCacheHeaders since it has no effect anymore.

HTTP Proxy doesn’t set cache control no-chache header anymore.

A new tree visitor engine has been added to the org.eclipse.scout.rt.platform.util.visitor package. It contains classes to depth-first or breadth-first traverse any tree data structures. Use the class org.eclipse.scout.rt.platform.util.visitor.TreeTraversals as entry point.

This new visitors can be used on any widget and tree node. It replaces the former IActionVisitor, ITreeVisitor and IFormFieldVisitor. The org.eclipse.scout.rt.client.ui.IWidget interface also declares various overloads accepting java.util.function.Consumer, java.util.function.Function and the new org.eclipse.scout.rt.platform.util.visitor.IDepthFirstTreeVisitor and org.eclipse.scout.rt.platform.util.visitor.IBreadthFirstTreeVisitor. Depending on how much control and data you need for your visitor the matching type can be used.

Until now only pre-order visitors have been available on these items. Therefore the migration to the new visitor takes the following steps:

There are new methods for setting mandatory state (setMandatory), status visibility (setStatusVisible), field style (setFieldStyle) and disabled style (setDisabledStyle) that allow to specify if child form fields should be changed as well.

So if you have overridden one of these methods in your code, please override the new one instead. The method now takes an additional boolean flag to indicate if children should be processed as well.

The new config property scout.cspDirective makes subclassing and replacing the ContentSecurityPolicy class obsolete as you can configure all CSP settings with this property now. An example from the Scout Widgets application:

This class was deleted and replaced by a config property in config.properties:

The methods handleGet and handlePost on IUiServletRequestHandler were replaced by the single method handle. This new method is called for all HTTP methods.

To retrieve the HTTP method, call getMethod on HttpServletRequest. When using AbstractUiServletRequestHandler no migration should be required because AbstractUiServletRequestHandler delegates to the Java methods for the common HTTP methods handleGet, handlePost, handlePut and handleDelete.

Methods proxyGet and proxyPost on HttpProxy are replaced by the common method proxy.

We removed remnants of the long-obsolete "population" event in tables:

Migration: Remove any references to the removed method or event from your code. (This should not cause any change in behavior, as the event was not fired by Scout anyways.)

The table field contained in a PageField used to have statusVisible set to false. This default was changed back to true to make it consistent with all other fields. Whether the status should be invisible can only be determined correctly by the programmer, because the PageField can not know about the status visibility in the inner forms (search form and search form).

Migration: To hide the status of a specific PageField's table field, override execInitField() and set the desired status visibility:

The Scout REST integration uses the popular Jackson library as default marshaller. When migrating to Scout 8.x add a maven dependency to jersey-media-json-jackson in your application pom.xml to use Jackson as JAX-RS marshaller with the Jersey JAX-RS implementation. Additionally add a dependency to the Scout module org.eclipse.scout.rt.rest.jackson. This module adds a set of Jackson additions in order to use the Jackson library together with Scout data objects.

The SmartField in Scout ⇐ 6.0 applied the lookup-row properties foregroundColor, backgroundColor, font and tooltipText automatically on the field when a lookup-row has been selected. Because that automatic behavior didn’t fit every business requirement, we removed it completely. This means you must implement the property-synchronization where required.

Since we prefer to do styling with CSS and LESS, we now copy the cssClass property from the lookup-row to the field. In some cases this new feature can be used to migrate from older Scout version.

Check the HowTo section SmartField: how to apply colors and styles from a lookup-row in Scout’s technical guide to find examples for migration and how to work with the cssClass property.

For migration, simply remove any references to this class.

The classes AbstractDynamicNlsTextProviderService, ITextProviderService, ScoutTexts and TEXTS have been moved from the shared module to the platform. Accordingly the package of these classes has been changed to org.eclipse.scout.rt.platform.text.

Migration: Change the imports in your *.java files accordingly.

The following classes were moved from org.eclipse.scout.rt.shared.mail to a new module named org.eclipse.scout.rt.mail to the package org.eclipse.scout.rt.mail:

For migration, replace all imports for org.eclipse.scout.rt.shared.mail by imports for org.eclipse.scout.rt.mail and add a dependency to the new module org.eclipse.scout.rt.mail.

A new helper org.eclipse.scout.rt.mail.smtp.SmtpHelper replaces the service org.eclipse.scout.rt.server.services.common.smtp.ISMTPService and it’s abstract implementation org.eclipse.scout.rt.server.services.common.smtp.AbstractSMTPService.

The only remaining property is SmtpDebugReceiverEmailProperty (scout.smtp.debugReceiverEmail).
The following properties are obsolete and configuration must be set in org.eclipse.scout.rt.mail.smtp.SmtpServerConfig:

SmtpHelper has no support for subject prefix and default from email anymore.

If a subject prefix is required, i.e. the property SmtpSubjectPrefixProperty (scout.smtp.subjectPrefix) was in use, the subject prefix must be prepended to the subject before calling SmtpHelper by using MailHelper.addPrefixToSubject.

If a default from email is required, i.e. the property SmtpDefaultFromEmailProperty (scout.smtp.defaultFromEmail) was in use, the default from email must be ensured before calling SmtpHelper by using MailHelper.ensureFromAddress.

The following classes are marked deprecated:

A new helper org.eclipse.scout.rt.mail.imap.ImapHelper provides some basic (stateless) functionality to connect to an IMAP server, find and create folders or move message to a new folder. Any other functionality must be implemented manually by operating on javax.mail.Message or javax.mail.Folder objects directly.

The following properties are obsolete and configuration must be set in org.eclipse.scout.rt.mail.imap.ImapServerConfig:

MailHelper#createMimeMessage was improved regarding the structure of the generated mime message. So far a multipart message was always created, even if a simpler structure would have been enough. The new implementation only creates the required parts depending on the provided input: plain text, html, attachments and inline attachments (newly supported).

In order to be able to reuse authentication token code DefaultAuthToken was refactored. Signing and verifying of tokens is now separated from token and its (de-)serialization. The new classes DefaultAuthTokenSigner and DefaultAuthTokenVerifier do now provide this functionality.

The StyleHelper bean was moved from org.eclipse.scout.rt.client to org.eclipse.scout.rt.platform, so it is available to server-side code as well. The old StyleHelper bean in the client module was marked as deprected and should no longer be used. It will eventually be removed in Scout 10.

Migration: Update your imports to point to the new org.eclipse.scout.rt.platform.html.StyleHelper bean. Methods that passed an IStylable as first argument are no longer available. Instead, directly call the corresponding method on the IStylable element itself.

The implementation of AbstractEntityRestClientExceptionTransformer was change an this might break implementation of sub-classes. Please refer to JavaDoc for any details.

The org.eclipse.scout.rt.shared.servicetunnel.HttpException was replaced by org.eclipse.scout.rt.sharedservicetunnel.http.HttpServiceTunnelException which is derived from the new, general org.eclipse.scout.rt.platform.exception.RemoteSystemUnavailableException. The HttpServiceTunnelException is thrown within the UI server, when a call to the Scout backend server (through the HTTP service tunnel) was unsuccessful and returned a status code < 200 or >= 299. The RemoteSystemUnavailableException and therefore its subclass HttpServiceTunnelException is finally displayed as network error by the global org.eclipse.scout.rt.client.services.common.exceptionhandler.ErrorPopup. The new RemoteSystemUnavailableException may generally be thrown to indicate an error when the communication with a remote service failed.

If you created a custom theme, you might have to adjust some LESS variables.

The clone() function of any widget got an options parameter. The options define what properties and events are synchronized between the widget and its clone.

The methods addChild() and removeChild() have been renamed to _addChild() and _removeChild(). This means the methods are considered to have private visibility now. Use the methods setParent(), setOwner() and destroy() to connect or disconnect widgets. These methods will add or remove the child widget automatically.

The visit() method on all FormFields has been renamed to visitFields(). This change is necessary to clarify what is visited and to distinguish between the visit methods available on widget level (e.g. visitChildren()).

The argument order of the method scout.Tree.visitNodes have changed from (nodes, func, parentNode) to (func, nodes, parentNode). So the func (the visitor) and the nodes to visit have changed positions.

The arguments of scout.Tree.prototype._visitNodes have changed from (nodes, func, parentNode) to (func, parentNode). So the nodes to visit must no longer be specified. Instead always the root nodes of the tree are used. Furthermore the method is public now and has therefore be renamed to visitNodes().

Scout can now detect the web fonts (*.woff) to preload automatically. It’s therefore no longer necessary to list the font names manually in the bootstrap argument of scout.App.

Migration:

Remove the fonts property from the bootstrap parameter object passed to the init() function of your Scout app.

For example, the default index.js file generated by the Scout "helloworld" archetype looks like this:

If no other init options remain, the file can be simplified to:

This migration is recommended but optional. Listing all fonts to preload manually still works. To disable font preloading entirely, set the fonts bootstrap property to an empty array [].

Until now it was required to explicitly set grid positions for child fields of Radio Button Groups and Sequence Boxes. This was because the automatic grid layout was not yet implemented in the Scout JavaScript layer. This was no issue however if the fields have been used in connection with a Java model because then the Java layer takes care about the layout.

Now also pure JavaScript Scout applications have automatic layout for child fields of Radio Button Groups and Sequence Boxes. So if explicit grid positions (gridData.x, gridData.y) have been specified, it can be removed now as Scout takes care about it now (as it was in the Java layer already).

open() now calls load() first before calling show(). The reason is to prevent showing an empty form before any data is loaded. If you relied on the previous behavior, (e.g. if you accessed ui properties like $container right after opening the form) you would need to put that code in a function executed delayed using form.open().then().

The static function scout.Status.warn() was renamed to scout.Status.warning() to bring it in line with the name of the corresponding severity constant scout.Status.Severity.WARNING.

In previous versions, right aligned menus were not stacked when there was not enough horizontal space. If this behavior is still required, the property stackable has to be set to false.

The custom LookupRow constructor with key and text parameter was removed. LookupRows must be created using the scout.create() object factory call.

Old style code like:

must be replaced by:

Call objects no longer perform retries by default. Retries should only be active if the target service can handle repeated calls correctly.

The use retries, specify the desired number of maximal retries or a retryIntervals array in the model when creating the Call object:

Because errors that happen in asynchronous calls (promise chains) are not delegated to the window.onerror handler, Scout’s ErrorHandler class was extended. It can now be used to handle arbitrary erros in "catch" clauses or "promise fail" functions. As a consequnce, the signature of the handle() has been changed. It used to be hard-wired to the window.onerror event. Now it supports a flexible number of arguments.

A global instance of ErrorHandler is still being installed as the window.onerror handler. Additionally, this instance is now available as scout.errorHandler.

Example usages:

Migration:

Projects that implemented their own ErrorHandler must update their code.

Smart fields and date fields use the property touch to indicate that the field is running in touch mode. Unfortunately this property overrides the function touch() of the FormField. This means touch() cannot be used for these fields, which was not intended.

Migration: The property touch is actually set automatically, so most people don’t have to migrate anything. If you set the property manually (e.g. to always run such a field in touch mode), you need to rename it to touchMode.

The jQuery version bundled with Scout has been updated to version 3.3.1. If a SpecRunnerMaven.html is used to run Jasmine tests, the corresponding script tag must be updated to include jquery-3.3.1.js instead of jquery-3.2.1.js.