Papyrus/Migration Guide/Neon

Papyrus 2.0 API Migration Guide

Download the guide as a printable PDF document.

This document provides a guide to migrating applications that extend Papyrus to the new 2.0 version APIs. In the 2.0 (Neon) release, several refactorings were implemented to fix problems of invalid bundle dependencies. These dependencies are of two kinds:

• dependency on Eclipse UI and/or SWT in bundle that should provide only headless API
• dependencies that violate the Papyrus layer architecture. For example, bundles in the "Infra" layer using UML or GEF APIs, bundles in the core NatTable component using diagram APIs, etc.

In most cases, these refactorings are simply moving types from one bundle to another bundle that is better suited to hosting them. As such, migration generally requires one or two steps:

1. Updating imports to change package names: type names are usually not changed, but the package namespaces do change to reflect the new containing bundle name
2. Adding new bundle dependencies to bring the new packages into the classpath. This step will sometimes not be required when the bundle to which a type was moved is already on the dependent bundle's classpath

Owing to the Papyrus project's policy prohibiting Require-Bundle re-exports, it will sometimes be necessary to change your bundles' dependencies in this migration task even when none of the APIs that it uses are moved, because of refactorings in the transitive dependencies of APIs that your bundles do use.

Migration details are presented by Papyrus component/layer and theme in the following sections.

Some refactorings are done in a more compatible fashion, by deprecating APIs and providing replacements, usually in a lower-level layer. These cases are self-documenting and are flagged in client code by new deprecation warnings, so they are not addressed in this document.

Infra Layer

UI Dependencies

APIs Moved out of the infra.tools Bundle

Several UI-dependency classes are moved from the org.eclipse.papyrus.infra.tools bundle to org.eclipse.papyrus.infra.ui. These simply require package renames in imports and adding the infra.ui bundle dependency.

Some packages are moved in their entirety (* replaces the prefix org.eclipse.papyrus):

Old Package	New Package
*.infra.tools.converter	*.infra.ui.converter
*.infra.tools.dnd	*.infra.ui.dnd
*.infra.tools.messages	*.infra.ui.messages
*.infra.tools.preferences	*.infra.ui.preferences
*.infra.tools.preferences.ui.dialog	*.infra.ui.preferences.dialog

And in the org.eclipse.papyrus.infra.tools.util package, several individual types are moved to org.eclipse.papyrus.infra.ui.util:

• AbstractCreateMenuFromCommandCategory
• EclipseCommandUtils
• EditorHelper
• ICallableWithProgress
• LocalMemento
• SelectionHelper
• UIUtil
• WorkbenchPartHelper

The UIUtil API for asynchronous code execution

The UIUtil class presents some interesting use cases. It is often used by clients to provide a simple means of deferring execution of some block of code or ensuring that some code is executed on the UI thread, even in an otherwise headless API (usually because it is known or assumed that common use cases for that API are initiated by an application UI). To that end, a new API is introduced in the org.eclipse.papyrus.infra.tools bundle that provides a headless-compatible access to this UI execution capability:

• org.eclipse.papyrus.infra.tools.util.CoreExecutors. This new class is intended to provide access to a variety of useful Executor implementations for asynchronous execution of code. The getUIExecutorService method provides one such executor for posting code to the UI thread. If there is no UI thread because the application is a headless Eclipse instance, then this executor simply uses a daemon thread as per the standard Java platform single-thread executor service
• org.eclipse.papyrus.infra.tools.util.IExecutorService. This extension of the Java Platform ExecutorService interface provides methods for synchronous execution of Runnables and Callables on the UI thread. The UI executor service provided by the CoreExecutors class implements that protocol using Display.syncExec when the UI is available

APIs Moved out of the infra.core Bundle

Several UI-dependent APIs are moved out of the org.eclipse.papyrus.infra.core bundle into org.eclipse.papyrus.infra.ui, most notably the IMultiDiagramEditor interface and its related service APIs.

Some packages are moved in their entirety:

Old Package	New Package
*.infra.core.contentoutline	*.infra.ui.contentoutline
*.infra.core.editor.reload	*.infra.ui.editor.reload
*.infra.core.editorsfactory	*.infra.ui.editorsfactory.anytype
*.infra.core.editorsfactory.anytype	*.infra.ui.editorsfactory
*.infra.core.extension.commands	*.infra.ui.extension.commands
*.infra.core.extension.diagrameditor	*.infra.ui.extension.diagrameditor
*.infra.core.lifecycleevents	*.infra.ui.lifecycleevents
*.infra.core.multidiagram.actionbarcontributor	*.infra.ui.multidiagram.actionbarcontributor

In the org.eclipse.papyrus.infra.core.editor package, several types were moved to a new org.eclipse.papyrus.infra.ui.editor package:

• ContentProviderServiceFactory
• CoreMultiDiagramEditor
• DiSashModelManagerServiceFactory
• DiSashModelMngrServiceFactory
• IMultiDiagramEditor
• IPapyrusPageInput
• IReloadableEditor
• MultiDiagramEditorSelectionContext
• MultiDiagramPropertySheetPage
• PageIconRegistryServiceFactory
• PageMngrServiceFactory
• PapyrusPageInput

And in the org.eclipse.papyrus.infra.core.util package, several individual types are moved to org.eclipse.papyrus.infra.ui.util:

• DisplayUtils
• EditorUtils
• PapyrusImageUtils — note that the icon resources are also moved
• ServiceUtilsForActionHandlers
• ServiceUtilsForWorkbenchPage

