UML 2 profiles are really powerful and useful things. Its very easy to create them and if you wrap them as plugins really easy to share them too. While there is a lot of information from IBM on how to create your own custom profiles, there is not so much on how to wrap them as plugins. Here's how to do just that using RSA 7.0.5...
We'll start by assuming that you already have a profile created in a seperate project and that you've released it. If you're unclear on how to do this, check out the tutorial from IBM - Comparing and Merging UML models in IBM Rational Software Architect, Part 6: Parallel Model Development with Custom Profiles. Note: Whilst this does also cover creating a plugin from the profile, it is aimed at RSA 6.0. Things have changed a fair bit since then (deprecated APIs, different wizards etc.)
We'll take this custom profile and embed it in an Eclipse plug-in with an two extension points: "com.ibm.xtools.uml.msl.UMLProfiles" and "org.eclipse.gmf.runtime.emf.core.Pathmaps". There is ample discussion of what these are responsible for in the IBM article previously mentioned. Under this extension you specify a directory which contains the profile, any images to be used for icons and shape images and a template definition file that pulls the whole thing together and provides some descriptive text.
1. Create a plug-in project
The first step is to create a new plug-in project (File-> New Project->Plug-in Development->Plug-in Project).
Give your project a name. It’s typical to keep the project name and plug-in identifier the same; you should also be aware that the plug-in identifier will need to be unique, so use a reverse domain name style of notation. I’ll use com.musicoftime.modelling.profiles.blog. The other thing you should do is untick the “Create a Java Project” check box. Now click Next.
On this second page, change the plug-in version from 1.0.0 to 1.0.0.qualifier. I’ll explain later why; for now just trust me, it’s plug-in development good practice to suffix the version number with .qualifier. Click Finish (you don’t need to change any other options so don’t click Next). You’ll be prompted on whether you want to change perspective to the “Plug-in Development perspective“. It’s upto you whether you do or not; if you’re unsure, select No.
2. Adding the extensions
Once the plug-in project has been created, the tool will automatically open the plug-in manifest editor, which allows us to make changes to the plug-ins that we’re defining. If you accidently close this, don’t panic, just right-click your plug-in project and select PDE Tools->Open Manifest. At the bottom of the editor are a number of tabs called Overview, Dependencies, Runtime, etc. The one we want is called “Extensions” so click that now.
From here, you need to click the Add button to allow us to add the two extensions we need. Untick the check box “Show only extensions from the required plug-ins” and in the “Extension Point filter” type “*umlprofile*“. Select the extension called “com.ibm.xtools.uml.msl.UMLProfiles” and click Finish.
You will get a prompt asking if you want to add some dependencies, you must click “Yes”.
You'll now be back in the manifest editor. To add the other extension, do the same again, but this time search using “*pathmaps*“. This time there will be two results. Select the extension called “org.eclipse.gmf.runtime.emf.core.Pathmaps” (the latter is deprecated) and click Finish.
Again you will get a prompt asking if you want to add some dependencies, you must click “Yes”.
You’ll now be back at the manifest editor again. Right click com.ibm.xtools.uml.msl.UMLProfile in the “All extensions” list, and select New->UML Profile. On the right the “Extension Element Details” will show the details you need to provide. Set the name value to be something like "Music Of Time UML Profile", set the path to "profiles/MusicOfTimeUMLProfile.epx", and set "required" to "false" and "visible" to "true". Select File->Save All.
You’ll now be back at the manifest editor again. To add the extension element details to the PathMap extension right click org.ecplise.gmf.runtime.emf.core.Pathmaps in the “All extensions” list, and select New->Pathmap. On the right the “Extension Element Details” will show the details you need to provide. Set the name value to be something like "com.musicoftime.modelling.profiles.blog.pathmap", and set the path to "profiles". Select File->Save All.
3. Create the resources
Right click the plug-in project, select New->folder. The folder name must be the same as the name we put into the template extension; so for us that’s “profiles“.
In this directory we need to put three things; a profile file (i.e. a .epx file) and any resources such as icons and shape images which it might need.
3a. Add the Profile
Next is the profile; as discussed, we already have one from the IBM article which we can copy. For this, I suggest opening a new view within the tool since the project explorer view tries to be a little clever by hiding the underlying model files. Although this is useful most of the time, it’ll be a pain for us right now. Therefore we’re going to use the Navigator view; from the top menu, select Window->Show View->Other… In the “type filter text” text box at the top of the dialog type “Nav” and you should have a single entry left, which is the Navigator view (in the General category). Select Navigator and click Ok.
In the navigator view, you can see the raw file system resources. Select your profile file MusicOfTimeUMLProfile.epx. To copy, just right click the model file and select “Copy” (or press Ctrl-C) and then right click the templates directory and select “Paste” (or select it and press Ctrl-V). (N.B. You can also copy it by dragging the model file onto the templates directory whilst holding down the Ctrl key - without the control key you’ll move it rather than copy it).
3b. Add the profile image resources (GIFs and SVGs)
If you have any profile image resources add them to the plugins directory too. Make sure that if you organised them in your Profile project using folders, you use the same structure here.
4. Test it works
To test that this works, we can either export the plug-in and test it in our installation (jump to the next section for that) or you can test it by ‘self-hosting‘. Although this is done from within the RSA tool, it does involve starting up a new running copy of RSA which means you’ll not be able to do this very easily if you’re using a memory contrained computer.
To do this we need to open the PDE’s perspective (Window->Open perspective->Plug-in Development). Now select Run->Run… then right-click “Eclipse Application” and select “New“. Now we select “Run” and wait for the new instance of RSA to open.
(Depending on the capabilities of your machine, it may take a couple of minutes to launch the new RSA instance.)
When it (eventually) starts, open the modeling perspective and create a new UML Model. Once you've done that, add your profile to the model by selecting it in the explorer and in the properties view selecting the "profiles" tab. Click the "Add Profile..." button and you should see your profile in the "Deployed Profile" dropdown. Click "OK" once you have it selected. You have applied your new profile to your model. Test it is working by creating an element in your model and applying a stereotype to it - the stereotypes from your profile should be in the list of options.
5. Export the plug-in
To be able to use the plug-in properly we need to export it so that we can deploy it within the tool. First we need to configure the plug-in’s build settings to indicate what needs to be exported. You need to be in the plug-in’s manifest editor (if you closed it, right-click your plug-in project and select PDE Tools->Open Manifest).
Select the “Build” tab at the bottom. In the binary build tree, click the “profiles” folder (you’ll notice that the resources within the templates folder are automatically selected.
Make sure everything is saved (File->Save All).
To export the plug-in you need to export as a deployable plug-in. To do this, from the menu select File->Export->Plug-in Development->Deployable plug-ins and fragments.
In the export dialog, make sure that the plug-in is selected. Enter a directory where you want the export to put the deployable plug-in and click Finish
After exporting, you’ll see that a “plugins” directory has been created under the directory you specified. Within this is a single jar file that contains your deployable plug-in.
Note that the name of the Jar file is the plug-in identifier followed by the plug-in version; although the ‘qualifier‘ part of the version has been replaced with a date/timestamp. This means that exporting the plug-in twice (mode than a minute apart) will create two distinct plug-in versions. This is a good thing and I’d strongly recommend allowing this. If this is something you really don’t want then either select a specific qualifer value on export (in the Options tab of the Export dialog) or remove the ‘.qualifier‘ suffix from the plug-in version.
To deploy this, copy the Jar file to C:Program Files\IBM\SDP70\plugins) and restart RSA.
6. Next steps
To make deployment easier within a team, you should strongly consider create an update site and hosting it on a development or departmental server - see Eclipse - How To Keep Up To Date.
View Andrew Law's profile