View source for Riena Migrating to 2.0 from 1.2

{{#eclipseproject:rt.riena}}
== Introduction ==

Explains how to migrate to Riena 2.0 from 1.2. 

While every effort was made to avoid breakage, there are a few areas of incompatibility or new APIs that should be adopted by clients. This page describes those areas and provides migration instructions.

== API Incompatibilities ==

=== SimpleNavigationNodeProvider - Removed register methods ===
The following methods have been removed:
* register(ISubApplicationNodeExtension, INavigationAssembler assembler)
* register(IModuleGroupNodeExtension, INavigationAssembler assembler)
* register(IModuleNodeExtension, INavigationAssembler assembler)
* register(ISubModuleNodeExtension, INavigationAssembler assembler)
In the old implementation of SimpleNavigationNodeProvider these methods do nothing.

=== INavigationNodeView without controller as generic argument ===
INavigationNodeView does not longer needs a controller as generic argument (but still a INavigationNode). The information about the controller was never used. ({{bug|288045}})

So all sub classes of INavigationNodeView (e.g. SubModuleView) are a little bit simpler.

Old implementation of INavigationNodeView (or SubModuleView) can simply remove the generic argument of the controller.

=== SubModuleController & IWindowRidget - Removed getDefaultButton() and setDefaultButton(...) methods ===

The above methods have been removed. They did not work consistently and did support only a single default button. Use <tt>SubModuleController.addDefaultAction(IRidget focusRidget, IActionRidget action)</tt> instead. For an example showing how to use this new API refer to DefaultButtonSubModule{View,Controller}. ({{bug|291708}})

=== SwtApplication - Removed abstract getBundle() method ===
Any subclass of SwtApplication needed to implement the abstract method getBundle(). However that method was never called. We have removed that method from the class. Leaving your code is no problem, but is also no benefit.

=== IComboRidget - Removed six obsolete methods ===

The following methods were never implemented. They would always throw an UnsupportedOperationException.

* boolean isAddable()
* boolean isListMutable()
* boolean isReadonly()
* void setAddable(boolean addable)
* void setListMutable(boolean mutable)
* void setReadonly(boolean readonly)

They have been removed in 2.0.

=== IStatuslineRemoved - Removed hidePopups() method ===

This method was never implemented (empty body) and is never called. It has been removed in 2.0.

=== ITextRidget - Removed getAlignment() and setAlignment(int) methods ===

SWT does not support changing the alignment after creating a Text widget. In 1.2 all occurrences of these methods have intentionally thrown an UnsupportedOperationException. These methods have been removed in 2.0. ({{bug|239979}})

=== TextRidget - Changed parameter type in protected addListeners(...) and removeListeners(...) methods ===

Previously, addListeners(...) and removeListeners(...) would accept a Control argument but expect it to be a Text instance. This behavior was documented in the javadoc. With 2.0 the type of the argument has been changed from Control to Text. Because the method is protected, the change only affects custom subclasses of TextRidget that override this method, which is not a typical case. To migrate just change the type from Text to Control.

<source lang="java">
// Old:
protected synchronized void addListeners(Control control) {
  Text text = (Text) control;

// New:
protected synchronized void addListeners(Text control) {
  // ...

// Old:
protected synchronized void removeListeners(Control control) {
  Text text = (Text) control;

// New:
protected synchronized void removeListeners(Text control) {
  // ...
}
</source>

=== IColumnFormatter - Removed getLeftPadding(), added getLeftIndent() method ===
The method "boolean getLeftPadding(Object)" was replaced by the method "int getLeftIndent(Object)". Now it is possible do define more than one indent per cell of a table.

''Note: At the moment this property is only used with the SCP widgets MatrixTable and MatrixDetailsComposite.

=== I18N ===

* Plugin org.eclipse.riena.example.client: Move Message.java, messages.properties to package org.eclipse.riena.example.client.nls
* Plugin org.eclipse.riena.ui.ridgets: Move Message.java, messages.properties to package org.eclipse.riena.ui.ridgets.nls.
* Plugin org.eclipse.riena.ui.ridgets.swt: Move Message.java, messages.properties to package org.eclipse.riena.ui.ridgets.swt.nls
* Plugin org.eclipse.riena.ui.swt: Move Message.java, messages.properties to package org.eclipse.riena.ui.swt.nls

=== UIControlsFactory - Removed two-argument createButtonXYZ(...) methods ===

Most two-argument methods in this class take a String label as the 2nd argument. Some two-argument methods took the String bindingId as the 2nd argument. To avoid confusion the later methods have been removed (Bug #305061). 

The removed methods are:

* createButtonCheck(Composite, String bindingId) - use createButtonCheck(Composite, String, String) 
* createButtonRadio(Composite, String bindingId) - use createButtonRadio(Composite, String, String) 
* createButtonToggle(Composite, String bindingId) - use createButtonToggle(Composite, String, String)

=== UIControlsFactory - Removed createCompositeTable(...) method ===

For making Riena compatible with RAP we require that the org.eclipse.riena.ui.swt bundle is free of optional dependencies, such as the CompositeTable widget. For that reason the method UIControlsFactory.createCompositeTable(...) has been removed. Use OptionalUIControlsFactory.createCompositeTable(...) instead. This class is found in the org.eclipse.riena.ui.ridgets.swt.optional bundle.

=== INavigationAssembler ===

With the new extension point "org.eclipse.riena.navigation.assemblies2" it was necessary to add some properties and change the signature of some methods.

New properties: 
* id
* parentNodeId
* startOrder

New signature:
* buildNode: returns an array of navigation nodes (INavigationNode<?>[]) instead a single node
* getAssembly/setAssembly: return/parameter are from type INavigationAssembly2Extension

For this interface exits the abstract class AbstractNavigationAssembler. This class already stores the new properties.

The old extension point "org.eclipse.riena.navigation.assemblies" is still supported. It will be converted - on the fly - into the new structure. Only the two elements foreach and assembly are not converted. They will be ignored.

=== AbstractMasterDetailsComposite - changed return type for getButtonXYZ() methods ===

The methods getButtonApply(), getButtonNew(), getButtonRemove() now return an generic Control instance instead of a Button. This was done to allow using Button '''and/or''' ImageButton widgets for the buttons. Existing callers of these methods must downcast to Button.

<source lang="java">
// Old:
MasterDetailsComposite comp;
Button btnApply = comp.getButtonApply();

// New:
MasterDetailsComposite comp;
Button btnApply = (Button) comp.getButtonApply();
</source>

=== IExceptionHandlerManager & IExceptionHandler ===
The IExceptionHandlerManager methods and the IExceptionHandler methods return an Action enum object that allows the IExceptionHandler to notify the application about what to do next.

This Action enum was moved from IExceptionHandlerManager (as public inner class) to IExceptionHandler (as public inner class).

The semantic is now that a return value of NOT_HANDLED means that the IExceptionHandlerManager continues to ask other IExceptionHandler. All other return values mean that the chain is interrupted and the Action is returned to the application.

The concreate meaning of OK, CANCEL or RETRY is up to the calling application.

=== IUISynchronizer ===
IUISynchronizer now provides the methods syncExec and asyncExec. "syncExec" blocks until the runnable has been handled by the ui thread. "asyncExec" immediately returns after placing the runnable in the ui event queue.
The "synchronize" method has been removed.
=== RienaDefaultLnf/ILnfTheme ===
<code>ILnfTheme</code> has changed completely. Instead of revealing its internal data structures there is now a dedicated interface <code>ILnfCustomizer</code> to perform the customization.
Within the ''old'' themes you had something like:
<pre>
public void addCustomColors(Map<String, ILnfResource> table) {

	table.put(LnfKeyConstants.TITLELESS_SHELL_FOREGROUND, new ColorLnfResource(255, 255, 255));
	table.put(LnfKeyConstants.TITLELESS_SHELL_PASSIVE_FOREGROUND, new ColorLnfResource(128, 128, 128));
	table.put(LnfKeyConstants.TITLELESS_SHELL_BACKGROUND, getPrimaryBackground());
..
public void addCustomFonts(Map<String, ILnfResource> table) {

	table.put(LnfKeyConstants.TITLELESS_SHELL_FONT, getPrimaryFont());
..
public void addCustomImages(Map<String, ILnfResource> table) {

	table.put(LnfKeyConstants.TITLELESS_SHELL_BACKGROUND_IMAGE, new ImageLnfResource(IMAGE_BACKGROUND));
..
public void addCustomSettings(Map<String, Object> table) {

	table.put(LnfKeyConstants.SHELL_HIDE_OS_BORDER, hideOsBorder());
..
</pre>
This has to be refactored in something like this:
<pre>
public void customizeLnf(ILnfCustomizer lnf) {
	lnf.putLnfResource(LnfKeyConstants.TITLELESS_SHELL_FOREGROUND, new ColorLnfResource(255, 255, 255));
	lnf.putLnfResource(LnfKeyConstants.TITLELESS_SHELL_PASSIVE_FOREGROUND, new ColorLnfResource(128, 128, 128));
	lnf.putLnfResource(LnfKeyConstants.TITLELESS_SHELL_BACKGROUND, getPrimaryBackground());
..
	lnf.putLnfResource(LnfKeyConstants.TITLELESS_SHELL_FONT, getPrimaryFont());
..
	lnf.putLnfResource(LnfKeyConstants.TITLELESS_SHELL_BACKGROUND_IMAGE, new ImageLnfResource(IMAGE_BACKGROUND));
..
	lnf.putLnfSetting(LnfKeyConstants.SHELL_HIDE_OS_BORDER, hideOsBorder());
</pre>

Instead of setting a theme in your L&F with:
<pre>
public ExampleLnf() {
	super();
	setTheme(new ExampleTheme());
}
</pre>
we recommend to use:
<pre>
public ExampleLnf() {
	super(new ExampleTheme());
}
</pre>



== Other Changes ==

=== hash code of NavigationNode ===
The generating of the hash code of the class NavigationNode has changed. The property ''label'' is not longer used for the generation. So the only important property is the ''nodeId''.

Corresponding to this the equals method also ignores the property ''label''.

Because of that ensure that every node has a NavigationNodeId.

=== UIProcess work progress ===
Now the progress inside an UIProcess is interpreted as IProgressMonitor.worked describes. This is the new default behaviour. You can switch to a cummulative mode by setting the ProgresStrategy of the UIProcess (UIProcess.setProgresStrategy(ProcessInfo.ProgresStrategy strategy))


[[Category:Riena]]