Eclipse Scout: Migration Guide

The following changes were made after the initial 7.0 release (Eclipse Oxygen release). Additionally follow these instructions when updating to a service release.

The following new Scout modules have been added to support REST services with Jackson as marshaller:

In order to use REST services based on the JAX-RS Jersey implementation, the following section must be added to the project web.xml:

The RestApplication class searches for all implementations of IRestResource and exposes them as REST services.

When a user performs two consecutive clicks on a button or a menu within a very short period of time, the action is executed twice. In some cases, this is an unwanted behavior. A new property "preventDoubleClick" was added to IButton and IMenu to disable it (see release notes).

In older Scout versions, two flags (m_enabledProcessing and m_enabledProcessingAction, respectively) were use to accomplish a similar objective. Whenever the click/action handler was started, the flag was set to false, and set back to true at the end of the execution. A second call to the method had no effect. However, this logic no longer works since the introduction of the HTML UI. The new UI strictly allows only one UI event to work on the client model simultaneously (subsequent click events are hold back by the UiSession lock). Consequently, the "enabledProcessing" flag is never false, and no clicks are prevented.

Because this construct no longer works, the corresponding properties and methods were removed, namely:

Migration: Delete any code that references any of the removed methods. There is not replacement, as the whole concept became disfunctional with the HTML UI. To prevent accidental double clicks, use the new getConfiguredPreventDefault() property. If for very rare and special cases such a flag is required, it has to be implemented manually by overriding AbstractButton.doClick() and AbstractAction.doAction().

If your application previously used a custom (not provided by Scout) implementation of the org.eclipse.scout.rt.shared.servicetunnel.http.HttpServiceTunnel class a migration might be necessary. For the service tunnel and a few other HTTP usages a new HTTP abstraction layer (Google HTTP Client 1.22) was introduced to support different low-level HTTP libraries (previously just the java.net.HttpURLConnection was used). The new default low-level HTTP library is the Apache HTTP Client 4.5.3, more details are available in the release notes. As the java.net connections are not used anymore by default the MultiSessionCookieStore (for java.net connections) is not installed by default (could be installed manually).

For the HttpServiceTunnel`class the method `URLConnection createURLConnection(ServiceTunnelRequest call, byte[] callData) has been replaced by HttpResponse executeRequest(ServiceTunnelRequest call, byte[] callData), also several methods (addCustomHeaders, addSignatureHeader, addCorrelationId, createAuthToken and interceptHttpResponse) signatures have changed their URLConnection parameter to either a HttpRequest or HttpResponse parameter. The same migration applies for subclasses of the org.eclipse.scout.rt.server.commons.servlet.HttpProxy class.

The function getGridColumnCount() returned the calculated column count of the grid. This has been changed so that it returns the configured one which is not necessarily the same.

Example: the default of the property gridColumnCount is -1 which will typically result in 2 columns.

So in case you used this method, you should consider calling getFieldGrid().getGridColumnCount() instead.

Removed support for session scope specific ScoutTexts instances because support of scoped services was removed in Scout without OSGi (version >= 5.0).

Changes:

Deprecations (methods will be removed in P-release):

The parameter $parent has been removed from the _render method because this.$parent is available for every widget. There is no need to have a parameter $parent which points to the same variable. Use this.$parent instead.

Also $parent is now optional when calling widget.render(). The $parent may be resolved using this.parent. No need to always write widget.render(this.$container) anymore, instead just write widget.render() if the $container of the parent should be used as $parent.

With jQuery 3 the promise API is now Promises/A+ compliant. This means you may need to adjust your code if you use promises.

We noticed the following effects:

See also https://jquery.com/upgrade-guide/3.0/ for details.

These functions are now supported by jQuery directly. Just use addClass, removeClass, attr and removeAttr.

The property change event has been simplified.

The event had 3 properties:

This was added to be able to react to multiple property change events at once. Since 6.1, bulk property changes don’t exist anymore, so there is no need for these properties anymore.

Now, with 7.0, the property change event has the following properties:

This makes handling the event easier. Check your propertyChange event handlers and adjust them accordingly.

Automatic Grid Data Validation has been introduced. This means there is no need to manually create a Logical Grid (e.g. VerticalSmartGroupBoxBodyGrid or HorizontalGroupBoxBodyGrid and validate it anymore, this will be done by the LogicalGridLayout itself. Also, check your JSON files, remove any explicit x, y grid definitions because they will be calculated by the LogicalGrid. Make sure to always use the property gridDataHints instead of gridData.

The naming of the events has been harmonized to conform with the event naming guide. This is only relevant, if you attached listeners using JavaScript or if you do some kind of load testing using the events in the requests.

The following changes have been made:

The naming of the functions of scout.graphics and scout.HtmlComponent has been harmonized. Also, they now consistently use an options parameter.

The following changes have been made:

scout.graphics:

scout.HtmlComponent:

The old methods still exists but are marked as deprecated. Note that getBounds does not include margins anymore, and bounds and offsetBounds now take an options object instead of 2 boolean parameters.

scout.Widget had a function called requestFocus. Some concrete widgets provided a function named focus. Because there is no need to have two methods doing the same, these functions have been merged. scout.Widget now provides a function focus. RequestFocus has been deprecated.

When creating a table using JavaScript and scout.create('Table'), specifying the index for each column has been necessary. This has changed, the column indices are now set automatically based on the order of the columns. Just remove the index settings from your JSON files.

The life cycle has been reworked and simplified:

To migrate: check your forms, remove the life cycle, use the new callback functions and system menus if needed, adjust your custom life cycles.

Every form needs a root group box. That box has the flag mainBox set to true. Until now, this has to be set explicitly. From now on, you can omit it. To migrate just remove the mainBox flags.

In Maven dependencies with the scope provided are not transitive. This makes sense if a dependency is set to provided depending on the environment. Any artifacts that are not intended to be used in a certain environment should not have the scope provided and are therefore now transitive. We removed any current dependency javax.servlet:javax.servlet-api except for the one in the artifact org.eclipse.scout.rt.server.commons.

To migrate your project, remove any dependency to javax.servlet:javax.servlet-api, javax.xml.ws:jaxws-api or javax.ws.rs:javax.ws.rs-api. Then add to all artifacts with packaging type war the dependency to javax.servlet:javax.servlet-api with scope provided. Depending on the container, you may want also to add the depdendency javax.xml.ws:jaxws-api with scope provided to the war artifact.