The service utilities API

The AbstractServiceUtils class and its subclass present some interesting use cases for the API migration. The AbstractServiceUtils class in the 1.x release provided the following methods that were accessible through all of the concrete utility subclasses:

• getIPageMngr(T): IPageMngr
• getIPageManager(T): IPageManager
• getILifeCycleEventsProvider(T): ILifeCycleEventsProvider
• getISashWindowsContainer(T): ISashWindowsContainer
• getNestedActiveEditorPart(T): IEditorPart

These methods were all convenient shortcuts and are simply deleted in the 2.0 API. There is no sensible way to move them because the types that exposed these methods must remain accessible in a headless context, but the APIs that they return are strictly UI-dependent. Clients must change to access these services using the standard getService(Class<?>, T) method. In the case of the nested active editor part, the replacement is

    ServiceUtilsForXyz.getInstance().getService(
        ISashWindowsContainer.class, xyz).getActiveEditor();

Also, the ServiceUtilsForActionHandlers class is used by many clients to access the services in the currently active Papyrus editor, where the calling context doesn't actually know what that editor is. This worked by looking for the Platform UI's active editor and getting its service registry. That obviously doesn't work in the context of the now headless org.eclipse.papyrus.infra.core bundle, so a new OSGi service is defined that allows the core AbstractServiceUtils API to access this current-editor-context service registry. Clients that depend on this capability can now, if they no longer have access to the ServiceUtilsForActionHandlers API (which is deprecated anyways), get it thus:

    ServiceUtils.getInstance().getServiceRegistry(null); // to get the registry
    ServiceUtils.getInstance().getModelSet(null);        // To get the ModelSet
    ServiceUtils.getInstance().getService(IPageManager.class, null); // Others

Bundle Re-exports Removed from the infra.core Bundle

Although it was in contravention of Papyrus project policy, the 1.x version of the org.eclipse.papyrus.infra.core bundle re-exported its dependency on the org.eclipse.papyrus.infra.core.sasheditor.di bundle for its DI/sash-windows model and other APIs. This is an overtly UI-dependent bundle, so it is no longer used by the infra.core bundle in Papyrus 2.0 and therefore is not re-exported. Clients that relied on this re-export will have to add it explicitly. Moreover, the EMF model that was provided by that bundle is moved to another new bundle, as discussed below.

APIs Moved out of the infra.emf Bundle

A few UI-dependent packages are moved from in their entirety from the org.eclipse.papyrus.infra.emf bundle to a new org.eclipse.papyrus.infra.ui.emf bundle (* replaces the prefix org.eclipse.papyrus):

Old Package	New Package
*.infra.emf.databinding	*.infra.ui.emf.databinding
*.infra.emf.dialog	*.infra.ui.emf.dialog
*.infra.emf.providers	*.infra.ui.emf.providers
*.infra.emf.providers.strategy	*.infra.ui.emf.providers.strategy

One class is moved from the org.eclipse.papyrus.infra.emf.adapters package to org.eclipse.papyrus.infra.ui.emf.adapter:

• EObjectAdapterFactory

One class is moved from org.eclipse.papyrus.infra.emf.utils to org.eclipse.papyrus.infra.emf.utils:

• ProviderHelper

In fact, the org.eclipse.papyrus.infra.ui.emf.utils.ProviderHelper class now also has a getCustomizationManager() method that should now be used instead of the same method on the org.eclipse.papyrus.infra.emf.Activator class to access the EMF Facet customization manager.

One class is moved from the org.eclipse.papyrus.infra.emf.utils package to org.eclipse.papyrus.infra.ui.converter in the org.eclipse.papyrus.infra.ui bundle:

• EMFStringValueConverter

and several others are moved to the org.eclipse.papyrus.infra.ui.util package because they have nothing to do with the EMF component, specifically:

• ServiceUtilsForHandlers
• ServiceUtilsForIEvaluationContext
• ServiceUtilsForSelection

Finally, note that, although the org.eclipse.papyrus.infra.emf bundle no longer has any UI dependencies in version 2.0, the EMFHelper::getEObject(Object) utility API still can unwrap selections from the Model Explorer and other views based on the EMF Facet tree model nodes that encapsulate the business objects being presented.

APIs Moved out of the infra.core.sasheditor.di Bundle

The infra.core.sasheditor.di bundle in the 1.x version performs two distinct functions: defining an EMF model for the editor layout in the *.di (and also *.sash) resource, and implementing a sash-windows content provider (from the infra.core.sasheditor bundle) based on this DI model. Unfortunately, the latter adds a UI dependency to the bundle, so that headless code cannot make use of the DI model API.

The DI model packages are moved into their own bundle, better aligning with the usual EMF code generation pattern. The following packages are now provided by the org.eclipse.papyrus.infra.sashwindows.di bundle:

• org.eclipse.papyrus.infra.core.sashwindows.di
• org.eclipse.papyrus.infra.core.sashwindows.di.exception
• org.eclipse.papyrus.infra.core.sashwindows.di.impl
• org.eclipse.papyrus.infra.core.sashwindows.di.util

This new bundle is now a dependency of the infra.core bundle, which continues to use the DI model API. However, it is not re-exported as the infra.core.sasheditor.di dependency was in the 1.x version, so clients of the DI model API that got it "for free" from infra.core must now add an explicit dependency on infra.core.sashwindows.di.

