Create your MagicDraw user library

First of all you need to create a user library (Window>Preferences>Java>Build Path>User Libraries) in Eclipse containing every *.jar from the “<MagicDraw_Install_Dir>/lib” and its subfolders.

Create your debug project

Create a new Java Project, and then you need to reference your plugin project in the build path of your debug project : (Right click on the project>Configure build path)

Here I take the Eclipse project given in this post.

Then you need to create a main class which will init your plugin and launch MagicDraw :

package fr.free.mdwhatever.magicdrawDebug;

import com.nomagic.magicdraw.core.Application;
import com.nomagic.runtime.ApplicationExitedException;

import fr.free.mdwhatever.simplePlugin.SimplePlugin;
/**
 * This class allows you to debug your MagicDraw plugin
 *
 * @author Xavier Seignard
 */
public class Debug {
	/**
	 * @param args
	 */
	public static void main(String[] args) {
		try {
			SimplePlugin plugin = new SimplePlugin();
			Application app = Application.getInstance();
			// Start the application (visible, not silent,
			// don't try to load a project, the given args,
			// the StartUp participant)
			app.start(true, false, false, args, null);
			plugin.init();
		} catch (ApplicationExitedException e) {
			e.printStackTrace();
		}
	}
}

Then all you need to do is to right-click on this class and choose “Debug as” to launch MagicDraw within the Eclipse debugger and use all the functionalities it gives us!

Nota : Maybe you’ll need to tune up a bit more your debug configuration by adding “-Xmx1024m” as VM argument as shown below :

Hope this helps! See you!

M2M/M2T tools:

