Difference between revisions of "Papyrus/Neon.1 Work Description/Improvements/Control-Mode"

Latest revision as of 13:42, 26 July 2016

Overview

One of the major use cases for the Papyrus-RT project, indeed the first use case that is encountered by a large segment of its user base, is import of UML-RT models from other systems. The primary such system currently supported is RSA-RTE. That tool encourages scaling models for source control by distributing the storage of model content over sub-model resources called 'fragments'. These fragments are not independently editable, but are editable only in the context of the model resources that (recursively) store the trees of objects containing their contents.

Up to the Papyrus Neon release, models from RSA (and therefore RSA-RTE) that were fragmented in this way are imported in a manner that retains this sub-model resource structure, but with a twist: in Papyrus, sub-model units are always independently openable and do not open in the context of their containing namespaces. For this reason, the "control" action that creates a new sub-model unit would create redundant profile applications on the package that is the root object in the sub-unit for all of the profiles applied to any nesting packages (this could not be done for sub-units that are not packages, as the user is warned by a dialog in the UI). However, because in RSA its 'fragments' are not independently openable in this way, they do not repeat profile applications and accordingly the sub-model units created in the imported Papyrus model do not repeat them, either.

To provide a more complete RSA-RTE import experience in the Papyrus-RT 0.8 release that is based on Papyrus Neon.1, improvements are planned in the design of the 'Control Mode' (model sub-unit resources) capability of Papyrus:

• Bug 496299 — Controlled units as integral fragments
• Bug 497865 — UI for dependent controlled units

The first of these enhances the existing control-mode framework with support for sub-units that behave more like RSA's fragments, being not independently editable. Initially this capability is used only by the RSA model importer to import fragment resources. The second enhancement provides additional UI to support this new style of controlled unit in Papyrus- and Papyrus-RT-centric use cases.

Controlled Units as Integral Fragments

This enhancement introduces a new variant of the controlled unit dubbed a 'shard' (as being a fragment of broken ceramic or glass that is a constituent of the whole on not generally handled). Thus Papyrus supports two modes of controlled unit:

• sub-model units: the classic form, through the Neon release, being usually a package that is independently openable and editable because it is self-sufficient in profile applications
• shards: the new form, that when the user opens it in an editor will instead open it in the context of the whole model (or the top-most parent unit that is a sub-model unit)

Use Cases

UC1 Import Fragmented Model from RSA

1. User selects a *.emx resource in the workspace, activates the context menu, and selects 'Import RSA Model/Profile'.
2. The system opens the RSA import wizard.
3. The user completes the wizard.
4. The system imports the *.emx resource along with all of its *.efx fragments. These latter are imported as 'shards'.
5. The user double-clicks on the top-level unit (the one that was imported from the EMX file) to open the model.
6. The system opens the top-level unit in the Papyrus Editor.

UC2 Open an Imported Sub-unit Resource

1. The user double-clicks on a *.di resource that was imported from an *.efx in the RSA model.
2. The system opens the top-level unit containing the root package namespace of the contents of the selected resource in the Papyrus Editor.

UC2.1 Variant: Open an Imported Sub-unit Resource (Model Already Open)

1. The user opens an imported model as in UC1.
2. The user finds some sub-unit resource of this model in the Project Explorer and double-clicks on it to open it.
3. The user activates the editor previously opened, which is the root context of the sub-unit resource.

Design

Model Cross-Reference Index

The topology of sub-model units is implied by cross-resource containment in EMF: that is, containment references that have proxies for lazily resolved objects from other resources. As one of the benefits of the classic Papyrus sub-model unit is that it is independently openable and editable, it does not add a reference to its parent unit in an annotation as is done in RSA's fragments, because that would trigger loading of the parent unit chain by proxy resolution. Accordingly, in order to discover the connected graph of sub-unit resources at run-time, some agent is required that can provide independent off-line knowledge of it. This is naturally implemented on the WorkspaceModelIndex framework.

A new ICrossReferenceIndex API in the org.eclipse.papyrus.infra.emf bundle provides for queries (asynchronous and synchronous, as usual) about:

• incoming and outgoing cross-references of and given resource (since resources have to be scanned for all references to find the containment proxies, it makes sense to keep this non-containment information, too)
• child sub-units and parent sub-units (the relationship is multiple in both directions). These are the containment counterparts of the incoming and outgoing cross-references
• root units
• whether a resource is a 'shard' style of sub-model unit or not

