Sunday, April 27, 2014

Contributing to the Papyrus Editor Palette

Augmenting the Papyrus Palette

Goal

This entry is the first in a series of articles that details the customizations to the Eclipse Papyrus platform for the UML Testing Tool. These customizations, though specific to the needs of the UML Testing Tool community, can be generalized and used for other products with similar requirements.

The UML Testing Tool is a graphical workbench for the design, visualization, specification, analysis, construction, and documentation of the artifacts involved in testing. The language for modeling these artifacts is based on a UML Testing Profile. This profile defines a set of UML stereotypes that extend a subset of UML elements. There are Similar tools based on other UML profile specifications, such as the NIEM UML Profile.

Papyrus is an environment within Eclipse that enables users to configure graphical editors for UML-based DSLs.

The goal of this first entry is to describe how to register a UML profile with Papyrus and to augment the Papyrus editor palette with stereotyped elements defined in this profile.

tl;dr

The source code for the set of Eclipse plug-ins that contains the UML Testing Profile, its registrations with the Eclipse UML and Papyrus extensions and the test cases described in this post is located here. Feel free to use, explore, contribute to or fork this code for your own needs. A snapshot of the code specific to these examples at the time of writing is here.

Registering the UML Profile

Let's assume that we already have all the boilerplate configuration for an Eclipse plug-in, test fragment, feature and p2-repository in place. For this plug-in, we can use the tycho_new_plugin_project archetype, initially described here.

We will start with an acceptance test to verify that we have correctly registered the UML Testing Profile as a UML dynamic package.

PackageRegistrationTest.java
PackageRegistrationTest.java
package timezra.uml.testing.resources;

import static org.eclipse.uml2.uml.UMLPlugin.getEPackageNsURIToProfileLocationMap;
import static org.eclipse.uml2.uml.resources.util.UMLResourcesUtil.init;
import static org.hamcrest.CoreMatchers.instanceOf;
import static org.junit.Assert.assertThat;

import org.eclipse.emf.ecore.EObject;
import org.eclipse.emf.ecore.resource.impl.ResourceSetImpl;
import org.eclipse.uml2.uml.Profile;
import org.junit.Test;

public class PackageRegistrationTest {
    @Test
    
public void should_register_the_uml_testing_package() {
        
final EObject utp = init(new ResourceSetImpl()).getEObject(
                getEPackageNsURIToProfileLocationMap().get(
"http://www.omg.org/spec/UTP/20120801/utp_1.2"), true);

        assertThat(utp, instanceOf(Profile.
class));
    }
}

In order to satisfy this test, we must include the utp_1.2.xmi and utptypes_1.2.xmi with our plug-in. We will modify the utp_1.2.xmi by adding the xmlns declaration xmlns:cmof="http://www.omg.org/spec/MOF/20110701/cmof.xmi" to the root header. We also need to define the profile through the Eclipse UML Editor.

With the UTP and its supporting type descriptions packaged into a plug-in, we can now register an extension for the UML dynamic package for the profile we just defined through the Eclipse UML Editor.

plugin.xml
plugin.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
    <extension point="org.eclipse.emf.ecore.uri_mapping">
        <mapping source="pathmap://UTP/"
            target="platform:/plugin/timezra.uml.testing.resources/src/main/resources/uml/">
        </mapping>
    </extension>
    <extension point="org.eclipse.emf.ecore.uri_mapping">
        <mapping source="http://www.omg.org/spec/UTP/20120801/utp_1.2.xmi"
            target="pathmap://UTP/utp_1.2.xmi">
        </mapping>
        <mapping source="http://www.omg.org/spec/UTP/20120801/utptypes_1.2.xmi"
            target="pathmap://UTP/utptypes_1.2.xmi">
        </mapping>
    </extension>
    <extension point="org.eclipse.uml2.uml.dynamic_package">
        <profile location="pathmap://UTP/utp_1.2.xmi#_iCl4wOVMEeG84fBOY39c0g"
            uri="http://www.omg.org/spec/UTP/20120801/utp_1.2">
        </profile>
    </extension>
</plugin>

Now, if we install our feature into Eclipse and create a new UML model, the UTP will be available for profile application through the UML Editor. UTP Registered With UML

Profile Registration With Papyrus

In order to register this profile with Papyrus, we can use similar steps: create a test to verify when the behavior we are trying to expose works and expose the profile location through an extension.

ProfileRegistrationTest.java
ProfileRegistrationTest.java
package timezra.uml.testing.papyrus.palettes;

import static org.eclipse.papyrus.uml.extensionpoints.profile.RegisteredProfile.getRegisteredProfile;
import static org.hamcrest.CoreMatchers.notNullValue;
import static org.junit.Assert.assertThat;

