How to Build an OSGi-Based Cytoscape 3 Plugin on Eclipse

Status

• Under construction. Need to add section how to use maven archetype for Cytoscape 3: KeiichiroOno DateTime()

TableOfContents()

Introduction

This tutorial is a step-by-step instruction for creating Cytoscape 3 plugin based on OSGi framework. By following this tutorial, you can create a new plugin for Cytoscape 3.

Background

In an OSGi system, everything is a plugin. This means, Cytoscape 3 running on OSGi framework is a collection of plugins called bundle and developing a plugin for Cytoscape 3 is equivalent to developing OSGi bundles.

The main difference between Cytoscape 2.x plugin and 3.x plugin is that you do not have to implement CytoscapePlugin interface in Cytoscape 3. Instead, you need to build your plugin jar file with metadata for OSGi. However, this process will be handled by Eclipse and other tools and you do not have to create metadata manually.

Requirements

To understand each steps in this document, it is better to understand following before building your plugin:

• Basic Java
• How to build Java project on Eclipse
• OSGi Bundle
  • Note: OSGi Bundle = regular jar file + metadata text file.
• OSGi-Dependent API

  • BundleActivator

Tools

The following tools should be installed on your machine before starting this tutorial:

• [http://www.eclipse.org/ Eclipse 3.3/3.4]

• [http://maven.apache.org/ Maven] 2.0.9 or later

• [http://www.ops4j.org/projects/pax/construct/ Pax-Construct 1.3]

• [http://java.sun.com/javase/downloads/index_jdk5.jsp Java SE 5/6]

Eclipse Plugins

• [http://m2eclipse.codehaus.org/ m2Eclipse] - Maven integration for Eclipse

• [http://subclipse.tigris.org/ Subclipse] - [http://subversion.tigris.org/ Subversion] client for Eclipse

• [http://springide.org/blog/ Spring IDE] (Optional)

Goal of This Tutorial

There are lots of ways to organize your plugin project directory, but in this tutorial, for simplicity, we will use the following directory structure:

• Plugin Project Root - The root directory of your plugin project.
  • Plugin Bundle Directory - This is the actual directory to store plugin code.

  • wrappers - Wrapping existing library files as OSGi bundles if they are not available as OSGi bundles

Other directories will be generated automatically. Your workspace will look like the following:

• attachment:pluginProjectTree.png

In the example above, samplePluginA is the name of plugin project and plugin1 is the name of plugin bundle.

Prerequisite

Since this project depends on Cytoscape 3 core, you need to know how to build and run Cytoscape 3 on Eclipse. Please read [:Cytoscape 3.0/Eclipse/CoreDevelopment:this tutorial] first.

Procedure

Part 1: Create New Plugin Project

1. Start Eclipse. For simplicity, I recommend to use fresh and empty workspace without any other projects.

2. Select Run > Run Configurations...

3. Right click Maven Build and create new configuration

4. Press Variables... and select workspace_loc as the destination directory for the new plugin project. However, the location is up to you. You can select any directory. attachment:pluginProject1.png

5. Press Select... and select pax:create-project as the goal

6. Press Add and set artifactId and groupId. Usually, groupId is based on your organization's URL. This is because once you publish your plugin in the Maven repository, the string groupId+artifactId must be unique to locate your project attachment:pluginProject2.png

7. Press Apply and Run.

8. At this point, there is no new project in your workspace. This is normal since the process above only creates Maven project, not an Eclipse project.

9. Open File > Import window and select Maven Projects attachment:pluginProject3.png

10. Set parameters attachment:pluginProject4.png

Part 2: Create Plugin Bundle

Next, you need to create an actual OSGi bundle of your plugin. You can create multiple bundles for a plugin, but in this tutorial, your plugin consists of one bundle.

1. Select Run > Run Configurations...

2. Right click Maven Build and create new configuration

3. Browse Workspace and select your project root directory

4. Goal should be pax:create-bundle

5. Add two parameters for the new plugin. Package will be the root package name of this bundle, and bundleName will be the name of your new plugin. attachment:pluginProject5.png

6. Press Apply and Run

7. Import the generated bundle into your workspace. It is same as part 1. attachment:pluginProject6.png attachment:pluginProject7.png

Part 3: Add Cytoscape Application Dependency

Part 4: Edit Template Code

   1         public void start(BundleContext bc) throws Exception {
   2                 System.out.println("STARTING org.cytoscape.sample");
   3 
   4                 Dictionary props = new Properties();
   5                 // add specific service properties here...
   6 
   7                 System.out.println("REGISTER org.cytoscape.sample.ExampleService");
   8 
   9                 // Register our example service implementation in the OSGi service
  10                 // registry
  11                 bc.registerService(ExampleService.class.getName(),
  12                                 new ExampleServiceImpl(), props);
  13                 
  14                 JOptionPane.showMessageDialog(null, "Hello Cytoscape 3!",
  15                                 "Plugin Initialized", JOptionPane.INFORMATION_MESSAGE);
  16         }
  17 

Part 4: Run Plugin

Use Spring Dynamic Modules for Your Plugin

If you want to use OSGi service mechanism, using Spring Framework is a good alternative to use OSGi-dependent API directly. In this section, you will learn how to create Spring-Powered bundles for your plugins.

Install Spring IDE

There is an Eclipse plugin for editing Spring configuration files. You can use this for your Spring-OSGi Cytoscape plugin project.

Note: although this program is called Spring IDE, it is not an independent application. It is just a regular Eclipse plugin.

You can follow this instruction to install it:

http://springide.org/project/wiki/SpringideInstall

Create Spring-Powered Bundle

=== Setup Spring-DM

(Under construction!)