• actifsource (http://www.actifsource.com/)
• AndroMDA (http://www.andromda.org/)
• Eclipse ATL (http://www.eclipse.org/atl/) is a part of Eclipse Modeling project
• Eclipse QVTO (http://wiki.eclipse.org/M2M/QVTO) is a part of Eclipse Modeling project
• Itemis/Eclipse xpand/xtend (http://wiki.eclipse.org/Xpand) it was originaly a part of the no longer supported openArchitectureWare (http://oaw.itemis.com/ & http://www.openarchitectureware.org/) is now a part of Eclipse Modeling project
• Mia-Software Mia-Generation (http://www.mia-software.com/) is a part of Mia-Studio tool suite
• Mia-Software Mia-Transformation (http://www.mia-software.com/) is a part of Mia-Studio tool suite
• Obeo/Eclipse Acceleo (http://www.eclipse.org/acceleo/) is a M2T tool that has recently moved from the Obeo (http://www.obeo.fr/) company to Eclipse Modeling project

MDE application builders:

• Artisan Software Tools Artisan Studio (http://www.artisansoftwaretools.com/) for SysML
• Aspectize (http://aspectize.com/) for .NET target
• BluAge (http://www.bluage.com/)
• Jaxio Celerio (http://www.jaxio.com/)
• Jaxio SpringFuse (http://www.springfuse.com/) for Java Spring
• Mendix (http://www.mendix.com/)
• Outsystems Agile Platform (http://www.outsystems.com/agile-platform)
• SkyWay Software SkyWay Builder (http://www.skywayperspectives.org/) for Java Spring
• Sodius MDWorkbench (http://www.mdworkbench.com/ & http://www.sodius.com/)
• SoftFluent CodeFluent Entities (http://www.codefluententities.com/ & http://www.softfluent.com/) for .NET target
• SpringSource SpringRoo (http://www.springsource.org/roo) for Java Spring

Language workbenches:

• EMFText (http://www.emftext.org/)
• Itemis/Eclipse TMF Xtext (http://xtext.itemis.com/) is a part of Eclipse Modeling project (http://www.eclipse.org/Xtext/)
• Jetbrains MPS (http://www.jetbrains.com/mps/)
• Spoofax (http://strategoxt.org/Spoofax/WebHome)

DSM (Domain Specific Modeling) workbenches:

• Isomeris ABSE & Atomweaver (http://www.atomweaver.com/ , http://www.abse.info/ & http://www.isomeris.com/) quite intriguing tools that will be launched during Q3(July) 2010
• MetaCase MetaEdit+ (http://www.metacase.com/)
• Obeo Designer (http://www.obeo.fr/pages/obeo-designer/en)

MDE UI design tools:

• Eclipse E4/XWT (http://wiki.eclipse.org/E4/XWT)
• redView (http://redview.org/)
• wazaabi (http://wazaabi.org/)

Modernization tools:

• eclipse MoDisco (http://www.eclipse.org/MoDisco/) is a part of Eclipse Modeling project
• Mia-Sotware Mia-Modernization (http://www.mia-software.com/) is a part of Mia-Studio tool suite
• Obeo Agility (http://www.obeo.fr/pages/agility/en)

CASE tools with MDE capabilities:

• ModelioSoft Modelio (http://www.modeliosoft.com/)
• NoMagic MagicDraw (http://www.magicdraw.com/)
• Sparx System Enterprise Architect (http://www.sparxsystems.com/products/ea/)

XSLT based tool:

• Xomega (http://www.xomega.net/)

• this is a mature tool,
• enterprise ready,
• and easy to use.

Then there’s a lot of great side functionalities like :

• reporting templates,
• dependency matrix,
• active validation
• and even more²!

But in a model driven environment, MagicDraw is great because of its open API which allows you to manipulate models and diagrams really easily.

So it’s time to introduce a simple plugin to get familiar with this open API!

Some resources to start

First of all, you’ll find javadoc and samples in the “<MagicDraw_Install_Dir>\openapi” directory and documentation in “<MagicDraw_Install_Dir>\manual\MagicDraw OpenAPI UserGuide.pdf“.

The documentation is really good, so I think you’ll find all what you need there.

How plugins are working?

Each time MagicDraw starts, it scans the “<MagicDraw_Install_Dir>\plugin” directory to find subdirectories containing two main things :

• A “plugin.xml” file which describes your plugin, the required libraries, and how to start it.
• A jar containing a class which extends the “com.nomagic.magicdraw.plugins.Plugin” and implements its “init()” method.

Plugin.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- The id must be unique, I generally put the class that extends the Plugin class as id. -->
<plugin
    <!-- The id must be unique, I generally put the class that extends the Plugin class as id. -->
    id="fr.free.mdwhatever.simplePlugin.magicDraw.SimplePlugin"
    name="SimplePlugin"

    <!-- Here I put project.version as version because Maven will filter it and put the same version you find in the pom.xml. -->
    version="${project.version}" 

    <!-- Who is providing this plugin (i.e. your company or whatever). -->
    provider-name="Xavier Seignard"

    <!-- The class which extends the com.nomagic.magicdraw.plugins.Plugin class
    in order to init your plugin within MagicDraw. -->
    class="fr.free.mdwhatever.simplePlugin.magicDraw.SimplePlugin">

    <!-- MagicDraw API version required by plug-in. Plug-ins and their requires versions required by plug-in. -->
    <requires>
        <api version="1.0" />
    </requires>

    <!-- The runtime libraries your plugin needs. -->
    <runtime>
        <library name="${artifactId}-${version}.${packaging}" />
    </runtime>
</plugin>

The SimplePlugin class

Here is the plugin entrance, take a look at the commented code.

package fr.free.mdwhatever.simplePlugin;

import com.nomagic.magicdraw.plugins.Plugin;
import com.nomagic.actions.ActionsCategory;
import com.nomagic.magicdraw.actions.ActionsConfiguratorsManager;
import com.nomagic.magicdraw.core.Application;

/**
 * This class allows you to load your plugin in MagicDraw
 *
 * @author Xavier Seignard
 */
public class SimplePlugin extends Plugin {

    // Methods
    /**
     * Plugin initialization and registration of the action in MagicDraw
     */
    public void init() {
        try {
            // We create a new actions category
            ActionsCategory category = new ActionsCategory(null, null);
            // We add our plugin action in this newly created category
            category.addAction(new SimplePluginAction());
            // We get the MagicDraw action manager
            ActionsConfiguratorsManager manager = ActionsConfiguratorsManager.getInstance();
            // We add our new configuration for our category in the MagicDraw action manager
            manager.addContainmentBrowserContextConfigurator(new BrowserContextConfigurator(category));
            // If everything is OK we log it to the MagicDraw GUI logger
            // Not really clever to put it there, but it's just to show how to log something in MagicDraw
            Application.getInstance().getGUILog().log("[Simple Plugin] Loading OK");
        }
        catch (Exception e) {
            // If something goes wrong we log it to the MagicDraw GUI logger
            Application.getInstance().getGUILog().log(
                    "[Simple Plugin] Could not instantiate plugin : " + e.toString());
        }
    }

    /**
     * The plugin is always supported, no matter the version of MagicDraw, or the perspective, or what you want.
     *
     * @return always true
     */
    public boolean isSupported() {
        return true;
    }

    /**
     * Return true always, because this plugin does not have any close specific actions.
     *
     * @return always true
     */
    public boolean close() {
        return true;
    }
}

This plugin has to do something!

How to trigger it?

Some plugin can just listen to some event, or it can be triggered by a contextual menu item or a button or whatever. In the case below we add a contextual menu item. (Have a look at the “com.nomagic.magicdraw.actions.ActionsConfiguratorsManager“)

package fr.free.mdwhatever.simplePlugin;

import com.nomagic.actions.ActionsManager;
import com.nomagic.magicdraw.actions.BrowserContextAMConfigurator;
import com.nomagic.magicdraw.ui.browser.Tree;
import com.nomagic.actions.ActionsCategory;
import com.nomagic.actions.NMAction;
import com.nomagic.magicdraw.actions.MDActionsCategory;
import com.nomagic.actions.AMConfigurator;

/**
 * This class allows you to add your plugin action (i.e. SimplePluginAction.java) in MagicDraw contextual menu.
 * @author Xavier Seignard
 */
public class BrowserContextConfigurator implements BrowserContextAMConfigurator {
    // Attributes

    // Here is the category of the contextual menu where you'll find you plugin
    public final static String SIMPLE_PLUGIN_MENU_CATEGORY = "Simple Plugin Menu Category";
    // Here is the ID of your category
    public final static String SIMPLE_PLUGIN_MENU_ID = "SimplePluginMenuID";
    // Plugin action
    private NMAction action;

    /**
     * Default constructor.
     *
     * @param nmAction the NMAction to set
     */
    public BrowserContextConfigurator(NMAction nmAction) {
        this.action = nmAction;
    }

    // Methods
    /**
     * Adds the plugin in the MagicDraw ui.
     *
     * @param mngr the action manager of MagicDraw to be configured
     * @param tree the containement tree of MagicDraw, where the plugin will be added
     */
    public void configure(ActionsManager mngr, Tree tree) {
        // We try to find the existing category
        ActionsCategory category = (ActionsCategory) mngr.getActionFor(SIMPLE_PLUGIN_MENU_ID);
        // If it doesn't exist we create it
        if (category == null) {
            category = new MDActionsCategory(SIMPLE_PLUGIN_MENU_ID, SIMPLE_PLUGIN_MENU_CATEGORY);
            category.setNested(true);
            mngr.addCategory(category);
        }
        // Then we add the action to the category
        category.addAction(action);
    }

    /**
     * Getter for priority.
     *
     * @return the priority int
     */
    public int getPriority() {
        return AMConfigurator.MEDIUM_PRIORITY;
    }
}

Set its behaviour

You have to extend the corresponding action, in this case : DefaultBrowserAction.

package fr.free.mdwhatever.simplePlugin;

import java.awt.event.ActionEvent;
import javax.swing.JOptionPane;
import com.nomagic.magicdraw.ui.browser.actions.DefaultBrowserAction;
import com.nomagic.uml2.ext.magicdraw.classes.mdkernel.Element;

/**
 * This class defines the behavior of the action in your plugin.
 *
 * @author Xavier Seignard
 */
public class SimplePluginAction extends DefaultBrowserAction {
    // Attributes
    // Serial version UID.
    private static final long serialVersionUID = 1L;
    // The name of the action which will be displayed in MagicDraw
    private static final String SIMPLE_PLUGIN_ACTION_NAME = "Simple Plugin Action";
    // The id of the action which will be displayed in MagicDraw
    private static final String SIMPLE_PLUGIN_ACTION_ID = "SimplePluginActionID";

    /**
     * Default constructor.
     *
     * @throws Exception if the super(...) call fails
     */
    public SimplePluginAction() throws Exception {
        super(SIMPLE_PLUGIN_ACTION_ID, SIMPLE_PLUGIN_ACTION_NAME, null, null);
    }

    // Methods
    /**
     * Here you define what does your action
     *
     * @param actionEvent the triggering event
     */
    public void actionPerformed(ActionEvent actionEvent) {
        SimplePluginBehavior simplePluginBehavior = new SimplePluginBehavior();
        CountingVisitor countingVisitor = simplePluginBehavior.getVisitor();
        // Clear the map for a clean count
        countingVisitor.getMap().clear();

        // Visit the children for counting elements of each type
        simplePluginBehavior.visitChildren((Element) getSelectedObject());
        // Display the counting results
        String result = simplePluginBehavior.returnResults(countingVisitor.getMap());
        JOptionPane.showMessageDialog(null, result);
    }

    /**
     * Defines when your action is available.
     */
    public void updateState() {
        // This action is only available when your click on an instance of Element in the containment tree
        if (this.getSelectedObject() != null) {
            if (this.getSelectedObject() instanceof Element) {
                setEnabled(true);
            }
            else {
                setEnabled(false);
            }
        }
        else {
            setEnabled(false);
        }
    }
}

This visitor pattern

The visitor pattern is well implemented in the Magicdraw open API, and it saves you a lot of efforts, so use it!

package fr.free.mdwhatever.simplePlugin;

import java.util.HashMap;
import com.nomagic.magicdraw.uml.BaseElement;
import com.nomagic.magicdraw.uml.ClassTypes;
import com.nomagic.magicdraw.uml.InheritanceVisitor;
import com.nomagic.uml2.ext.jmi.reflect.VisitorContext;
import com.nomagic.uml2.ext.magicdraw.classes.mdkernel.Element;

/**
 * This class extends InheritanceVisitor to count element through the visitor pattern.
 * @author Xavier Seignard
 *
 */
public class CountingVisitor extends InheritanceVisitor {

    // Map for counting results. Class type is a key, number is a value.
    private HashMap countMap = new HashMap();

    /**
     * The visitation of the element.
     *
     * @param element the element to visit.
     * @param context the context of the visitor.
     */
    public void visitElement(Element element, VisitorContext context) {
        super.visitElement(element, context);
        // Call the count
        countElements(element);
    }

    /**
     * Count elements of each type.
     *
     * @param element the element to count.
     */
    public void countElements(BaseElement element) {
        // We get the human readable name of the element
        String classType = ClassTypes.getShortName(element.getClassType());
        // Then we get the count of this type of elements
        Integer count = countMap.get(classType);
        // If it is the first element of this type we visit, we need to create a new value for the counting
        if (count == null) {
            count = Integer.valueOf(0);
        }
        // Finally we increase the count
        countMap.put(classType, Integer.valueOf(count.intValue() + 1));
    }

    /**
     * Getter for countMap.
     * @return the countMap
     */
    public HashMap getMap() {
        return countMap;
    }
}

The implementation of the behavior

Finally here is the implementation of the behaviour which allows you to calculate some metric like classes per package, or methods per classes :

package fr.free.mdwhatever.simplePlugin;

import java.util.HashMap;
import com.nomagic.magicdraw.core.Application;
import com.nomagic.uml2.ext.magicdraw.classes.mdkernel.Element;

/**
 * The behavior of our MagicDraw plugin
 *
 * @author Xavier Seignard
 */
public class SimplePluginBehavior {  

    // Our visitor to count the type of each element.
    private CountingVisitor visitor = new CountingVisitor();

    /**
     * Returns a string containing the counting results
     *
     * @param map the HashMap containing the counting results
     * @return string describing the counting results
     */
    public String returnResults(HashMap map)
    {
        // The string to return
        String textToReturn = "";
        textToReturn += "Number of elements for each types :\n";
        for (String key : map.keySet()) {
            textToReturn += "\t"  + key + " : " + (map.get(key)).intValue() + "\n";
        }

        // Calculation for some means (the real interesting part)
        Integer packages = map.get("Package");
        Integer classes = map.get("Class");
        Integer attributes = map.get("Property");
        Integer operations = map.get("Operation");

        if (packages != null && classes != null) {
            textToReturn += "Average classes per package : " + (classes.doubleValue()/packages.doubleValue()) + "\n";
        }

        if (classes!=null && operations!=null) {
            textToReturn += "Average operations per class : " + (operations.doubleValue()/classes.doubleValue()) + "\n";
        }

        if (classes!=null && attributes!=null)
            textToReturn += "Average attributes per class : " + (attributes.doubleValue()/classes.doubleValue()) + "\n";

        // if map was empty and no elements was found.
        if (textToReturn.length()==0)
        {
            textToReturn = "No elements found!";
        }

        return textToReturn;
    }

    /**
     * We parse all the children of the given root element.
     * For each element, we visit it to count the types of the elements
     *
     * @param rootElement the root element to start counting
     */
    public void visitChildren(Element rootElement)
    {
        try {
            rootElement.accept(visitor);
        }
        catch (Exception e) {
            // If something goes wrong we log it to the MagicDraw GUI logger
            Application.getInstance().getGUILog().log(
                    "[Simple Plugin] Exception occured : " + e.toString());
        }
        // We visit the children elements
        for (Element child : rootElement.getOwnedElement()) {
              visitChildren(child);
        }
    }

    /**
     * Getter for the visitor.
     * @return the visitor
     */
    public CountingVisitor getVisitor() {
        return visitor;
    }
}

Conclusion

You’re now familiar with the MagicDraw openAPI! So lets go and develop your own plugin!

You’ll find a packaged version of this Eclipse/Maven2 project there : magicdraw-simple-plugin.tar.gz
To set up your environement, you’ll have to upload some MagicDraw libs to your maven2 local repo. You’ll find them in the “<MagicDraw_Install_Dir>\lib\” directory. The list of the needed libs are described in the “dependencies” section in the “pom.xml” file.

You’ll also need to declare an environement variable “MDUML_HOME” which is the “<MagicDraw_Install_Dir>“.

Then if you execute a “mvn clean install” it will compile the plugin and install it on your MagicDraw installation. And you’ll just have to start MagicDraw to test the plugin.

In a next blog post we’ll see how to debug your plugins within Eclipse.

1 : Have a look here : http://www.magicdraw.com/main.php?ts=navig&=&cmd_show=1&menu=testimonials, you’ll find my testimonial!

2 : Here is the features list of MagicDraw: http://www.magicdraw.com/main.php?ts=navig&cmd_show=1&menu=feature_list

C’est ce que nous appliquons chez le client chez qui j’interviens.

Maven2 nous sert (entre autres) à :

• Exécuter un export vers XMI depuis MagicDraw ;
• Exécuter des fonctionalités particulières de MagicDraw sans pour autant lancer MagicDraw en mode graphique ;
• Exécuter nos propres plugins MagicDraw ;
• Valider nos modèles avec nos propres règles de validation codées avec l’API emf/uml2 d’eclipse ;
• Lancer nos transformations de modèle ;
• Et finalement de générer avec MIA-Generation.

Pour certaines des tâches ci-dessus il existe des plugins Maven2, pour les autres vous pouvez développer vos propres plugins Maven2.

Pas de panique, la courbe d’apprentissage est faible, et on obtient rapidement ce que l’on veut!

Malheureusement, il n’est pas toujours facile de trouver de la documentation sur la création de plugins pour Maven2.
Pour vous aider à débuter, voici quelques liens qui m’ont été très utiles :

• Maven Developer Centre
• API Maven 2.1.0 – Plugin
• API Maven 2.1.0 – Full
• Guide to Developing Java Plugins for Maven2
• Mojo Developer Cookbook
• Write your own report plugin
• Maven Properties Guide
• Create a Customized Build Process in Maven
• Creating an Ant Maven Plugin
• Créer un nouveau packaging Maven
• Maven DOCCK Plugin – Documentation Validation
• Maven – The Maven Embedder
• Tetedebois.org » Maven embarqué
• Re: Maven Embedder Example?
• How to resolve an artifact with maven embedder

Le rendez-vous est pris avec Maven3!