Unlike sub-model units, shards additionally have annotations that reference the containing object in the parent resource, not unlike fragments in RSA. This is not a problem because they are not intended to be loaded independently of their parent units, anyways, but also has the benefit of enabling a tracing of the parent unit chain in cases where the full off-line index is not available:

• when the Eclipse Job Manager is suspended (e.g., when starting the workbench)
• in a non-Eclipse environment, such as command-line applications (e.g., headless Papyrus-RT code generation)

Shard Resource Loading

The point of shard resources is that they cannot be loaded without the chain of parent resources storing their containing objects, so that in the case of UML resources, packages find all of the profile applications in their nesting packages to ensure that stereotype applications are properly resolved.

This loading of the parent unit chain, from the root unit(s) down, is ensured in two different ways, depending on the circumstances:

• when opening a resource in the Papyrus Editor, the editor will refer to the index to find the root units to open, instead, if the requested resource is actually a 'shard'. Similarly, the PapyrusMatchingStrategy matches editor-inputs for shards with editor-inputs for their root units
• when resolving proxies, the EMF ResourceSet will demand-load the referenced resource. If this happens to be a shard, it needs to load it from the top unit down (this is the essence of bug 458837 in which stereotype applications were lost by demand-loaded packages not knowing their profile applications). This is accomplished by a ShardResourceLocator installed on the resource set. This API supports non-Eclipse applications via the on-demand cross-reference index discussed above.

Other Index Enhancements

Because now another index is introduced (Papyrus has had an index of external profile applications since the Mars release), it is prudent to do some refactoring to ensure as much as possible that performance doesn't suffer from the added burden.

Consolidation of Indexing Control

Rather than have every index create background jobs for itself that react to resource changes and scan projects in the workspace, now a new IndexManager provides a single point of control for these processes:

• one workspace resource-change listener to trigger re-indexing of projects and files recognized by each individual index
• one pool of jobs with one indexing job per project, which invokes all indexers to process each file in turn

This improves throughput of the indexing process by eliminating multiple passes over resource deltas and resource trees in the workspace projects, but it does mean that asynchronous queries on any index will only be ready when all indices complete their processing of any deltas.

Persistence of Index Data

Because even the simplest use case of opening a model now depends on this new workspace-wide index, it is important to initialize that index as efficiently as possible. To that end, the WorkspaceModelIndex framework now supports an extension of the IndexHandler protocol which is a PersistentIndexHandler. This protocol

• guarantees that the index data it provides for a file is Serializable, so that it can be persisted when the workspace shuts down
• provides API for loading index data saved when the workspace shut down last

The new CrossReferenceIndex supports persistence and the older DecoratorModelIndex is retrofitted for persistence, also.

Index Start-up

As a consequence of both of the enhancements described above, consolidation of control and initialization from a persistent store, it is necessary for the IndexManager to discover all available index instances when it starts up. This is accomplished by a new extension point org.eclipse.papyrus.infra.emf.index on which IWorkspaceModelIndexProviders are registered that supply unique concrete WorkspaceModelIndex instances. It is not required but probably advisable that all such instances be long-lived singletons.

Manipulating Sub-unit Resources

As far as the manipulation of sub-units is concerned, they are still created in the same way as in the Neon release. The difference is that, after a model element is stored in its sub-unit resource, it needs to be tagged as a 'shard'. This is accomplished by the ShardResourceHelper API. A helper is initialized with the model element that is the root of the shard sub-tree. It can add or remove the shard annotation directly or by providing Commands for execution on the stack and can query the current shard-ness of the sub-unit. As long as the helper is in use, it maintains Adapters to track any changes to the object's containment and/or shard annotation. For this reason, it must be closed when no longer needed, to prevent memory leaks.

User Interface for New Control-Mode Features

This enhancement introduces UI for manipulation of the 'shard' style of sub-unit resource, including:

• option to disallow independent opening and editing of the sub-unit
• action to toggle between independent sub-model unit and shard
• label decorator to mark sub-model units and shards in the Project Explorer

Use Cases

UC3 Create a Sub-model Unit