import org.junit.Test;

public class ProfileRegistrationTest {
    @Test
    
public void should_register_the_uml_testing_profile() {
        assertThat(getRegisteredProfile(
"UTP"), notNullValue());
    }
}

plugin.xml
plugin.xml
....
   <extension
         point="org.eclipse.papyrus.uml.extensionpoints.UMLProfile">
      <profile
            description="UML Testing Profile"
            iconpath="icons/full/obj16/utp.png"
            name="UTP"
            path="http://www.omg.org/spec/UTP/20120801/utp_1.2.xmi#_iCl4wOVMEeG84fBOY39c0g"
            provider="omg.org">
      </profile>
   </extension>
   <extension
         point="org.eclipse.papyrus.uml.extensionpoints.UMLLibrary">
      <library
            description="UML Testing Profile Types"
            iconpath="icons/full/obj16/utptypes.png"
            name="UTP Types"
            path="http://www.omg.org/spec/UTP/20120801/utptypes_1.2.xmi"
            provider="omg.org">
      </library>
   </extension>
....

The UTP is now available in the Papyrus repository, and it can be applied from the Profile tab of the Properties View. UTP Registered With Papyrus

Palette Customization

Once we are able to apply the UTP to a Model, we can specify tests with UML elements extended by this profile. Suppose we begin by creating a TestContext from the Papyrus palette.

ClassDiagramPaletteTest.java
ClassDiagramPaletteTest.java
package timezra.uml.testing.papyrus.palettes;

import static org.eclipse.papyrus.uml.diagram.common.util.URIUtil.getFile;
import static org.eclipse.papyrus.uml.tools.model.UmlUtils.getUmlResource;
import static org.hamcrest.CoreMatchers.instanceOf;
import static org.hamcrest.CoreMatchers.notNullValue;
import static org.junit.Assert.assertThat;

import org.eclipse.gef.EditDomain;
import org.eclipse.gef.EditPartViewer;
import org.eclipse.gef.Tool;
import org.eclipse.gef.palette.PaletteContainer;
import org.eclipse.gef.palette.PaletteEntry;
import org.eclipse.gef.palette.ToolEntry;
import org.eclipse.gef.ui.palette.PaletteViewer;
import org.eclipse.gmf.runtime.diagram.ui.editparts.IGraphicalEditPart;
import org.eclipse.gmf.runtime.diagram.ui.parts.IDiagramWorkbenchPart;
import org.eclipse.papyrus.editor.PapyrusMultiDiagramEditor;
import org.eclipse.papyrus.infra.core.editor.IMultiDiagramEditor;
import org.eclipse.papyrus.uml.diagram.clazz.CreateClassDiagramCommand;
import org.eclipse.swt.events.MouseEvent;
import org.eclipse.swt.widgets.Event;
import org.eclipse.uml2.uml.Class;
import org.eclipse.uml2.uml.Element;
import org.eclipse.uml2.uml.Package;
import org.junit.Rule;
import org.junit.Test;
import org.junit.rules.RuleChain;
import org.junit.rules.TestRule;

import timezra.uml.testing.papyrus.palettes.rules.AppliesTheUTP;
import timezra.uml.testing.papyrus.palettes.rules.CreatesAPapyrusModel;
import timezra.uml.testing.papyrus.palettes.rules.CreatesAProject;
import timezra.uml.testing.papyrus.palettes.rules.CreatesAServicesRegistry;
import timezra.uml.testing.papyrus.palettes.rules.OpensEditor;
import timezra.uml.testing.papyrus.palettes.rules.SavesAModel;

public class ClassDiagramPaletteTest {

    
private CreatesAServicesRegistry theServicesRegistry;
    
private CreatesAProject theProject;
    
private CreatesAPapyrusModel thePapyrusModel;
    
private OpensEditor<IMultiDiagramEditor> theEditor;

    @Rule
    
public final TestRule ruleChain = RuleChain
            .outerRule(theServicesRegistry = 
new CreatesAServicesRegistry())
            .around(theProject = 
new CreatesAProject(getClass().getSimpleName()))
            .around(thePapyrusModel = 
new CreatesAPapyrusModel(theServicesRegistry, theProject, "model.di",
                    
new CreateClassDiagramCommand()))
            .around(
new AppliesTheUTP(thePapyrusModel))
            .around(
new SavesAModel(thePapyrusModel))
            .around(theEditor = 
new OpensEditor<IMultiDiagramEditor>(
                    () -> getFile(getUmlResource(thePapyrusModel.get()).getURI()), PapyrusMultiDiagramEditor.EDITOR_ID));

