Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
BPMN2-Modeler/DeveloperTutorials/ExtendingRuntime
Contents
Versions
This Tutorial was developed with Eclipse 4.5 (Mars) and BPMN2-Plugin version 1.2.3.
The Environment
First, install the BPMN2 Modeler plugin from the updatesite into your Eclipse development IDE. If you are working with Eclipse Luna, plugin development is much easier than in the early years of Eclipse. So most things can be controlled from the plugin editor and Eclipse will take care of finding and installing dependencies for the BPMN2 Modeler plugin.
If you also install the BPMN2 Sources from the updatesite you can look around the BPMN 2 implementations which will sometimes help to understand some behavior in the background. Optionally you can also import the following plugins into your Eclipse Workspace.
org.eclipse.bpmn2.modeler.core org.eclipse.bpmn2.modeler.feature org.eclipse.bpmn2.modeler.runtime.example org.eclipse.bpmn2.modeler.ui
Create a Plugin project
First of all create a new Eclipse Plugin project. To extend the BPMN Plugin you first need to add some of the necessary dependencies.
Open the plugin.xml with the plugin editor and switch to the ‘dependencies’ tab and add the following bpmn2 and graphiti dependencies:
org.eclipse.bpmn2 org.eclipse.bpmn2.edit org.eclipse.bpmn2.editor org.eclipse.bpmn2.core org.eclipse.bpmn2.ui org.eclipse.graphiti org.eclipse.graphiti.ui org.apache.xerces
The dependencies are added into the MANIFEST.MF File into the section ‘Runtime-Bundle’. This section should look like this:
.... Require-Bundle: org.eclipse.core.runtime, org.eclipse.emf.ecore;visibility:=reexport, org.eclipse.emf.ecore.xmi;visibility:=reexport, org.eclipse.graphiti;bundle-version="[0.11.0,0.12.0]", org.eclipse.graphiti.ui;bundle-version="[0.11.0,0.12.0]", org.eclipse.gef, org.eclipse.bpmn2, org.eclipse.bpmn2.edit, org.eclipse.bpmn2.editor, org.eclipse.bpmn2.modeler.core, org.eclipse.bpmn2.modeler.ui, org.eclipse.emf.transaction, org.eclipse.emf.databinding, org.eclipse.emf.edit.ui, org.eclipse.ui.views.properties.tabbed, org.eclipse.jface.databinding, org.apache.xerces, org.eclipse.core.resources, org.eclipse.core.runtime, org.eclipse.ui, org.eclipse.jdt.core .....
Create and optional EMF model
Before starting, it is a good idea to think about whether or not you will need (or already have) an EMF model Ecore and Java implementation classes. The namespace URI defined in that model will be required when you create your RuntimeExtension in the next section.
There are lots of resources on the web about how to work with the EMF Ecore editor and model generator. When you are comfortable with that process, you may want to also reference the Model Extension tutorial to learn how to integrate the model with your BPMN2 Modeler extension plugin.
Create a new RuntimeExtension
The core element of a BPMN2 Modeler plugin extension is the so-called "BPMN2 Runtime Extension". So first of all you need to create a new Class which implements the Interface ‘IBpmn2RuntimeExtension’.
In the RuntimeExtension implementation you need to provide a method to let the editor know if a bpmn file should be handled by your plugin. This can be done by “peeking” at the contents of the file and checking the targetNamespace declared in the <bpmn2:definitions> element. if you will be using a model extension, the namespace URI defined in the model must match your RuntimeExtension's targetNamespace. Note that either way you must define a targetNamespace - it can not be empty.
Note that the targetNamespace test does not have to be the only criterion for determining if the model file should be handled by your plugin. This can be as simple or complex as necessary, but care should be taken here since there may be several other editor extension plugins that will need to perform this same test. Also, your tests should be as quick as possible because it will delay editor startup.
This is how the RuntimeExtension will look like so far:
package bpmn2.tutorial;
import org.eclipse.bpmn2.modeler.core.utils.ModelUtil.Bpmn2DiagramType;
import org.eclipse.bpmn2.modeler.ui.AbstractBpmn2RuntimeExtension;
import org.eclipse.bpmn2.modeler.ui.wizards.FileService;
import org.eclipse.ui.IEditorInput;
import org.xml.sax.InputSource;
public class ImixsRuntimeExtension extends AbstractBpmn2RuntimeExtension {
public static final String RUNTIME_ID = "org.imixs.workflow.bpmn.runtime";
public static final String targetNamespace = "http://bpmn2.tutorial.org/bpmn2";
@Override
public String getTargetNamespace(Bpmn2DiagramType diagramType) {
return targetNamespace;
}
/**
* IMPORTANT: The plugin is responsible for inspecting the file contents!
* Unless you are absolutely sure that the file is targeted for this runtime
* (by, e.g. looking at the targetNamespace or some other feature) then this
* method must return FALSE.
*/
@Override
public boolean isContentForRuntime(IEditorInput input) {
InputSource source = new InputSource(
FileService.getInputContents(input));
RootElementParser parser = new RootElementParser(
"http://bpmn2.tutorial.org/bpmn2");
parser.parse(source);
return parser.getResult();
}
}
Define the runtime Extension Point
Now you can add a new Runtime Extension point to your plugin. Open the plugin.xml with the Eclipse Plugin Editor and go to the tab ‘extensions’. Here you can add a new extension from the type:
org.eclipse.bpmn2.modeler.runtime
After you added your new extension you can start with the configuration of your extension.
Click ‘new -> runtime’ to define your runtime Extension Point. Chose your java class file created before and define a Name and a unique ID. This ID is required by the editor and other extension points.
Test the Plugin
Now you can run your first smoke test. Just launch your plugin as an Eclipse Application from the plugin.xml Editor. Create a new empty project in the runtime workspace and open the project properties dialog (right-click on the project name and select "Properties" from the context menu.) you should see the section ‘BPMN2′ with a "Target Runtime" selector. Your new Runtime Extension should be listed here. Go ahead and select it then save and close the properties dialog.
Behind the scenes, setting this project property creates a ".settings" folder and a project-specific configuration file for the BPMN2 Modeler. Now when you create a new "Generic BPMN 2.0 Diagram" with the New File Wizard, the newly created BPMN2 file will be constructed with the targetNamespace defined by your Runtime Extension.