1. User selects a package in the Model Explorer, activates the context menu, and selects 'Create Submodel'.
2. The system opens the 'Submodel Resource' dialog.
3. The user enters a resource URI and ensures that the 'Create an independent sub-model resource' check-box is selected, then presses OK.
4. The system creates the sub-model resource in the editor's resource set and shows the controlled unit decoration on the package in the Model Explorer.
5. The user saves the editor.
6. The Project Explorer shows the new sub-unit resource with a filled blue bent-corner paper decoration to denote that it is a sub-model unit.

Papyrus Sub-units

UC4 Create a Shard Unit

1. User selects a package in the Model Explorer, activates the context menu, and selects 'Create Submodel'.
2. The system opens the 'Submodel Resource' dialog.
3. The user enters a resource URI and ensures that the 'Create an independent sub-model resource' check-box is not selected, then presses OK.
4. The system creates the shard resource in the editor's resource set and shows the controlled unit decoration on the package in the Model Explorer.
5. The user saves the editor.
6. The Project Explorer shows the new shard resource with a hollow blue bent-corner paper decoration to denote that it is a shard unit.

UC4.1 Variant: Control a UML Class

1. User selects a class in the Model Explorer, activates the context menu, and selects 'Create Submodel'.
2. The system opens the 'Submodel Resource' dialog. The 'Create an independent sub-model resource' check-box is disabled, because classes cannot be edited independently (they cannot have profile applications).
3. The user enters a resource URI then presses OK.
4. The system creates the shard resource in the editor's resource set and shows the controlled unit decoration on the package in the Model Explorer.
5. The user saves the editor.
6. The Project Explorer shows the new shard resource with a hollow blue bent-corner paper decoration to denote that it is a shard unit.

UC5 Convert a Sub-model Unit to a Shard

1. User creates a sub-model unit for a package as in UC3 and saves the editor.
2. The user selects the package, activates the context menu, and toggles the 'Independent Submodel' menu item, which is currently checked.
3. The system adds the shard annotation and removes redundant profile applications from the package.
4. The user saves the editor.
5. The Project Explorer updates the sub-unit resource's label to show the hollow blue bent-corner paper decoration denoting that it is a shard unit. paper decoration to denote that it is a shard unit.

UC6 Convert a Shard to a Sub-model Unit

1. User creates a shard unit for a package as in UC4 and saves the editor.
2. The user selects the package, activates the context menu, and toggles the 'Independent Submodel' menu item, which is currently checked.
3. The system removes the shard annotation and adds redundant profile applications to the package so that it may be opened independently.
4. The user saves the editor.
5. The Project Explorer updates the sub-unit resource's label to show the filled blue bent-corner paper decoration denoting that it is a sub-model unit.

UC6.1 Variant: Convert a Class Shard to a Sub-model Unit

1. User creates a shard unit for a class as in UC4.1 and saves the editor.
2. The user selects the package and activates the context menu.
3. The 'Independent Submodel' menu item is unchecked and disabled so that it may not be toggled.

Design

Control-Mode Participants

A new protocol specializing the IControlModeParticipant is introduced that participants may optionally implement to influence the UI workflows. The IControlCommandApprover interface specifies two operations:

• boolean canCreateSubModel(EObject): queries whether a model element that is to be made into a sub-unit can support independent opening and editing. The UML participant implements this to deny sub-model units for non-packages: they can only be created as shards. Thus, the warning dialog about limited support for non-package sub-units is no longer shown
• Diagnostic approveRequest(ControlModeRequest): gives participants an opportunity to veto a control or uncontrol request, with a message that is displayed to the user

So, the former of these APIs is used by the ControlModeManager to determine the enablement of the check-box option for sub-models in the 'control resource' dialog and in the context menu (although, of course, in the latter case the action is enabled if a non-package element is controlled as a sub-model in order that it may be converted to a shard).

The latter API is used by the UI control/uncontrol command handlers to validate a request before attempting to survey the participants for commands and execute them.

Compatibility

The 'shard' structure is compatible with the Neon and Mars releases. It adds only an annotation that those versions of the software simply ignore. The back-reference to the parent unit will usually cause the parent units (and recursively up to the roots) to be loaded, which may help to emulate the Neon.1 and later behaviour. However, because a Neon.1 shard will not have redundant profile applications (a model imported from RSA in Mars or Neon would not have them, either) then there may be problems in handling of stereotype applications and potential data loss. If these resources must be edited with Mars or Neon versions of Papyrus, then it is recommended either always to open them at the root unit explicitly or even to opt for the classic sub-model unit structure (except for non-packages, which effectively always were defective shards anyways).