Papyrus/Migration Guide/Neon
Contents
- 1 Papyrus 2.0 API Migration Guide
- 2 Infra Layer
- 2.1 UI Dependencies
- 2.1.1 APIs Moved out of the infra.tools Bundle
- 2.1.2 APIs Moved out of the infra.core Bundle
- 2.1.3 Bundle Re-exports Removed from the infra.core Bundle
- 2.1.4 APIs Moved out of the infra.emf Bundle
- 2.1.5 APIs Moved out of the infra.core.sasheditor.di Bundle
- 2.1.6 API Moved out of the infra.constraints Bundle
- 2.1.7 APIs Moved out of the infra.services.edit Bundle
- 2.1.8 APIs Moved out of the infra.onefile Bundle
- 2.2 GEF 3 Dependencies
- 2.3 UML Dependencies
- 2.4 Diagram Layer Dependencies
- 2.5 Views Dependencies
- 2.6 ElementTypesConfiguration Framework
- 2.7 ExtendedTypes Framework
- 2.1 UI Dependencies
- 3 Diagram Infrastructure Layer
- 4 UML Layer
- 5 VisualID Migration
- 6 Footnotes
Papyrus 2.0 API Migration Guide
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:
- 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
- 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
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[1] | *.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 usefulExecutor
implementations for asynchronous execution of code. ThegetUIExecutorService
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 PlatformExecutorService
interface provides methods for synchronous execution ofRunnable
s andCallable
s on the UI thread. The UI executor service provided by theCoreExecutors
class implements that protocol usingDisplay.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 theDefaultConstraintEngine
class) no longer requires anISelection
-
Constraint::match(Collection<?> selection)
(and hence the same inAbstractConstraint
andCompoundConstraint
) no longer requires anIStructuredSelection
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
null
s 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()
ortoList()
or similar (which includes theIStructuredSelection
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 thePapyrusLabelProvider
class in the UI bundle - several API methods are moved from the
OneFileUtils
class into a new classorg.eclipse.papyrus.infra.onefile.ui.utils.OneFileUIUtils
:getActivePage()
getEditorID(IEditorInput)
isOpenInEditor(Object)
openInEditor(Object, boolean)
infra.ui
bundle (formerly by theinfra.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 anIModel
that provides access to its semantic content in theModelSet
via a new<modelBinding>
element in theorg.eclipse.papyrus.infra.core.languages
extension point. TheUmlModel
is thus associated with the UML language. TheILanguage
interface has a newgetModel(ModelSet) : IModel
API to get the associated language, if there is one. Similarly, theILanguageService
has a static convenience methodgetLanguageModels(ModelSet)
for obtaining all of the semantic models in a model set that have content - the
IEMFModel
interface extendingIModel
has a newgetRootElements() : 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. TheUmlModel
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 ITreeContentProvider
s for presentation of model content can now be obtained via the semantic IModel
s 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
, andIAdaptableContentProvider
. The provider factories are self-composable; a composite factory yields composite content providers - the
IModel
interface now extendsIAdaptable
, to provide for adapters ofISemanticContentProviderFactory
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 theSemanticUMLContentProvider
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 operationscanPersist(EObject) : boolean
andpersist(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 operationgetModelToPersist(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 renamedorg.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 neworg.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 interfaceorg.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 theorg.eclipse.papyrus.views.properties
bundle, but the activate manager instance is to be obtained via a neworg.eclipse.papyrus.infra.properties.ui.runtime.PropertiesRuntime
class (thegetConfigurationManager
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
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
UML Dependencies
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 [2], 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.
Footnotes
- ↑ which should not have been API in any case
- ↑ The definition and APIs of the Palette Service are dependent on concepts from UML Profiles in even the most abstract interfaces. Factoring out these UML-isms was ruled out of scope for the Neon release, as simply not being a priority, considering that the entire Palette Service is planned to be superseded.