Similarly, the IPageManager API does still need to be accessible by client code in a headless context in order to maintain the integrity of the DI/Sash model references to pages, especially when the notation views that they reference are deleted. This is necessary whether they are presented in an editor or not. A part of this is the particles of edit advice that clean up page-references to deleted objects. Accordingly, the following classes are moved from the org.eclipse.papyrus.infra.core.sasheditor.di bundle to org.eclipse.papyrus.infra.core.sashwindows.di along with the DI model, itself:

Old Type	New Type
*.sasheditor.contentprovider.IPageManager	*.sashwindows.di.service.IPageManager
*.sasheditor.contentprovider.service.ILocalPageService	*.sashwindows.di.service.ILocalPageService
*.sasheditor.contentprovider.service.AbstractLocalPageService	*.sashwindows.di.service.AbstractLocalPageService

Along with these, the IPageUtils::getMemoizedCloseAllPagesCommand() method is moved to the org.eclipse.papyrus.infra.core.sashwindows.di.util.DiUtils class. Also, the org.eclipse.papyrus.infra.core.sasheditor.contentprovider.PageMngr class, which implemented the deprecated IPageMngr interface, is moved to org.eclipse.papyrus.infra.core.sashwindows.di.service.BasicPageManagerImpl as a headless implementation of the IPageManager service. It includes support for the legacy PageList object in the DI model and is specialized, as the PageMngr was previously, by the UI-based PageManagerImpl in the org.eclipse.papyrus.infra.core.sasheditor.di bundle.

API Moved out of the infra.constraints Bundle

The org.eclipse.papyrus.infra.constraints.providers.ConstraintTypeContentProvider class is moved to a new bundle infra.constraints.ui as org.eclipse.papyrus.infra.constraints.ui.providers.ConstraintTypeContentProvider.

More significantly, the signatures of API methods that accepted ISelection or IStructuredSelection (which are JFace UI types) now accept more plastic Object and Collection<?> parameters, respectively:

• IConstraintEngine::getDisplayUnits(Object selection) (and hence the same in the DefaultConstraintEngine class) no longer requires an ISelection
• Constraint::match(Collection<?> selection) (and hence the same in AbstractConstraint and CompoundConstraint) no longer requires an IStructuredSelection

Note that the default implementation of the getDisplayUnits(Object) API accepts arguments in a variety of shapes, from which it tries to get or create a collection to pass along to its constraints:

• incoming nulls are coerced to empty collections
• incoming collections are taken as they are
• incoming objects that offer a no-argument collection coercion method such as asSet() or toList() or similar (which includes the IStructuredSelection type) will be converted to a collection via that method
• other objects will be wrapped in a singleton collection

APIs Moved out of the infra.services.edit Bundle

The ElementTypeValidator class is moved from the org.eclipse.papyrus.infra.services.edit.utils package to the org.eclipse.papyrus.infra.services.ui.dialogs package in a new org.eclipse.papyrus.infra.services.ui bundle.

APIs Moved out of the infra.onefile Bundle

Several UI-dependent packages are moved out of the infra.onefile bundle into a new org.eclipse.papyrus.infra.onefile.ui bundle. However, most of these contained only internal APIs and were not exported at all, so clients should not be affected.

One package is partially moved:

Old Package	New Package
*.infra.onefile.providers	*.infra.onefile.ui.providers

The following types in the onefile.providers package were moved to the new onefile.ui.providers package:

• PapyrusContentProvider
• PapyrusLabelProvider
• PapyrusViewerSorter

The OneFileModelProvider class remains in the headless infra.onefile bundle and other classes are now internal in the UI bundle because they were not public API:

• CopyToClipboardAction
• OneFileDecorator
• PapyrusEditActionProvider
• PapyrusModelActionProvider
• SubresourceFileActionProvider

Finally, some APIs are changed on the sub-type level:

• the IPapyrusElement::getImage() method is removed. This is simply incompatible with a headless execution environment and is an incorrect placement of the responsibility, anyways, which in Eclipse is served by label providers. Thus, the implementations of this API are now provided exclusively by the PapyrusLabelProvider class in the UI bundle
• several API methods are moved from the OneFileUtils class into a new class org.eclipse.papyrus.infra.onefile.ui.utils.OneFileUIUtils:
  • getActivePage()
  • getEditorID(IEditorInput)
  • isOpenInEditor(Object)
  • openInEditor(Object, boolean)
  It is doubtful that any of these should have been used by clients in the first place, as they are all redundant with similar utilities provided now by the infra.ui bundle (formerly by the infra.core bundle).

GEF 3 Dependencies

To support the introduction of diagrams based on the new GEF 4 API, dependencies on the GEF 3 API need to be isolated as much as possible from the core GMF-based diagram infrastructure in Papyrus. Also, because GEF implies a UI dependency, dependencies on GEF APIs in bundles that should be headless also need to be refactored.

Accordingly, some GEF-related refactorings in the Infra Layer may need to be accounted for by clients.

APIs Moved out of the infra.core.sasheditor Bundle

The MultiDiagramEditorGefDelegate class is moved from the org.eclipse.papyrus.infra.core.sasheditor.editor package to the org.eclipse.papyrus.infra.gmfdiag.gef.internal.editor package in a new org.eclipse.papyrus.infra.gmfdiag.gef bundle. Note that this API is now internal.

