Developing Import and Export Plug ins

Creating Import and Export Plug-ins

To create a plug-in for Archi that allows you to export or import certain file types into or out of Archi take a look at the example plug-in, com.archimatetool.importexportexample in the source code. There are two classes, MyExporter.java and MyImporter.java that illustrate how to achieve this.

Tutorial - Creating an Export Plug-in

The simplest way to do this is to copy and modify the com.archimatetool.importexportexample plug-in:

1. In Eclipse copy the com.archimatetool.importexportexample plug-in (found in the "other" folder) and give it a suitable name, for example "org.myorganisation.export"
2. In Eclipse, view the project in the Package Explorer. It should look like the following:

3. Delete the MyImporter.java class as we won't be needing it
4. Open the plugin.xml file to edit it. Fill in the fields on the "Overview" tab as follows:

5. On the "Extensions" tab of plugin.xml delete the com.archimatetool.editor.importHandler entry. Only one entry should remain for the extension point com.archimatetool.editor.exportHandler
6. Also on the "Extensions" tab of plugin.xml edit the label to describe the format you wish to export to. For example "Model to HTML Format..."

7. To test that it is working create a Launch configuration to Run Archi. See Running and Debugging Archi for details on how to set this up. Ensure that your plug-in is included on the list of plug-ins:

8. Now Run Archi from Eclipse. Select a model in the Models Tree and then select the "File->Export" menu. You should see your plug-in's export menu item:

9. If you select the menu item and provide a file name then the model should be saved in the format of a "*.mex" file using the format as defined in the MyExporter.java class

Converting the Model to an Export Format

Now all you need to do now is to edit the MyExporter.java class to do the work of converting the ArchiMate model into your chosen format.

This is achieved by taking the IArchimateModel instance from the following:

@Override
public void export(IArchimateModel model) throws IOException {
    File file = askSaveFile();
    if(file == null) {
        return;
    }
    
    writer = new OutputStreamWriter(new FileOutputStream(file));
    
    writeFolder(model.getFolder(FolderType.BUSINESS));
    writeFolder(model.getFolder(FolderType.APPLICATION));
    writeFolder(model.getFolder(FolderType.TECHNOLOGY));
    writeFolder(model.getFolder(FolderType.CONNECTORS));
    writeFolder(model.getFolder(FolderType.RELATIONS));
    
    writer.close();
}

The first thing that happens is the user is asked by means of a file dialog to provide a file name. If this is not null (user cancelled) then a new OutputStreamWriter is created.

Here, the IArchimateModel instance is then accessed for all of its folders. The contents of each IFolder is then written to the output stream as follows:

private void writeFolder(IFolder folder) throws IOException {
    List<EObject> list = new ArrayList<EObject>();
    getElements(folder, list);
    for(EObject eObject : list) {
        if(eObject instanceof IArchimateElement) {
            String s;
            IArchimateElement element = (IArchimateElement)eObject;
            s = normalise(element.eClass().getName()) + "," + normalise(element.getName())
                    + "," + normalise(element.getDocumentation());
            writer.write(s + "\n");
        }
    }
}

private void getElements(IFolder folder, List<EObject> list) {
    for(EObject object : folder.getElements()) {
        list.add(object);
    }
    
    for(IFolder f : folder.getFolders()) {
        getElements(f, list);
    }
}

private String normalise(String s) {
    if(s == null) {
        return "";
    }
    
    s = s.replaceAll("\r\n", " ");
    s = "\"" + s + "\"";
    
    return s;
}

Deploying the Plug-in

The instructions given so far show you how to develop and run the plug-in from within Eclipse as a developer. The end-user will need to deploy your plug-in in their Archi installation separately in their "plugins" folder. You will therefore need to:

1. Export the plug-in as a jar file from Eclipse (File -> Export -> Deployable plug-ins and fragments)
2. Make the plug-in jar available to Archi users

The Archi user will need to:

1. Close Archi if it is open
2. Copy the plug-in to the Archi's "dropins" folder (if this does not exist you will need to create it)
3. Relaunch Archi
4. After relaunching Archi, the new export or import menu will be available in Archi.

Note:

The default "dropins" folder is located in the following places:

Windows: %user.home%/AppData/Roaming/Archi/dropins
Mac: %user.home%/Library/Application Support/Archi/dropins
Linux: %user.home%/.archi/dropins

("%user.home%" denotes your home directory.)

Or you can manually create a "dropins" folder alongside the Archi installation's "plugins" folder.