Developing Plug-Ins - Get your Plug-In running.Explanations
This page collects some deeper explanations to understand things explained at Developing_Plug-Ins_-_Get_your_Plug-In_running. These informations are not inserted at this page to not destroy the fast flow through the how-to and overwhelm users with informations they mostly do not need (but may be worthful if you need).
Short: MANIFEST.MF is the file to configure all attributes of your OSGi plugin. It is places in your plugin jar file at "META-INF/MANIFEST.MF" and is read by the OSGi framework (Equinox) to discover the capabilities of your plugin. It may be accompanied by the file plugin.xml for some specific needs.
There are two files that describe all the attributes of your OSGi Plugin: META-INF/MANIFEST.MF and plugin.xml. To understand that you have to know a bit of historical background. Much of this technology belongs to the Eclipse Platform. In former times there was a file "plugin.xml" to describe the attributes of an Eclipse Plugin. From Eclipse 3.1 (I think so) on Eclipse changed to a new plugin system. This was the point to introduce the Equinox Library. Equinox is an implementation of the OSGi Plugin Architecture. It is part of the Eclipse project and at the beginning the Equinox project was founded as an OSGi implementation for the Eclipse Platform. OSGi defines a file named "META-INF/MANIFEST.MF" to describe the attributes of an OSGi Plugin.
The easy way would have been to switch from the old to the new system. But there was a problem: The OSGi consortium is a kind of big and slow thing and you can not extend the specification very fast without going through a time consuming standardization process. And Eclipse needed some capabilities which were not standardized in OSGi. So the Equinox framework implemented the standard conforming thing the standard way (configured throug MANIFEST.MF) and used a second configuration file (plugin.xml) to configure the equinox-specific features.
How does this belong to me as an iDempiere developer?
iDempiere uses Equinox as its OSGi implementation library. So you have the possibility to use both kinds of configuration. plugin.xml is only used if you need equinox-specific features. So you use MANIFEST.MF for the most of your plugin configuration.
This is the base plugin for iDempiere. It contains the most basic part of the code. It has to be included in the dependency list of every iDempiere plugin.
This plugin contains helping utilities for plugins. It contains the AdempiereActivator class. If you use this class as an OSGi activator it may do some work for you if the plugin is activated like aoutomatically creating entries in the database. See http://www.adempiere.com/Equinox_Integration_2/Tutorial_Plugin
A Singleton plugin may be loaded only once in a OSGi framework. On one hand OSGi is about the fact that plugins are not dependend from their environment and so it should not matter if there are other instances of the same plugin. On the other hand it often makes no sense to import a functionality two times and you can have strange errors if you are using a plugin two times - perhaps in different versions - because you forgot to deinstall the old version before installing a new one. [blog article] explains it a bit. [Vogel's tutorial] also uses only Singleton Plugins.
In iDempiere in general you should use only Singleton Plugins.
Problems with the workflow from the article Developing Plug-Ins - Get your Plug-In running
After following the article I created an own activator class like
MyActivator extends AdempiereActivator. The class was empty. It did not compile with the error message
- The project was not built since its build path is incomplete. Cannot find the class file for org.osgi.util.tracker.ServiceTrackerCustomizer. Fix the build path then try building this project.
The error went away after adding "org.eclipse.osgi" to my plugin's dependencies. I do not understand why this is needed. I do not use the ServiceTrackerCustomizer directly in my code and the OSGi mechanisms should solve this.
Can someone help?!?