Introduction

Plugins are software programs that can be dynamically added to existing programs to add / enhance functionality. They are also called Add-ons or Bundles (the OSGi term). In IGB, plug-ins are also called "Apps." You may have seen plugins in the software that you use, Internet such as internet browsers, text/graphics editors, games, etc. Examples include Adobe Flash and Adobe Reader for browsers, Chrome extensions and countless Photoshop filters. Users can search for plugins and choose ones that address their needs. Users can add a new plugin (download and install) whenever they want. They can remove a plugin if they no longer need it. The plugins can or remove plugins at will without having to re-install the base application. Plugins can also be updated dynamically when the author(s) make changes.

IGB uses OSGi to implement plug-

...

able Apps 

OSGi is specification and framework for building modular applications in java. In addition to the framework specification, it also contains a specification for dynamically installing and running plug-ins. The OSGi term for a Plugin is Bundle. They mean the same thing.

An OSGi bundle is a nothing but a jar file . It must have a with some OSGi-specific headers included in the its MANIFEST.MF file. The OSGi framework uses these headers to manage how the bundle interacts with other bundles within the same framework.  The OSGi headers (see below).framework also use the headers to manage transitions between lifecycle states for a bundle - installed, resolved, starting, active, stopping, and uninstalled.  

An OSGi bundle can (usually will) have a special java class called an Activator. This class must extend org.osgi.framework.BundleActivator, and implement the start() and stop() methods. The activator class is specified in the Bundle-Activator MANIFEST.MF header (see below). These methods are called when the bundle is started and stopped.

...

OSGi caches bundles, saving them to a directory called the "bundle cache" on the local hard disk, so that they don't need to be downloaded every time. So you can work offline after you have loaded IGB. IGB stores the App bundles alongside core IGB platform bundles in a folder called "bundles" in an IGB-specific directory called ".igb." The bundles directory contains subdirectories for specific IGB versions.   

There are several implementations of OSGi, including:

...

IGB uses OBR (http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html) to find and load bundles from web servers (repositories). The web servers need to use OBR to create the repository.xml file listing all the available bundles. 

Users can add / remove bundle repositories by choosing File>Preferences , Plugin Repositories tab.

IGB uses OSGi Services to allow bundles to add new implementations of existing IGB elements. The new implementations will show up as soon as the bundle is started. Examples include IGB tabs and graph manipulation functions.

Extension Points

...

IGB has several "extension points" designed specifically for pluginsApps. These are interfaces or abstract classes that
are implemented or extended by plugin versionsApp classes. Usually the Activator for the plugin App will register the plugin App as a
service in the its start() method:

Code Block
bundleContext.registerService(<extension point>.class.getName(), <plugin implementation>, new Properties());

The Some of the available extension points include:

• com.affymetrix.genometryImpl.operator.Operator - operates on a selection of tracks from the GraphAdjuster tab or popup menu
• com.affymetrix.genometryImpl.parsers.FileTypeHandler - process a file type (by the file extension)
• com.affymetrix.igb.shared.TrackClickListener - called when the user clicks on the label portion of a track
• com.affymetrix.igb.shared.GlyphProcessor - called when IGB creates a glyph
• com.affymetrix.igb.shared.MapViewGlyphFactoryI - a new way to display a track
• com.affymetrix.igb.search.mode.ISearchMode - a new search method option on the Search View tab
• com.affymetrix.igb.osgi.service.IGBTabPanel - a tab in the JTabbedPane at the bottom and sides of IGB
• com.affymetrix.genometryImpl.util.ServerTypeI - a server type
• com.affymetrix.igb.osgi.service.IStopRoutine - a routine to be run when IGB terminates
• com.affymetrix.igb.prefs.IPrefEditorComponent - a Preferences window to let users enter preferences

Developing IGB bundles

...

IGB-specific MANIFEST.MF requirements

To install an App into IGB, the 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. This is where you want to put all the code to start and stop the bundle.

MANIFEST.MF requirements

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: (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)

Plug-ins tab

If you look at the Plug-ins tab, you will see the Bundle-SymbolicName under the Name column, the Bundle-Description under the Description column, and the Bundle-Version under the Version column. If the Bundle-DocURL is there, the Name cell will have a blue info icon that links to this URL.

• Import-Package and Require-Bundle don't overlap, you can specify a requirement in one or the other, but Import-Package is recommended over Require-Bundle. 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.mf file - due to a bug in felix.
• The igb, genometry and genoviz projects can by accessed as bundles. If a class/method is needed from igb/genometry/genoviz, it must be public, and the package must be exported in the MANIFEST.MF Export-Package list of the bundle that contains the class (igb, genometry or genoviz).
• If you want to add a tab panel as a bundle, there is a helper abstract class, com.affymetrix.igb.window.service.WindowActivator, that you can extend.
• The order that OSGi starts the bundles is not specified, so at any given time, one bundle cannot assume that another bundle has been started. So, if your bundle needs access to other bundles or services (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 service is available - see WindowActivator for an example.
• In the IGB source code repository, in the plugins/ directory, you will find several embedded bundles that IGB uses. You can look through these to help you understand bundles.

Sample plug-in

1. To create our plugin, we will create three files, the MANIFEST.MF file, an activator (OSGi term), and a transformer (IGB term).
2. We will create a bundle that adds a new graph function.
3. Create the following MANIFEST.MF file:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: MyTransformer
Bundle-SymbolicName: MyTransformer
Bundle-Version: 1.0.0
Bundle-Activator: mypackage.MyActivator
Import-Package: com.affymetrix.genometryImpl.util,
 org.osgi.framework

Note: There are spaces at the beginning of the extension lines, and a blank line at the end)

