A plugin is implemented against one the the existing APIs (Canonizer, Search, Clustering, ...) or comes with a new API. This How To describes how to create a new API. Before starting please ensure you setup your development environment as described here.
If you encounter any error or issues using this How To, please raise an issue in our Apromore JIRA.
A Plugin API is usually made up of one (or more) Java interfaces that extend one of the existing interfaces from the Plugin API package. (Plugin, ParameterAwarePlugin) Often it is useful to provide a default implementation that inherits from DefaultPlugin or DefaultParameterAwarePlugin as these abstract classes provide easy handling of meta data and optional/mandatory properties. Meta data includes currently the following values. DefaultPlugin allows you to put these in a simple ".config" file:
Properties should be used to provide users of a Plugin with the possibility to specify parameters that are specific to the Plugin and not part of the API. An example would be a Search Plugin which allows you to choose between different algorithms. A good example is the YAWL Deployment Plugin.
First you need to write your own interfaces that extends the Plugin or ParameterAwarePlugin interface and defines the methods your plug-ins have to implement. Afterwards you should write a PluginProvider that exposes all plug-ins that implement your plug-in API. The PluginProvider will be used by Apromore to find all installed Plugins at runtime.
Your Plugin API and Plugin API Provider should be kept separate from each other, so you need to create two new Maven modules (projects).
Create a new Plugin API project
To create a new Plug-in API project you can simply use one of the existing Plug-in API projects as template and copy it to a new directory. You could, for example, use the Canoniser API and copy it to the directory:
Now you MUST modify the Maven project file (pom.xml) to reflect your new Plug-in. The important parts that need to be changed are shown below:
- Next delete the existing code for the Canoniser API in
src/test/javaand add the interfaces and classes needed for your Plug-in API.
Try to build your API using Maven
- If you see BUILD SUCCESS, then everything works!
Create a new Plugin API Provider project
To create a new Plug-in API Provider project you can simply use one of the existing Plug-in API Provider projects as template and copy it to a new directory. You could, for example, use the Canoniser API Provider and copy it to the directory:
Now you MUST modify the Maven project file (pom.xml) to reflect your new Plug-in. The important parts that need to be changed are shown below. Be sure to include the Plug-in API project you just created in the dependencies. For example, the Canoniser API Provider defines a dependency to the Canoniser API.
- Next, rename the Java class
CanoniserProviderImpl.javain the directory
src\main\java\org\apromore\canoniser\provider\implto match your plug-in package and name.
You can probably re-use some of the existing code, as plug-in providers are mostly just a convenience layer on top of the OSGi services.
To enable the automatic discovery of OSGi services (i.e. all available plug-ins) you need to adapt the file
osgi-context.xmlin the directory
src\main\resources\META-INF\springto your needs.
Now try to build your API Provider using Maven:
- If you see BUILD SUCCESS everything works!