Also, the CoreMultiDiagramEditor class, which itself was moved from the infra.core bundle to infra.ui, has had its gefAdaptor field removed because the GEF dependency in the infra.ui bundle would be illegal. Accordingly, this is now implemented as an external adapter via Eclipse Platform's adapter registry: the CoreMultiDiagramEditorAdapterFactory class in the infra.gmfdiag.gef bundle provides the ActionRegistry adapter via the MultiDiagramEditorGefDelegate.

UML Dependencies

New APIs to Generalize UML-specific Patterns

Replacing Usage of UmlModel

The org.eclipse.papyrus.uml.tools.utils.UmlModel API (often via UmlUtils in the same package) is commonly used in the 1.x releases to access the "semantic model", being the model content that it is the user's intent to edit. This naturally assumes UML content to the exclusion of any other (the Papyrus vision being broader than UML). Several new and updated APIs are now available for a more generic access to the model content:

• in the Language Service, an ILanguage can now be associated with an IModel that provides access to its semantic content in the ModelSet via a new <modelBinding> element in the org.eclipse.papyrus.infra.core.languages extension point. The UmlModel is thus associated with the UML language. The ILanguage interface has a new getModel(ModelSet) : IModel API to get the associated language, if there is one. Similarly, the ILanguageService has a static convenience method getLanguageModels(ModelSet) for obtaining all of the semantic models in a model set that have content
• the IEMFModel interface extending IModel has a new getRootElements() : Iterable<? extends EObject> API providing the root semantic model elements. Thus, for any language models (per above) that implement this interface, they can now provide the actual root semantic model elements that the user is editing. The UmlModel implementation of this API provides the top-most UML elements, excluding stereotype applications or other foreign-schema resource contents
• the Semantic Service now more accurately provides the root semantic model elements, according to the aforementioned language models, instead of all contents of all resources in the set. Also, the SemanticService::getSemanticIModels() API now is implemented, providing the language models as above

Replacing Usage of SemanticUMLContentProvider

Several generic UI components, such as element-chooser dialogs and even the Model Explorer view, have a need to present the semantic model content from the ModelSet to the user. Thus, it was often necessary to construct a SemanticUMLContentProvider as content provider for a TreeViewer. The most appropriate ITreeContentProviders for presentation of model content can now be obtained via the semantic IModels discussed in the previous section:

• a new org.eclipse.papyrus.infra.ui.providers.ISemanticContentProviderFactory interface creates tree-content providers conforming to the specialized Papyrus protocols required for various use cases: IStaticContentProvider, IHierarchiveContentProvider, and IAdaptableContentProvider. The provider factories are self-composable; a composite factory yields composite content providers
• the IModel interface now extends IAdaptable, to provide for adapters of ISemanticContentProviderFactory type. Thus, for any semantic model (as above) that has a content-provider factory adapter, a suitable tree content provider can be obtained. By composing the factories for all semantic models in the model-set, all potentially heterogeneous semantic content can be presented to the user in a unified view (for example, if there is Ecore content in addition to UML content in the model-set)
• in the 2.0 release, a provider factory adapter is supplied for the UmlModel that creates the SemanticUMLContentProvider used previously

Additionally, the org.eclipse.papyrus.infra.ui.emf.utils.ProviderHelper class provides static convenience APIs for obtaining a language-appropriate content provider for a ResourceSet.

Replacing Usage UML-specific XML Enablement Expression Definitions

Several menu/toolbar contributions in Papyrus are guarded with enablement expressions that are UML-specific, that should be more generally applicable to Papyrus editors on any kind of semantic model. Consider replacing expression definitions as follows

Old Definition/Property	New Definition/Property
*.uml.diagram.common.IsPapyrusActiveWithUMLModel	*.ui.semanticModelActive

Note that the "old definitions" in the left column of the table above are still defined and usable in the appropriate circumstances.

Extension Identifiers Moved out of the uml.diagram namespace

The org.eclipse.papyrus.uml.diagram.ui.toolbar contribution to the Platform toolbars is defined in the org.eclipse.papyrus.infra.ui bundle. Accordingly, its identifier is changed to org.eclipse.papyrus.ui.toolbar to better reflect its role as the Papyrus toolbar.

Diagram Layer Dependencies

NotationModel and NotationUtils

