Differences between revisions 27 and 30 (spanning 3 versions)
← Revision 27 as of 2008-08-18 20:06:19 →
Size: 11666
Editor: KeiichiroOno
Comment:
← Revision 30 as of 2008-09-04 22:24:49 →
Size: 11831
Editor: cosiapat1
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
Line 4: Line 3:
 * Document rev. 0.9 released.  Confirmed to work on Linux and Mac: KeiichiroOno
 * Document rev. 1.0 released.  Confirmed to work on Windows, Linux and Mac: KeiichiroOno [[DateTime()]]
 		 * Document rev. 0.9 released. Confirmed to work on Linux and Mac: KeiichiroOno
 * Document rev. 1.0 released. Confirmed to work on Windows, Linux and Mac: KeiichiroOno [[DateTime()]]
Line 10: Line 8:
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.  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.
Line 13: Line 11:
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. 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. ''
Line 15: Line 13:
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. 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.
Line 26: Line 24:
Line 34: Line 31:
Line 36: Line 32:
Line 40: Line 35:
Line 47: Line 41:
Other directories will be generated automatically. Your workspace will look like the following:
Line 48: Line 43:
Other directories will be generated automatically. Your workspace will look like the following:

 attachment:pluginProjectTree.png
 		 . attachment:pluginProjectTree.png
Line 55: Line 47:
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. 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.
Line 59: Line 51:
 1. Start Eclipse.  For simplicity, I recommend to use fresh and empty workspace without any other projects.  1. Start Eclipse. For simplicity, I recommend to use fresh and empty workspace without any other projects.
Line 62: Line 54:
 1. 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.  1. 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.
Line 65: Line 57:
 1. Press '''''Select...''''' and use the tree browser to expand '''''pax''''' and then choose '''''create-project''''' as the goal.
 1. 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
Line 66: Line 61:
 1. Press '''''Select...''''' and select '''''pax:create-project''''' as the goal
 1. 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
 
Line 72: Line 62:
 1. 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.  1. 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.
Line 77: Line 67:
 1. Set parameters    1. Set parameters
Line 80: Line 69:

Line 83: Line 70:
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. 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.
Line 88: Line 75:
 1. Goal should be '''''pax:create-bundle'''''
 1. 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.  Also, add '''''junit''''' parameter to automatically generate test case template.  The value should be the version of JUnit you want to use. 		 1. Set the goal to '''''create-bundle''''' under the '''''pax''''' entry in the tree browser.
 1. 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. Also, add '''''junit''''' parameter to automatically generate test case template. The value should be the version of JUnit you want to use.
Line 93: Line 80:
 1. Press '''''Apply''''' and '''''Run'''''
 1. Next, you need to add OSGi project nature to your workspace.  Select '''''Run > Run Configurations...''''' 		 1. Press '''''Apply''' and '''''Run''''' ''
 1. Next, you need to add OSGi project nature to your workspace. Select '''''Run > Run Configurations...'''''
Line 98: Line 85:
Line 101: Line 87:
 1. Press '''''Apply''''' and '''''Run'''''
 1. Import the generated bundle into your workspace.  It is same as part 1.  Now your workspace looks like the following:
 		 1. Press '''''Apply''' and '''''Run''''' ''
 1. Import the generated bundle into your workspace. It is same as part 1. Now your workspace looks like the following:
Line 105: Line 90:
Line 107: Line 91:
Line 112: Line 95:
   * ''src/main'' - Main source code directory you are going to write your own plugin code.
    * ''src/test'' - For unit/integration test cases 		  * ''src/main'' - Main source code directory you are going to write your own plugin code.
  * ''src/test'' - For unit/integration test cases
