EMF Forms Migration Guide

This guide describes necessary steps and relevant changes when updating to a new version of EMF Forms. See this tutorial for a general introduction of the framework. In the first section, we describe the migration of the view models, which works similarly for all updates. See the table in this section to know if a migration is necessary. In the following sections, we describe migration guidelines for specific versions.

How to migrate view models when updating EMF Forms

In general, the view model of EMF Forms has been very stable in the latest releases. However, when driving the framework forward, we sometimes need to change the view meta model in an incompatible way. This would mean, the existing view models could not be loaded anymore. In this case, the view model tooling of EMF Forms provides a migration mechanism based on Edapt (see here for technical details).

Please note that the automatic migration is available since the release of 1.5.1. Please also note, that Eclipse Luna SR2 contains 1.5.0, which does not yet support automatic migration. We therefore highly recommend, you install at least version 1.5.1 from our download page.

In order to start the migration you simply need to open all your view models using the view model editor (double click on them in the IDE). If a migration is required you will be notified and may veto the execution. Since 1.7.0, EMF Forms also provides runtime migration as a fall back (see section “Migration to 1.7.0”), but we recommend to migrate all view models explicitly.

⇒ Find out more about Developer Support and Training or contact us.

⇒ Further Documentation for EMF Forms

Migration to 1.7

Due to breaking model changes (see below) in the core, existing view models need to be migrated for use with 1.7. This can be done by simply opening all your view models in your IDE.

Control Label-Alignment: Pre-1.7 versions of EMFForms offered “Left” and “None” as options for a control’s label alignment. “Left” was being used as the default. By request we have added a further option “Top”.

To decrease the need of specifying a label-alignment we also introduced an option called Default. With this option the renderer will chose a label-alignment option which is most suitable for the environment. This option replaces “Left” as the new default. Our view model migration will take care that legacy view models with the old default label alignment will be migrated so that “Left” is used.

Runtime Migration

With 1.7 we also introduce the possibility to migrate view model during runtime when using our XMI Extension View Provider. Simply include the org.eclipse.emf.ecp.view.edapt.feature (and its dependencies) to your product/run configuration. This feature is optional, so you are not forced to introduce Edapt dependencies in your product.

Migrating view model during runtime is not recommended because the migration needs to take place on every application startup. This feature is intended to serve as a fallback, if a legacy view model was not migrated at development time and made its way to production code. So please migrate your view models proactively.

Migration of View Model Extensions

With 1.7 we changed the nsURI of our core view model in order to allow Edapt to migrate existing view models. If you have created your own models that extend classes from the core view model, e.g. your own DomainModelReference, then you have to recompile your model. This is due to Java inlining of constant values, see https://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.4.9 .

New interface for Databinding Service

With 1.7 we added an additional interface implemented by the existing databinding service. When using EMF as a domain model, most existing callers of the databinding service (“EMFFormsDatabinding”) already cast the returned IValueProperties to EStructuralFeatures. We decided to make this dependency explicit, and add an additional interface called “EMFFormsDatabindingEMF“, which is EMF specific. It directly returns an EStructualFeature, if required. All existing default controls in EMF Forms expect the EMFFormsDatabindingEMF.

The refactoring also affects the SPI: To resolve the databindings, the new service internally uses a new interface: DomainModelReferenceConverterEMF. We thus updated all DomainModelReferenceConverter to implement the new DomainModelReferenceConverterEMF interface, as well. If you use an own DomainModelReferenceConverter implementation and you are using the EMF Forms controls, please update it to implement DomainModelReferenceConverterEMF.

Migration to 1.6

Localization changes: old NLS message.properties are invalid, new place is the OSGI-INF/l10n/ the file now is named bundle.properties (more details see this tutorial)

New Feature: View Model Localization: (more details see this tutorial)

Use EMFFormsRendererFactory instead of deprecated SWTRendererFactory

EMF Forms Services: Take a look at the EMF Forms services, when implementing renderer

Custom Renderer: The constructor of custom renderers is not called using reflection, thus it is not empty anymore.

Prior to EMFForms 1.6 renderers were registered using the extension point “org.eclipse.emf.ecp.ui.view.swt.renderers”. Although, this is still supported,we advise to migrate. Since 1.6 renderers are provided using an OSGi Service, all services required by renderer are passed in via the constructor (either manually by the framework or by dependency injection). To ease the migration we added an extension point: org.eclipse.emfforms.swt.core.di.extension.renderers. This allows you to use the existing ECPRendererTester and renderer.

The following example shows the registration of a renderer and the corresponding tester:

<extension point="org.eclipse.emfforms.swt.core.di.extension.renderers">
      <renderer class="com.eclipsesource.example.MyCustomControlSWTRendererDI"
            tester="com.eclipsesource.example.MyCustomControlSWTRendererECPTester">
      </renderer>
   </extension>

MyCustomControlSWTRendererECPTester extends the ECPRendererTester as before. This way the existing renderer testers can be reused. The MyCustomControlSWTRendererDI is the existing Renderer implementation updated with a new constructor. This constructor retrieves all required parameters using dependency injection and passes them on to the super constructor. The constructor is therefore annotated with @Inject. The resulting class declaration and constructor looks like this:

public class MyCustomControlSWTRendererDI extends SimpleControlSWTControlSWTRenderer {
  @Inject
  public MyCustomControlSWTRendererDI(VControl vElement, ViewModelContext viewContext, ReportService reportService, EMFFormsDatabinding emfFormsDatabinding, EMFFormsLabelProvider emfFormsLabelProvider, VTViewTemplateProvider vtViewTemplateProvider) {
    super(vElement, viewContext, reportService, emfFormsDatabinding, emfFormsLabelProvider, vtViewTemplateProvider);
  }
...
}

By using this extension point you are only required to update your constructor and add the annotation. Everything else is handled by EMFForms. For new renderers we recommend to use OSGi Services for registration as described here.

New Bundles

For the 1.6.0 release, we have started to move EMF Form specific parts into new bundles with a new and shorter name space. If you use our pre-configured features, they are already adapted (we recommend to configure run configurations and products feature based). If you configure your product or run configuration bundle-based, please add the following new bundles:

• org.eclipse.emfforms.common
• org.eclipse.emfforms.core.services
• org.eclipse.emfforms.core.services.databinding.featurepath
• org.eclipse.emfforms.core.services.editsupport
• org.eclipse.emfforms.core.services.emf
• org.eclipse.emfforms.core.services.emfspecificservice
• org.eclipse.emfforms.core.services.locale.default
• org.eclipse.emfforms.localization
• org.eclipse.emfforms.swt.core
• org.eclipse.emfforms.swt.core.di
• org.eclipse.emfforms.swt.core.di.extension

⇒ Find out more about Developer Support and Training or contact us.

⇒ Further Documentation for EMF Forms