Papyrus supports two kinds of notational views on models: graphical diagrams and tables. Extenders may well implement more. A common use of the NotationModel API (sometimes indirectly via the NotationUtils is the addition of a newly created view (diagram, table) to the *.notation resource of the model currently being edited. This dependency on the NotationModel is not a problem in the case of diagrams, because dependency on the diagram layer in that case is correct. For tables, however, this dependency is a problem. To address that, new APIs are added to the Papyrus Model Set:

• IEMFModel gets new operations canPersist(EObject) : boolean and persist(EObject) : boolean that give client code a generic way to find the proper place to store a new root object such as a notation view
• the ModelSet class gets a new operation getModelToPersist(EObject) : IEMFModel that makes it easy to find the right model with which to add a root element to the most appropriate resource

Diagram Hyperlinks

The org.eclipse.papyrus.infra.hyperlink bundle in the Mars release provides all of the various kinds of Hyperlink supported by the Papyrus diagrams, including links to diagram views. The contribution of the type of hyperlink is moved up into the Diagram Layer. The following types are all moved into the org.eclipse.papyrus.infra.gmfdiag.hyperlink bundle:

Old Type Name	New Type Name
*.infra.hyperlink.helper.EditorHyperLinkHelper	*.infra.gmfdiag.hyperlink.helper.EditorHyperLinkHelper
*.infra.hyperlink.object.HyperLinkEditor	*.infra.gmfdiag.hyperlink.object.HyperLinkEditor
*.infra.hyperlink.ui.EditorHyperLinkEditorShell	*.infra.gmfdiag.hyperlink.ui.EditorHyperLinkEditorShell
*.infra.hyperlink.ui.EditorLookForEditorShell	*.infra.gmfdiag.hyperlink.ui.EditorLookForEditorShell

On-Demand Loading Resource Set

The org.eclipse.papyrus.infra.services.resourceloading.util.LoadingUtils::unloadResourcesFromModelSet(...) variant with the option to refresh diagrams is removed because it was not used within Papyrus. The code that used it was superseded by Papyrus Editor's deferred re-load framework.

Also, the org.eclipse.papyrus.infra.services.resourceloading.preferences bundle is renamed org.eclipse.papyrus.infra.services.resourceloading.ui because the preference page is just one special case of a UI element. All of its APIs, including the StrategyChooser class implementing the IStrategyChooser interface, are now internal. Clients that (for some reason) needed to access the current loading strategy chooser can now access the editor's active IStrategyChooser in the service registry (it is now registered as a service). A new IStrategyChooser::setStrategy(int) : boolean operation is provided to update the active loading strategy.

Table and Diagram Coöperation

Papyrus tables and diagrams support copy/paste back and forth between them. To that end, in the Mars release, the org.eclipse.papyrus.infra.nattable.common bundle provided a Paste Strategy. The IPasteStrategy API is defined in the Diagram Layer because it is design to handle the quirks of pasting in a graphical context. This paste strategy is extract into a new bundle org.eclipse.papyrus.infra.nattable.gmfdiag that can provide any and all table/diagram interoperability function.

Views Dependencies

Properties Model

Several of the Infra Layer bundles (not only diagram infrastructure but also the infrastructure core, including bundles that should be headless) have dependencies in the 1.x releases on the Properties Model from the org.eclipse.papyrus.views.properties.model bundle and also its .edit counterpart for bundles that extend/re-used the properties model. This dependency is a violation of the strictly acyclic dependencies between Papyrus layers.

Accordingly, these model bundles are refactored into the Infra Layer. The bundle names are changed according to the following table

Old Bundle	New Bundle
*.views.properties.model	*.infra.properties
*.views.properties.model.edit	*.infra.properties.edit
*.views.properties.model.editor	*.infra.properties.editor

Along with this, the model API packages are correspondingly renamed:

Old Package	New Package
*.views.properties.contexts	*.infra.properties.contexts
*.views.properties.contexts.impl	*.infra.properties.contexts.impl
*.views.properties.contexts.util	*.infra.properties.contexts.util
*.views.properties.environment	*.infra.properties.environment
*.views.properties.environment.impl	*.infra.properties.environment.impl
*.views.properties.environment.util	*.infra.properties.environment.util
*.views.properties.ui	*.infra.properties.ui
*.views.properties.ui.impl	*.infra.properties.ui.impl
*.views.properties.ui.util	*.infra.properties.ui.util

as well as a non-model package that serves persistence of context and environment models:

Old Package	New Package
*.views.properties.catalog	*.infra.properties.catalog

This moved package includes the PropertiesCatalog EMF resource implementation and the PropertiesURIHandler that implements its ppe: URI scheme.

Extension points are moved or split:

• the org.eclipse.papyrus.views.properties.environment point is renamed org.eclipse.papyrus.infra.properties.environments (note the plural, now) and is otherwise unchanged
• the org.eclipse.papyrus.properties.context point is split into two. A new org.eclipse.papyrus.infra.properties.contexts point (note the plural, now) defines the <context> element for registration of context models. The old extension point is retained, minus the <context> element, for association of contexts with preference pages via the <preferencePageBinding> element

Properties UI

In the 1.x releases, all of the UI APIs for the XWT-based property sheets are in the org.eclipse.papyrus.views.properties bundle. However, this bundle doesn't actually define any view (the Properties View is provided by Eclipse Platform). Moreover, none of the clients of these APIs care that the properties are shown in some view (and in the Neon release the Welcome Page of the editor reuses the framework to present widgets in a totally different context). These APIs are used extensively by bundles in the Infra, Table, and Diagram layers that have nothing to do with specific views.

So, all of the APIs for definition and presentation of properties widgets are factored out of the org.eclipse.papyrus.views.properties bundle into a new org.eclipse.papyrus.infra.properties.ui bundle. The following packages are renamed in the new bundle (note that some packages that were not internal now are):

Old Package	New Package
*.views.properties.creation	*.infra.properties.ui.creation
*.views.properties.extensions	*.infra.properties.internal.ui.observable
*.views.properties.messages	*.infra.properties.internal.ui.messages
*.views.properties.modelelement	*.infra.properties.ui.modelelement
*.views.properties.observable	*.infra.properties.internal.ui.observable
*.views.properties.preferences	*.infra.properties.ui.preferences
*.views.properties.providers	*.infra.properties.ui.providers
*.views.properties.runtime	*.infra.properties.ui.runtime
*.views.properties.util	*.infra.properties.ui.util
*.views.properties.widgets	*.infra.properties.ui.widgets
*.views.properties.widgets.layout	*.infra.properties.ui.widgets.layout
*.views.properties.xwt	*.infra.properties.ui.xwt

Proposition of a Migration Tool

• Download the https://wiki.eclipse.org/images/7/75/Papyrus_neon_migration_xwt.png (nb it is a text file with sed command)
• Execute the following command on any xwt file

sed -f ../migration.png -i *.xwt

Two important changes are made in the ConfigurationManager API:

• the org.eclipse.papyrus.views.properties.runtime.ConfigurationManager class is replaced by a new interface org.eclipse.papyrus.infra.properties.ui.runtime.IConfigurationManager which provides all of the same API that is required by bundles that contribute content to the property sheet. The implementation of the configuration manager is still provided by the org.eclipse.papyrus.views.properties bundle, but the activate manager instance is to be obtained via a new org.eclipse.papyrus.infra.properties.ui.runtime.PropertiesRuntime class (the getConfigurationManager method). The Properties View bundle still implements the entire properties preference storage system
• the ConfigurationConflict class is now internal API; clients providing property sheet content have no need of it

Two extension points are renamed (the first is also divided in two, as described above):

Old Extension Point	New Extension Point
*.views.properties.context	*.infra.properties.ui.context
*.views.properties.labelprovider	*.infra.properties.ui.labelprovider

References to constraints and widgets in the core environment/context models must now reference those models (still via URIs of ppe: scheme) in the new bundle, for example

    <constraintType
        href="ppe:/environment/org.eclipse.papyrus.infra.properties.ui/model/Environment.xmi#//@constraintTypes.0"/>

The namespaces of the core property-sheet widgets likewise must be updated in XWT source files:

Old XWT Namespace	New XWT Namespace
*.views.properties.creation	*.infra.properties.ui.creation
*.views.properties.widgets	*.infra.properties.ui.widgets
*.views.properties.widgets.layout	*.infra.properties.ui.widgets.layout

ElementTypesConfiguration Framework

APIs Moved

Old namespace	New namespace
oep.infra.elementtypesconfigurations	oep.infra.types.core and oep.infra.types
oep.infra.elementtypesconfigurations.edit	oep.infra.types.edit
oep.infra.elementtypesconfigurations.editor	oep.infra.types.editor
oep.infra.elementtypesconfigurations.ui	oep.infra.types.ui
oep.infra.elementtypesconfigurations.invarianttypes	oep.infra.types.rulebased
oep.infra.elementtypesconfigurations.emf	oep.infra.emf.types and oep.infra.emf.types.ui
oep.uml.elementtypesconfigurations	oep.uml.types.core

ElementTypesConfiguration Metamodel Changes

The metamodel for the ElementTypesConfigurations has been changed to improve and fix the possible extensions of this metamodel.

This changes notably distinguish default AdviceBindingConfiguration, EditHelperconfiguration, and MatcherConfiguration from the abstract AdviceBindingConfiguration, EditHelperconfiguration, and MatcherConfiguration that can be extended thanks to org.eclipse.papyrus.infra.elementtypesconfigurations.adviceConfigurationType and org.eclipse.papyrus.infra.elementtypesconfigurations.matcherConfigurationType extension points.

Although these changes don't change the underlying concepts of the elementtypesconfigurations and their extensions, they impact the *.elementtypesconfigurations models created with this metamodel (and their extensions).

You'll find all the details of the changes below. A little developer tool has been developed to assist the migration in the org.eclipse.papyrus.types.dev plugin (namely: org.eclipse.papyrus.dev.types.handlers.MigrateTypesConfigurations).

Migration of the NsURI

Old Namespace URI	New Namespace URI
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/1.0	http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/1.1
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/uml/applystereotypeadvice/1.0	http://www.eclipse.org/papyrus/uml/types/applystereotypeadvice/1.1/
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/invariantstereotyperule/1.0	http://www.eclipse.org/papyrus/uml/types/invariantstereotyperule/1.1
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/uml/settypeadvice/1.0	http://www.eclipse.org/papyrus/uml/types/settypeadvice/1.1
http://www.eclipse.org/payrus/elementtypesconfigurations/uml/stereotypematcherconfiguration	http://www.eclipse.org/papyrus/uml/types/stereotypematcher/1.1
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/invarianttypeconfiguration/containerruleconfiguration/1.0	http://www.eclipse.org/papyrus/emf/types/invariantcontainerrule/1.1
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/emf/runtimevalueseditionadviceconfiguration/1.0	http://www.eclipse.org/papyrus/emf/types/runtimevaluesadvice/1.1
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/emf/setvaluesadviceconfiguration/1.0	http://www.eclipse.org/papyrus/emf/types/setvaluesadvice/1.1
http://www.eclipse.org/papyrus/infra/elementtypesconfigurations/invarianttype/1.0	http://www.eclipse.org/papyrus/infra/types/rulebased/1.1

Migration of the EditHelperAdviceConfigurations

For default interpretation, the xsi:type must be elementtypesconfigurations:EditHelperAdviceConfiguration

For extensions of EditHelperAdviceConfiguration, the editHelperAdviceClassName attribute has been removed.

The name, inheritance and identifier attributes have been removed.

Migration of the AdviceBindingsConfigurations

For default interpretation, the xsi:type must be elementtypesconfigurations:AdviceBindingConfiguration

For extensions of AdviceBindingsConfiguration, the editHelperAdviceClassName attribute has been removed.

The name attribute has been removed.

Migration of the MatcherConfigurations

For default interpretation, the xsi:type must be elementtypesconfigurations:MatcherConfiguration

For extensions of MatcherConfiguration, the matcherClassName attribute has been removed.

Migration of the InvariantTypes

InvariantTypeConfiguration metaclass is now RuleBasedTypeConfiguration

Migration of the RuntimeValuesEditionAdvice

RuntimeValuesEditionAdviceConfiguration metaclass is now RuntimeValuesAdviceConfiguration

Multiple ClientContexts

In Mars loading and unloading elementtypesconfiguration in the registry was done only by specifying a elementtypeconfigurationset Eobject or the path of a model containing an elementtypeconfigurationset to load/unload (because all the configurations were automatically bound to the default Papyrus ClientContext).

In Neon, the identifier of the clientContext the configurations will be bound to must be specified, too.

Changes on loading and unload through the registry singleton

Old API	New API
void loadElementTypeSetConfiguration(String identifier)	boolean loadElementTypeSetConfiguration(String contextId, String path)
void loadElementTypeSetConfigurations(Collection<ElementTypeSetConfiguration> elementTypeSetConfigurations)	boolean loadElementTypeSetConfigurations(String contextId, Collection<ElementTypeSetConfiguration> elementTypeSetConfigurationsToRegister)
void unload(String identifier)	boolean unload(String contextId, String elementTypeSetId)

Changes on the registration of an elementtypeset through the elementTypeSetConfiguration extensionpoint (elementTypeSetConfiguration.exsd)

elementTypeSet.id in Mars was the identifier of the elementTypeSetConfiguration. In Neon, this attribute is removed and a new String attribute elementTypeSet.clientContextID has been added to specify the context in which the elementtypeset is to be registered.

Extension Points

Extension Points that were defined in org.eclipse.papyrus.infra.elementtypesconfigurations moved in org.eclipse.papyrus.infra.types.core.

extensionIDs of those extension points changed like this:

Old extensionID	New extensionID
adviceConfigurationType	adviceConfigurationKind
containerConfigurationType	containerConfigurationKind
elementTypeConfigurationType	elementTypeConfigurationKind
matcherConfigurationType	matcherConfigurationKind

The Extension Point defined in org.eclipse.papyrus.infra.elementtypesconfigurations.invarianttypes moved in org.eclipse.papyrus.infra.types.rulebased.

invariantRule extensionIDs becomes ruleKind

ExtendedTypes Framework

The ExtendedTypes Framework has been completely removed from Neon. The ElementTypesConfiguration Framework (plugins/infra/types) replaces it completely.

The following table shows the ElementTypesConfiguration plugins that replace the ExtendedTypes plugins:

ExtendedTypes	ElementTypesConfiguration
oep.infra.extendedtypes	oep.infra.types, oep.infra.types.core, oep.types.rulebased, oep.infra.types.ui, oep.infra.types.doc, oep.dev.types
oep.infra.extendedtypes.emf	oep.infra.emf.types, oep.infra.emf.types.ui
oep.infra.extendedtypes.edit	oep.infra.types.edit
oep.infra.extendedtypes.editor	oep.infra.types.editor
oep.uml.tools.extendedtypes	oep.uml.types.core

Diagram Infrastructure Layer

APIs Removed in the infra.gmfdiag.common Bundle

The org.eclipse.papyrus.infra.gmfdiag.common.utils.MDTUtil utility class had some APIs that operated on an annotation for identification of a UML-specific editor:

• EDITOR_VERSION : String
• addDiagramVersion(Diagram, String) : void
• getDiagramVersion(Diagram) : String

These are simply deleted as they are obsolete and were not used within Papyrus.

APIs Moved out of the infra.gmfdiag.css.palette Bundle

As the purpose of this bundle is to provide CSS styling post-actions on creation of new elements via the Palette Service, and whereas the Palette Service is an overtly UML-specific capability , this bundle is renamed as org.eclipse.papyrus.uml.diagram.css.palette.

Accordingly, the identifier of the aspect action provider is changed from org.eclipse.papyrus.infra.gmfdiag.css.style to org.eclipse.papyrus.uml.diagram.css.style. Palette XML definitions will have to be updated to use this new identifier.

APIs Moved out of the uml.diagram.common Bundle

Two XML expressions properties were used in action extensions in the Diagram infrastructure layer:

• org.eclipse.papyrus.uml.diagram.common.isSemanticDeletion
• org.eclipse.papyrus.uml.diagram.common.isReadOnly

These are removed and are superseded by, respectively:

• org.eclipse.papyrus.infra.gmfdiag.common.isSemanticDeletion
• org.eclipse.papyrus.infra.gmfdiag.common.canDelete

Note that the latter above is actually the negation of the property that it supersedes, which was used only as a test for whether an element may be deleted (it would be logically incorrect in the more general case of testing read-only state).

UML Layer

UI Dependencies

APIs Moved out of the uml.service.types Bundle

Several UI-dependency classes are moved from the org.eclipse.papyrus.uml.services.types bundle to a new org.eclipse.papyrus.uml.service.types.ui bundle. These simply require package renames in imports and adding the uml.service.types.ui bundle dependency.

Some packages are moved in their entirety (* replaces the prefix org.eclipse.papyrus):

Old Package	New Package
*.uml.service.types.handlers	*.uml.service.types.ui.handlers
*.uml.service.types.menu	*.uml.service.types.ui.menu

In the org.eclipse.papyrus.uml.service.types.command package, several commands with UI interactions are moved into an internal package org.eclipse.papyrus.uml.service.types.internal.ui.commands (they should not be API because they only service edit advices, which were not and are not API):

• CollaborationRoleCreateCommand
• InformationFlowCreateCommand
• InstanceSpecificationLinkCreateCommand

Also, the type ExtensionHelper is moved from the org.eclipse.papyrus.uml.service.types.helper package to org.eclipse.papyrus.uml.service.types.ui.util (it is a collection of utility methods, not an edit-helper).

VisualID Migration

Meaningful VisualIDs

Up to the Neon release, The visualIDs in the Papyrus GMFGen models were defined as integer numbers. These numbers were used as hints for Views in notatinal models, and as part of the names of the generated APIs. This made interpretting those models and using those APIs hard by users. In the Neon release, the Papyrus visualIDs have changed to meaningful names. The change is implemented by introducing a tree of papyrusgmfgenextension:VisualIDOverride objects as another root in the GMFGen model. The tree parallels the GenView tree in the model, in the sense that there is a VisualIDOverride object that references a corresponding GenView object at the same nesting level. The VisualIDOverride object provides the meaningful visualID string, which will be used by the Papyrus GMFGen templates instead of the integer.

UML Element Types Unification

Up to the Neon release, each Papyrus UML diagram defined its own relevant subset of UML graphical element types (and correponding visualIDs). These subsets usually overlapped when the same notational cases existed in multiple diagrams resulting in duplicate code. In the Neon release, all UML graphical element types have been unified (similar notational elements in multiple diagrams are represented by the same graphical element type) and defined in a common library org.eclipse.papyrus.uml.service.types/model/umldi.elementtypesconfigurations. The library is then reused by all Papyrus UML diagrams (i.e., its element types are referenced by those diagrams' GMFGen models).

• Both changes mentioned above have been applied to all Papyrus UML diagrams and the impacted code in the core plugins have been migrated. However, Papyrus's extra plugins and some third party extensions may have to be migrated as well. This guide provides tips for doing that.

Migration of Code Base

Step 1: Migrate Java Code

Occurrences of the old (integer) style visualIDs (e.g., 3012) for UML need to be replaced by the new (meaningful name) style (e.g., Property_ClassAttributeLabel). These occurrences may exist in hard-code strings, which could be replaced by the new string, but really should be refactored to use instead the VISUAL_ID constant defined by the corresponding editpart (e.g., PropertyForClassEditPart.VISUAL_ID). Similarly, calls to (or overrides of) the old style properties (e.g., UMLElementTyps.Property_3012) or functions (UMLViewProvider.createClass_2008) that have the integers in their names, and which will give compile errors, need to be replaced by the equivalent ones that have meaningful names (e.g., UMLElementTypes.Property_ClassAttributeLabel, UMLViewProvider.createClass_Shape).

• The replacement can be done manually by looking up the visualID and graphical element type mappings in this spreadsheet (File:Mars to Neon VisualID Mappings.zip), which has a page for each UML diagram.

There is no reliable way now to generically tell if a string represents a visualID. Any assumption in the code about the visualIDs (or semantic hints) being exlcusively numbers need to be changed. This is typically found in code that checks, with a string pattern, if visualIDs are numbers, or tries to parse them into numbers. Moreover, there is also no reliable way now to generically tell if a visualID represents a UML visualID (i.e., defined by the UML element type library).

Furthermore, there is no cheap way now to tell if an element type represents a graphical element type (an expensive way is to check if the view service provides a view for it). However, one may check if an element type represents a core UML graphical element type by checking if the identifier is prefixed by org.eclipse.papyrus.umldi. Also, there is no reliable way to tell which diagram uses such an element type, since it may be used by multiple diagrams.

Step 2: Migrate plugin.xml

Occurrences of the UML old style visualIDs or old identifiers for graphical element types in extensions (e.g., viewProviders or editpartProviders) in plugin.xml files need to be replaced by the corresponding ones using the spreadsheet in step 1.

Step 3: Migrate domain models

Occurrences of the UML old style visualIDs (e.g., 3012) or old identifiers for graphical element types (e.g., org.eclipse.papyrus.uml.diagram.clazz.Property_3012), or references to them, in some domain models (e.g., *.assistants and *.elementtypesconfigurations) need to be replaced by the corresponding ones (Property_ClassAttributeLabel, org.eclipse.papyrus.umldi.Property_ClassAttributeLabel) using the spreadsheet in step 1.

Step 4: Migrate end user models

A set of reconcilers for UML diagrams have been added to migrate pre-Neon models. They basically replace the old visualIDs by new ones. These reconcilers are invoked when a diagram editor is opened and perform the replacement in memory. However, for their changes to be persistent, the diagram needs to be saved. Any old models that are kept in the code base, including those in test plugins, can be migrated by opening their diagrams, performing a dummy change to dirty them, and saving them.

Adding New Notational Cases

When contemplating adding new notational cases to one of the UML GMFGen models, one must first check the common UML library of graphical elements org.eclipse.papyrus.uml.service.types/model/umldi.elementtypesconfigurations to see if the cases already exist and can be reused. When truly new cases (that belong to core UML notation) are identified, then they can by handled by adding new element types for them in the common UML library. Suitable meaningful names should be chosen for the visualIDs, which are consistent with the existing ones.

Once a new graphical element type is added to the UML common library, then it can be used in a GMFGen by referring to its identifier in a new GenView object. The GenView object will still need to get assigned a unique integer visualID. However, one must also provide the meaning name visualID, by adding a new VisualIDOverride object in the appropriate nesting level in the VisualIDOverride tree (at the root). That object needs to reference the GenView and provide the string visualID.