Bundles and Plug-Ins

under construction

Introduction

Explain:

• What is a bundle? Give an example.
• What is OSGi and how does it work?
  • Explain what an Activator is.
• Provide references to tutorials developers new to the concept of bundles can read to get familiar with the topic.
• Explain the concept of extension point.
• Explain the advantages of bundles, plug-ins. (Ann can write this part after talking more with Michael and Lance.)

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:

Ann's note: the formatting below is weird. Did you copy and paste from an email message?

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 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.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. Ann's note: manifest.mf of what?
• If you want to add a tab window (Ann's note: Do you mean panel or window, because they can be opened as new windows?) 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. (Ann's note: Please explain more) 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.

To create plug-ins using eclipse - a Quick-Start Guide

Eclipse (http://www.eclipse.org) 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
(using eclipse Helios)

1. check out IGB from https://genoviz.svn.sourceforge.net/svnroot/genoviz/trunk
     into a new project in eclipse
2. make a new IGB_HOME environment variable to point to the IGB project (Ann's Note: What directory should it point to in the checked out code - maybe give an example?)
3. open a command prompt in IGB_HOME, and do an "ant clean" and "ant jar"
4. in eclipse, project explorer, right click the IGB project and select "refresh"
5. 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
6. 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"

Ann's note: Please add a tutorial explaining how to develop a simple plug-in. Your graph plug-in is probably a good place to start. We need a very simple but cool example that relies on a stable part of the API so that the tutorial doesn't get out of date.)

Sample plug-in using eclipse

 In the Project Explorer - blank area, right-click
 New > Project ... > Plug-in Project > "Next >" button
 Project name: "HelloWorld" > "Next >" button
 Version: "1.0.0" check "Generate an activator ...",
   Activator "helloworld.Activator", Rich Client Application click "No",
   "Next >" button
 Uncheck "Create a plug-in using one of the templates", "Finish" button
 Under the new HelloWorld project, find the META-INF directory, and open
   the MANIFEST.MF file by double-clicking on it.
 Click on the "Dependencies" tab,
   in the "Required Plug-ins" box, 
   highlight org.eclipse.core.runtime, and click the "Remove" button on the right.
   next to the "Imported Packages" box, click the "Add..." button, int
   the "Package Selection" popup in the text box, enter "com.affymetrix.genoviz.util"
   and click the "OK" button. Do the same for "org.osgi.framework" (there may be
   a version number in parentheses after the name).
   Right click on the blank area at the top, next to "Dependencies" and
   a context menu comes up, click "Save".
 Open the Activator.java file under src/helloworld, add the import statement
   import com.affymetrix.genoviz.util.ErrorHandler;
   at the top, and add the line
   ErrorHandler.errorPanel("Hello World");
   at the end of the start() method, and
   ErrorHandler.errorPanel("Goodbye World");
   at the end of the stop method
   Save the file
 In the Project Explorer, Right click the HelloWorld project, > "Export ..."
   "Deployable plug-ins and fragments", "Next >" button,Under "Available Plug-ins and Fragments:", check only
   Hello World, "Directory:" use any directory you like. click the "Finish" button.
   The HelloWorld_1.0.0.jar file will be in the plugins directory under the directory the you specified. This is your bundle
 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 IGB directory.
 Now, if you can access your plugins directory from a local web server, you can open up the Plug ins tab
   in IGB, and click on the "Repositories..." button on the lower right. Click the "Add..." button, and put the
   URL for your local plugin directory. Click the "Add Server" button, then close the Preferences popup. Now,
   uncheck and recheck the "Show Uninstalled" checkbox at the bottom of the Plug ins tab. You should now
   see your Hello World plugin. If you install the plugin you will see an Error popup "Hello World". When you uninstall
   the plugin, you will see an Error popup "Goodbye World". Congratulations!

To create plug-ins using NetBeans - a Quick-Start Guide

Is this possible? Easy?