    @Test
    
public void can_create_a_test_context() {
        
final IGraphicalEditPart theActivePart = ((IDiagramWorkbenchPart) theEditor.get().getActiveEditor())
                .getDiagramEditPart();
        
final EditPartViewer theEditPartViewer = theActivePart.getViewer();
        doubleClick(findThePaletteTool(theEditPartViewer, 
"UTP/Test Context (Class)"), theEditPartViewer);

        
final Element theTestContext = ((Package) theActivePart.resolveSemanticElement())
                .getPackagedElement(
"TestContext1");

        assertThat(theTestContext, instanceOf(Class.
class));
        assertThat(theTestContext.getAppliedStereotype(
"utp::TestContext"), notNullValue());
    }

    
private Tool findThePaletteTool(final EditPartViewer theEditPartViewer, final String toolPath) {
        
final EditDomain theDomain = theEditPartViewer.getEditDomain();
        
final PaletteViewer thePaletteViewer = theDomain.getPaletteViewer();
        
final ToolEntry toolEntry = findByLabel(thePaletteViewer.getPaletteRoot(), toolPath);
        thePaletteViewer.setActiveTool(toolEntry);

        
final Tool theTool = toolEntry.createTool();
        theTool.setViewer(theEditPartViewer);
        theTool.setEditDomain(theDomain);

        
return theTool;
    }

    @SuppressWarnings(
"unchecked")
    
private <T extends PaletteEntry> T findByLabel(final PaletteContainer thePaletteContainer, final String theLabel) {
        
final String[] path = theLabel.split("/");
        PaletteEntry nextEntry = thePaletteContainer;
        NEXT_SEGMENT: 
for (final String segment : path) {
            
if (nextEntry instanceof PaletteContainer) {
                
for (final Object o : ((PaletteContainer) nextEntry).getChildren()) {
                    
final PaletteEntry paletteEntry = (PaletteEntry) o;
                    
if (segment.equals(paletteEntry.getLabel())) {
                        nextEntry = paletteEntry;
                        
continue NEXT_SEGMENT;
                    }
                }
                
return null;
            } 
else {
                
return null;
            }
        }
        
return (T) nextEntry;
    }

    
private void doubleClick(final Tool theTool, final EditPartViewer theEditPartViewer) {
        
final Event theEvent = new Event();
        theEvent.widget = theEditPartViewer.getControl();
        
final MouseEvent mouseEvent = new MouseEvent(theEvent);
        mouseEvent.button = 1;
        theTool.mouseDoubleClick(mouseEvent, theEditPartViewer);
    }
}

Now we will describe a palette entry for the Class Diagram Editor that is in a UTP drawer and that will apply the utp::TestContext stereotype to a UML class.

UTP.clazz.palette.xml
UTP.clazz.palette.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<paletteDefinition>
    <content>
        <drawer iconpath="/icons/drawer.gif" id="UTP_Drawer" name="UTP">
            <aspectTool description="Create a Test Context (Class)"
                iconpath="platform:/plugin/timezra.uml.testing.papyrus.palettes/icons/full/obj16/test_context_class.png"
                id="clazz.tool.class_UTP_TEST_CONTEXT" name="Test Context (Class)" refToolId="clazz.tool.class">
                <postAction id="org.eclipse.papyrus.applystereotypeactionprovider">
                    <stereotypesToApply>
                        <stereotype stereotypeName="utp::TestContext" />
                    </stereotypesToApply>
                </postAction>
            </aspectTool>
        </drawer>
    </content>
</paletteDefinition>

Finally, we will register this palette configuration with a Papyrus extension.

plugin.xml
Copy of plugin.xml
....
<extension point="org.eclipse.papyrus.uml.diagram.common.paletteDefinition">
    <paletteDefinition ID="timezra.uml.testing.papyrus.palettes.UTP_clazz"
        class="org.eclipse.papyrus.uml.diagram.common.service.PluginPaletteProvider"
        icon="icons/full/obj16/utp_palette.png" name="UTP Class Diagram Elements"
        path="palettes/UTP.clazz.palette.xml">
        <Priority name="Medium">
        </Priority>
        <editor id="org.eclipse.papyrus.uml.diagram.clazz">
        </editor>
    </paletteDefinition>
</extension>
....

Once we register the palette definition with Papyrus, the test will pass and the TestContext contribution will be visible for UML Models that have the UML Testing Profile applied. TestContext palette contribution

Conclusion

In this article, we expose the following behaviors from the Eclipse workbench: the ability to apply the UML Testing Profile within the UML and Papyrus Editors and the ability to create UML elements extended by UML stereotypes defined in the UTP directly from a Papyrus editor palette. We describe these behaviors through tests and define them with plug-in extensions and external configuration. The code for these examples is here.