1. Now, create the Activator, mypackage.MyActivator.java

package mypackage;
import java.util.Properties;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
import com.affymetrix.genometryImpl.util.FloatTransformer;

public class MyActivator implements BundleActivator {
    private BundleContext bundleContext;
    private ServiceRegistration serviceRegistration;
    protected BundleContext getContext() {
        return bundleContext;
    }
    public void start(BundleContext _bundleContext) throws Exception {
        bundleContext = _bundleContext;
        serviceRegistration =
            bundleContext.registerService(FloatTransformer.class.getName(),
            new MyTransformer(), new Properties());
    }
    public void stop(BundleContext _bundleContext) throws Exception {
        if (serviceRegistration != null) {
            serviceRegistration.unregister();
        }
        bundleContext = null;
    }
}

1. And create the Transformer, mypackage.MyTransformer.java

package mypackage;
import com.affymetrix.genometryImpl.util.FloatTransformer;
public class MyTransformer implements FloatTransformer {
    final String paramPrompt;
    final String name;
    public MyTransformer() {
        super();
        paramPrompt = null;
        name = "MyTransformer";
    }
    public String getParamPrompt() { return null; }
    public String getName() {
        return name;
    }
    public String getDisplay() {
        return name;
    }
    public float transform(float x) {
        return x; // boring, put your own math function here, return 1.0/x; or return 3*x*x*x - 2*x*x +8*x - 6;
    }
    public boolean setParameter(String s) {
        return true;
    }
}

1. Now, compile and jar these files into MyTransformer.jar (the jar command has a -m option for the manifest file).
2. At this point, you want to put your jar into a web server using OBR (see above).
   • To add the plugin to a web server without OBR, in the plugins directory, from the command line run
   • java -cp IGB_HOME/igb_server/lib/bindex.jar -jar bindex.jar -n IGB -q -r repository.xml .
   • where IGB_HOME is your checked-out copy of the genoviz-trunk repository from Sourceforge.net. 
3. this will create a repository.xml file listing all the bundles and their requirements.
4. make sure the repository.xml file and the bundles directory are accessible to the web server.
5. in IGB, open the File>Preferences page, Plugin Repositories tab
6. click the Add ... button at the bottom
7. enter the web server URL for the directory that has the repositories.xml file that you created - you can use whatever you want for the name.
8. Click the "Add Server" button
9. close the Preferences page.
10. Open the Plugins tab
11. you should see your bundle in the table, click on the install checkbox.
12. Once you have installed your bundle, select a graph track on the main view, and open the Graph Adjuster tab. Now if you click on the Transformation drop down, you will see MyTransformer in the list. Select it and click the Go button, and you will see a new track using your bundle.

To create plug-ins using Eclipse

See the Quick-Start Guide.

To create plug-ins using NetBeans

See the Quick-Start Guide.

Including a Bundle in the IGB Distribution

Some bundles are included in the normal IGB distribution. Above we discussed how to build an "external" bundle for use with IGB. Here are the additional things you need to do to include a bundle with IGB. Such bundles are sometimes referred to as "internal".

...

needs to include the standard OSGi headers, which you should not have to manually add. You should use the BND tool to create these. Of these, two are specifically required by IGB to install and manage Apps. These are:

• Bundle-SymbolicName - used by IGB to uniquely identify an App and its various versions, e.g., "super-simple-igb-app." Users typcally do not see this name; however, App Store uses this to form URLs to App-specific pages, e.g., https://apps.bioviz.org/apps/org.lorainelab.igb.protannot
• Bundle-Version - used by IGB to distinguish different versions, called "releases", of the same App, e.g., "0.0.1." An App's version should always look like x.y.z, where x, y, and z are non-negative integers. It is important to not include suffix tags so that IGB can distinguish higher from lower versions of the same App. 

IGB also recognizes and uses two optional MANIFEST.MF headers. These are:

• Bundle-Name - a user-facing, display name for an App, e.g., "Super Simple IGB App." This appears in App Manager and also on IGB App Store pages. 
• Bundle-Description - base64-encoded markdown text describing the App. IGB App Manager and IGB App Store pages display the decoded, rendered Markdown to users. We provide a maven plugin (bundle-markdown-encoder) for developers to include this header in their bundle's MANIFEST.MF file.