Developing plug-ins without affecting the trunk

From iDempiere en
Jump to navigation Jump to search

This tutorial is brought to you by Jan Thielemann from evenos GmbH. If you have questions, criticism or improvement suggestions, feel free to visit me (Jan.thielemann) or write me an email

The goal of this tutorial

This tutorial is about developing plug-ins which are not targeted to be pushed into the trunk. You might want to do this because:

  • the plug-in is for personal use only;
  • the plug-in is for testing or tutoring purposes;
  • you have customers that require customized plug-ins that run on the same base;
  • you want to separate plug-in and base development so you can push fixes and improvements to the trunk without exposing your plug-ins.


You must have the iDempiere workspace running in Eclipse with the Mercurial client and the Mercurial Eclipse plug-in.

Related tutorials

If you don't fulfill the prerequisites, you should take a look at the following tutorials:

The workflow

After your workspace is set up and useable, we can start creating new plug-ins. To do so, create a new plug-in project by clicking "File>New>Other...".


Select Plug-in Project in the Plug-in Development folder and click "Next"


Give the new project a name of your choice (typically your reverse domain name and the name of the plug-in) and uncheck the "Use default location" checkbox. Now you can chose your own location by clicking on "Browse..."


Since our idempiere workspace lies in /home/user/workspace/idempiere, it is a good idea to create an additional folder for your plug-ins. In our case, we create the folder idempiere-plugins (/home/user/workspace/idempiere-plugins)


Because we probably will develop more than one plug-in, we create an additional folder for each plug-in the the idempiere-plugins folder. We chose the name according to our project name. In our case it is "de.evenos.testplugin". Select this folder and click on "OK"


Make sure that this plug-in is targeted to run with the Equinox OSGi framework and click on "Next"


Select a execution environment of your choice (Java 6 is a good idea) and uncheck the "Generate an activator..." checkbox. Click on "Next"


Uncheck the checkbox and click on "Finish", unless you want to create the plug-in using a template.


The new plug-in project gets created. You may notice that, unlike the other projects, your new plug-in is not attached to a repository (notice that other projects have the [development] tag behind their name)


You probably want to track changes in your plug-in, share it via mercurial or have the need to work together with others, so lets make the new plug-in ready to use for mercurial. To do this, rightclick on the project and chose "Team>Share Project"


Select "Mercurial" and click on "Next"


Make sure that the correct path is selected and click on "Finish"


Congratulations, your new plug-in is ready for development. All changes you commit to your plug-in won't affect the idempiere repository.


Additional Notes

Instead of creating a mercurial repository for each of your plug-ins and fragments, you can also follow another approach:

  • Create a directory on your harddrive which will contain all of your plug-ins and fragments
  • Create a mercurial repository in this directory
  • Place all new created plug-ins and fragments in the repository directory and skip the part where you create the repositories
  • Now you have one big repository containing all your files

Declare Service Annotation Get rid of xml

Reference link

How to use

  • You have to use eclipse Oxygen and newer
  • Configuration eclipse to support DS annotation
Eclipse DS annotation configuration
  • Add the following dependencies on the Imported Packages side:

Mark org.osgi.service.component.annotations as Optional

Service factory

  • On factory class add annotation like bellow
Sample code


 property= {"service.ranking:Integer=2"},
 service = org.adempiere.base.IProcessFactory.class

public class JRProcessFactory implements IProcessFactoryNew

  • you don't need service if you implement direct service interface like IProcessFactory
  • for array properties, repeat properties name

Event handle

  • On handle class extend from AbstractEventHandler add annotation like bellow
Sample code


   reference = @Reference( 
                 name = "IEventManager", bind = "bindEventManager", unbind="unbindEventManager", 
                 policy = ReferencePolicy.STATIC, cardinality =ReferenceCardinality.MANDATORY, service = IEventManager.class)

public class SampleEventHandle extends AbstractEventHandler{