Line 115: Line 98:
 * MANIFEST.MF - Metadata for OSGi bundle.  The most important part is the section '''''Export-Package''''' and '''''Import-Package''''' which describes what packages are exported/imported.
 * osgi.bnd - This is the setting file for [http://felix.apache.org/site/maven-bundle-plugin-bnd.html maven-bundle-plugin].  Instead of editing ''MANIFEST-MF'' directly, we are going to use the plugin to generate manifest file (metadata for OSGi bundle).  For now, I'm not going into the detail about how to edit this file. 		 * MANIFEST.MF - Metadata for OSGi bundle. The most important part is the section '''''Export-Package''' and '''''Import-Package''''' which describes what packages are exported/imported. ''
 * osgi.bnd - This is the setting file for [http://felix.apache.org/site/maven-bundle-plugin-bnd.html maven-bundle-plugin]. Instead of editing ''MANIFEST-MF'' directly, we are going to use the plugin to generate manifest file (metadata for OSGi bundle). For now, I'm not going into the detail about how to edit this file.
Line 118: Line 101:
Line 121: Line 103:
Line 124: Line 107:
 1. Open plugin root pom.xml file and paste the dependency    1. Open plugin root pom.xml file and paste the dependency
Line 127: Line 109:
Line 129: Line 110:
 1. Create new Maven Run target.  Base directory is your plugin root (see the screenshot below)
 		 1. Create new Maven Run target. Base directory is your plugin root (see the screenshot below)
Line 133: Line 113:
 1. Apply and Run.  You can see Cytoscape 3 and your new plugin are running together on the same OSGi framework.
 		 1. Apply and Run. You can see Cytoscape 3 and your new plugin are running together on the same OSGi framework.
Line 136: Line 115:
Line 138: Line 116:
Line 142: Line 119:
Line 144: Line 120:
Now you are ready to write your own code.  Let's add a very simple code to the template. Now you are ready to write your own code. Let's add a very simple code to the template.
Line 148: Line 124:
{{{#!java
 public void start(BundleContext bc) throws Exception {
  System.out.println("STARTING org.cytoscape.sample"); 		{{{
#!java
        public void start(BundleContext bc) throws Exception {
                System.out.println("STARTING org.cytoscape.sample");
Line 152: Line 129:
  Dictionary props = new Properties();
  // add specific service properties here... 		                Dictionary props = new Properties();
                // add specific service properties here...
Line 155: Line 132:
  System.out.println("REGISTER org.cytoscape.sample.ExampleService");                 System.out.println("REGISTER org.cytoscape.sample.ExampleService");
Line 157: Line 134:
  // Register our example service implementation in the OSGi service
  // registry
  bc.registerService(ExampleService.class.getName(),
    new ExampleServiceImpl(), props);
     JOptionPane.showMessageDialog(null, "Hello Cytoscape 3!",
    "Plugin Initialized", JOptionPane.INFORMATION_MESSAGE);
 } 		                // Register our example service implementation in the OSGi service
                // registry
                bc.registerService(ExampleService.class.getName(),
                                new ExampleServiceImpl(), props);

                JOptionPane.showMessageDialog(null, "Hello Cytoscape 3!",
                                "Plugin Initialized", JOptionPane.INFORMATION_MESSAGE);
        }
Line 167: Line 144:
 
Line 169: Line 145:
 1. Add a brakepoint to your plugin code.  As an example, add it in the new line you have just added to the template
 		 1. Add a brakepoint to your plugin code. As an example, add it in the new line you have just added to the template
Line 173: Line 148:
 1. Create a new debug configuration.  Select '''''Run > Debug Configurations''''' and create new OSGi configuration.
 1. In the ''Bundles'' tab, uncheck all bundles.  Then select '''''Felix 1.0.4 via PAX Runner''''' for Framework
 		 1. Create a new debug configuration. Select '''''Run > Debug Configurations''''' and create new OSGi configuration.
 1. In the ''Bundles'' tab, uncheck all bundles. Then select '''''Felix 1.0.4 via PAX Runner''''' for Framework
Line 182: Line 156:
Line 185: Line 158:
 1. In the ''PAX Cursor'' tab, press ''Add POM'' and select '''''deploy-pom.xml''''' under '''''PLUGIN_PROJECT_ROOT/runner''''' directory where PLUGIN_PROJECT_ROOT is your plugin project's root directory.  You need to select ''Any File'' to make deploy-pom.xml be displayed.  1. In the ''PAX Cursor'' tab, press ''Add POM'' and select '''''deploy-pom.xml''' under '''''PLUGIN_PROJECT_ROOT/runner''''' directory where PLUGIN_PROJECT_ROOT is your plugin project's root directory. You need to select ''Any File'' to make deploy-pom.xml be displayed. ''
Line 187: Line 160:
Line 190: Line 162:
 1. '''''Apply''''' and '''''Debug'''''.  PAX Runner executes Cytoscape 3 and your plugin.  It will stop at the break point.
 		 1. '''''Apply''' and '''''Debug'''''. PAX Runner executes Cytoscape 3 and your plugin. It will stop at the break point. ''
Line 194: Line 165:
 1. Press ''resume'' button and continue.  Eventually, you will see the following dialog on the Cytoscape Desktop:
 		 1. Press ''resume'' button and continue. Eventually, you will see the following dialog on the Cytoscape Desktop:
Line 197: Line 167:
Line 199: Line 168:
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. 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.
Line 202: Line 171:
There is an Eclipse plugin for editing Spring configuration files.  You can use this for your Spring-OSGi Cytoscape plugin project. There is an Eclipse plugin for editing Spring configuration files. You can use this for your Spring-OSGi Cytoscape plugin project.
Line 204: Line 173:
Note: although this program is called ''Spring IDE,'' it is not an independent application.  It is just a regular Eclipse plugin. Note: although this program is called ''Spring IDE,'' it is not an independent application. It is just a regular Eclipse plugin.
Line 212: Line 181:
 1. Add one more parameter when you create bundle. When you create a plugin bundle, add '''''spring''''' as an extra parameter. Then PAX Construct automatically generates template bundle project ready for writing Spring-DM code.
Line 214: Line 182:
 1. Add one more parameter when you create bundle. When you create a plugin bundle, add '''''spring''''' as an extra parameter. Then PAX Construct automatically generates template bundle project ready for writing Spring-DM code.
Line 215: Line 184:
Line 218: Line 186:
 1. Set PAX Cursor profile to '''''spring'''''. All you have to do is just check the '''''spring''''' checkbox on the Pax Cursor tab.  1. Set PAX Cursor profile to '''''spring'''. All you have to do is just check the '''''spring''''' checkbox on the Pax Cursor tab. ''
 attachment:spring2.png
That's it. While your plugin is running with PAX Cursor, type ''ps'' in the console. You can see Spring-DM infrastructure bundles are running with Cytoscape 3.
Line 220: Line 190:
 attachment:spring2.png

That's it. While your plugin is running with PAX Cursor, type ''ps'' in the console. You can see Spring-DM infrastructure bundles are running with Cytoscape 3.

 attachment:spring3.png
 		 . attachment:spring3.png
Line 227: Line 192:
 

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

Status

  • Document rev. 0.9 released. Confirmed to work on Linux and Mac: KeiichiroOno

  • Document rev. 1.0 released. Confirmed to work on Windows, Linux and Mac: 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:

Eclipse Plugins

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 use the tree browser to expand pax and then choose 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. Set the goal to create-bundle under the pax entry in the tree browser.

  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. Also, add junit parameter to automatically generate test case template. The value should be the version of JUnit you want to use. attachment:pluginProject5.png

  6. Press Apply and Run

  7. Next, you need to add OSGi project nature to your workspace. Select Run > Run Configurations...

  8. Right click Maven Build and create new configuration

  9. Browse Workspace and select your project root directory

  10. Goal should be pax:eclipse attachment:pluginProject6.png

  11. Press Apply and Run

  12. Import the generated bundle into your workspace. It is same as part 1. Now your workspace looks like the following: attachment:pluginProject7.png

    The samplebundle folder is the actual project you are going to write your plugin.

OSGi Project Directory Structure

In the samplebundle directory, you may see some new files you are not familier with.

  • Source Code - In Maven projects, source code is managed in two directories.

    • src/main - Main source code directory you are going to write your own plugin code.

    • src/test - For unit/integration test cases

  • Resource Files - If you need to include some resource files (image icons, etc.) you can put them under src/resources.

  • MANIFEST.MF - Metadata for OSGi bundle. The most important part is the section Export-Package and Import-Package which describes what packages are exported/imported.

  • osgi.bnd - This is the setting file for [http://felix.apache.org/site/maven-bundle-plugin-bnd.html maven-bundle-plugin]. Instead of editing MANIFEST-MF directly, we are going to use the plugin to generate manifest file (metadata for OSGi bundle). For now, I'm not going into the detail about how to edit this file.

  • pom.xml - Setting file for Maven.

Part 3: Add Cytoscape Application Dependency

To run your plugin with Cytoscape 3 core distribution, you need to add all of its bundles to plugin pom.xml file.

  1. Assume you have already checked out Cytoscape 3 and run it by pax:provision goal

  2. Open CYTOSCAPE3_ROOT/runner/deploy-pom.xml where CYTOSCAPE3_ROOT is the root directory of Cytoscape 3 project

  3. Copy entire dependencies section from the xml file

  4. Open plugin root pom.xml file and paste the dependency attachment:pluginProject8.png

Part 4: Run Template Project with Cytoscape

  1. Create new Maven Run target. Base directory is your plugin root (see the screenshot below) attachment:pluginProject9.png
  2. Apply and Run. You can see Cytoscape 3 and your new plugin are running together on the same OSGi framework. attachment:pluginProject10.png

    If you type services, you can see example OSGi service which is defined in the template code is running. attachment:pluginProject11.png

  3. Quit Cytoscape

Part 5: Edit Template Code

Now you are ready to write your own code. Let's add a very simple code to the template.

  1. Open samplebundle > src/main/java > org.cytoscape.sample.internal > ExampleActivator.java

  2. Edit the following method and save it 

   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

  1. Right-click the root dir of the project (in this example, it is c3plugin) and execute Run As > Maven install

Part 6: Debug your Plugin

  1. Add a brakepoint to your plugin code. As an example, add it in the new line you have just added to the template attachment:pluginProject12.png

  2. Create a new debug configuration. Select Run > Debug Configurations and create new OSGi configuration.

  3. In the Bundles tab, uncheck all bundles. Then select Felix 1.0.4 via PAX Runner for Framework attachment:pluginProject13.png

  4. In the Arguments tab, add following as VM arguments 

    -Xbootclasspath/a:bundles/com.jgoodies.looks_2.1.2.jar:bundles/cytoscape-sun.jhall_1.0.0.jar
    attachment:pluginProject14.png

  5. In the PAX Cursor tab, press Add POM and select deploy-pom.xml under PLUGIN_PROJECT_ROOT/runner directory where PLUGIN_PROJECT_ROOT is your plugin project's root directory. You need to select Any File to make deploy-pom.xml be displayed.

  6. Set update to yes attachment:pluginProject15.png

  7. Apply and Debug. PAX Runner executes Cytoscape 3 and your plugin. It will stop at the break point. attachment:pluginProject16.png

  8. Press resume button and continue. Eventually, you will see the following dialog on the Cytoscape Desktop: attachment:pluginProject17.png

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

There are only two differences between OSGi-dependent plugins and Spring-DM plugins:

  1. Add one more parameter when you create bundle. When you create a plugin bundle, add spring as an extra parameter. Then PAX Construct automatically generates template bundle project ready for writing Spring-DM code. attachment:spring1.png attachment:spring12.png

  2. Set PAX Cursor profile to spring. All you have to do is just check the spring checkbox on the Pax Cursor tab. attachment:spring2.png

That's it. While your plugin is running with PAX Cursor, type ps in the console. You can see Spring-DM infrastructure bundles are running with Cytoscape 3.

  • attachment:spring3.png

More advanced tutorial including how to write Spring-DM setting files will be available soon.

Outdated_Cytoscape_3.0/Eclipse/PluginDevelopment (last edited 2011-02-24 15:36:04 by PietMolenaar)

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux