Developing IGB bundles
----------------------
IGB bundles are OSGi compatible, so they must have an Activator, a class that extends org.osgi.framework.BundleActivator,
and they must have a manifest.mf file that is found in the META-INF directory. These are compiled and jarred with all required
classes, jars, and resources. The resulting jar is the bundle. This can then be uploaded to the bundle repository. At that point,
any one can use the bundle with IGB. IGB uses the Apache Felix OSGi implementation, but this could change, so no Felix specific
code should be used. In the Activator class, there is a start() and stop() method that are called when the bundle is
activated / deactivated (not installed / uninstalled). This is where you want to put all the code to start and stop the bundle.
In the manifest.mf file, there are several headers that need to be specified - fill in parenthesis below:
IGB bundles are OSGi compatible, so they must have an Activator, a class that extends org.osgi.framework.BundleActivator,
and they must have a manifest.mf file that is found in the META-INF directory. These are compiled and jarred with all required
classes, jars, and resources. The resulting jar is the bundle. This can then be uploaded to the bundle repository. At that point,
any one can use the bundle with IGB. IGB uses the Apache Felix OSGi implementation, but this could change, so no Felix specific
code should be used. In the Activator class, there is a start() and stop() method that are called when the bundle is
activated / deactivated (not installed / uninstalled). This is where you want to put all the code to start and stop the bundle.
In the manifest.mf file, there are several headers that need to be specified - fill in parenthesis below:
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: (name of bundle)
Bundle-SymbolicName: (name of bundle)
Bundle-Version: (bundle version, you can use 1.0.0 to start)
Bundle-Activator: (activator class name, including package)
Bundle-ActivationPolicy: lazy
Bundle-Vendor: Affymetrix
Bundle-Vendor: (your company)
Bundle-DocURL: (URL of bundle documentation)
Import-Package: (list all external packages required by the bundle)
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Bundle-ClassPath: (put the class path within the bundle itself, e.g.: ., resources/, lib/xyz.jar)
Bundle-Description: (description of bundle)
Require-Bundle: (list all bundles required by this bundle)
Import-Package and Require-Bundle don't need to overlap, you can specify a requirement
in one or the other. To have a multi line header, start the continuation line after a blank in column 1.
Put a blank line at the end of the manifest.me file - due to a bug in felix.
The genometry and genoviz projects can by accessed as bundles (Require-Bundle), but the
IGB project is accessed through an interface, IGBService, itself a bundle.
If a class/method is needed from genometry/genoviz, it must be public, and the package
must be exported in the manifest.mf Export-Package list.
For access to IGB, this is done through the IGBService. If IGBService does not have a method
for what you need, it may need to be added to IGBService and IGBServiceImpl.
If you want to add a tab window as a bundle, there is a helper abstract class,
com.affymetrix.igb.window.service.WindowActivator, that you can extend.
If you need access to other bundles (like IGBService), you will not be sure when the
bundle is available. For Services, like IGBService and WindowService, you can use a
ServiceTracker to be notified when the required bundle is available - see WindowActivator
for an example.
To test the bundle, you can specify it as an optional bundle for IGB, by adding the jar
name to the pluginsOptionalList= entry in igb.properties.
Note - eclipse makes it a lot easier to develop bundles. You can create a new project
as a plug in project, and it will give you wizards, etc. for development. see:http://www.vogella.de/articles/OSGi/article.html
To create plug-ins using eclipse,
(using eclipse Helios)
- check out IGB from https://genoviz.svn.sourceforge.net/svnroot/genoviz
into a new project in eclipse
- make a new IGB_HOME environment variable to point to the IGB project
- open a command prompt in IGB_HOME, and do an "ant clean" and "ant jar"
- in eclipse, project explorer, right click the IGB project and select "refresh"
- in eclipse, project explorer, right click on open space, and select "Import..."
Select "Plug-ins and Fragments" under "Plug-in Development", click the "Next >" button
under "Import From", select "Directory:",
under "Plug-ins and Fragments to Import" select "Select from all plug-ins and Fragments",
under "Import As" select "Binary Projects"
for "Directory:", click the "Browse..." button and select the IGB_HOME/ext, click the "OK" button
click the "Next >" button
under "Plug-ins and Fragments Found:", select affx_fusion, colt, freehep, image4j, jlfgr, picard, and sam
click the "Add -->" button to add these all to "Plug-ins and Fragments to Import:", click the "Finish" button
- Do the following for the directories under IGB_HOME, genometryImpl, genoviz_sdk, igb, plugins/igb_service, plugins/window_service
in eclipse, project explorer, right click on open space, and select "Import..."
Select "Existing Projects into Workspace" under "General", click the "Next >" button
click "Select root directory:" and click the "Browse..." button on the right
select the project under IGB_HOME, and click "OK"
click "Finish"