Tutorial:Creating an OSGi Bundle Cytoscape 3 App

From OpenTutorials
Jump to: navigation, search

Slideshow Create a Bundle App Using Command Line (about 30 minutes)


Cytoscape 3 is architecturally re-designed new version of Cytoscape. This tutorial will cover:

  1. Generating a Cytoscape 3 app project
  2. Writing the code for a functional app for Cytoscape 3
  3. Deploying of the final app into Cytoscape 3

Introduction

In this tutorial, you are going to create an OSGi Bundle style Cytoscape 3 App. To create native Cytoscape 3 app, you need to understand basics of OSGi. However, there are several tools to automate this process.

What is a Native Cytoscape 3 App?

  • Really just an OSGi bundle
    • In Cytoscape 3, there is no clear difference between core and apps. Everything is an OSGi bundle.
  • Classpath advantages
    • Minimize library version conflicts
  • Publish your own API and hide implementations
    • You have package-level access control of your classes.

Tools You Need

  • Java Development Kit (JDK) 6 or 7
  • Maven 3.x
  • Git

Create app from Maven Archetype

To create an OSGi bundle app, we can use the Cytoscape Maven archetypes. This will quickly create a Maven-based project that will build an OSGi bundle-based Cytoscape app and is easily extensible to fit your needs.

Create project from archetype

To create a project using the Cytoscape Maven archetypes, run the following command from a command line:

mvn archetype:generate -DarchetypeCatalog=http://code.cytoscape.org/nexus/service/local/repositories/releases/content/archetype-catalog.xml

This will present a menu with a list of all Cytoscape Maven archetypes:

Choose archetype:
1: http://code.cytoscape.org/nexus/service/local/repositories/releases/content/archetype-catalog.xml -> org.cytoscape.archetypes:task-app (-)
2: http://code.cytoscape.org/nexus/service/local/repositories/releases/content/archetype-catalog.xml -> org.cytoscape.archetypes:cyaction-app (-)
3: http://code.cytoscape.org/nexus/service/local/repositories/releases/content/archetype-catalog.xml -> org.cytoscape.archetypes:api-provider-app (-)
4: http://code.cytoscape.org/nexus/service/local/repositories/releases/content/archetype-catalog.xml -> cytoscape.archetypes:sample-plugin (-)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :2

We select cyaction-app - after doing so, you will then be prompted for the version of the archetype to be used:

Choose org.cytoscape.archetypes:cyaction-app version: 
1: 3.0.0
2: 3.1.0.1
Choose a number: 2: 1

We select 3.0.0 - that is generally the right choice unless you need to use features only found in later versions of the API.

After doing this, you will be prompted for additional information needed to create the project:

Define value for property 'groupId': : org.cytoscape.myapp
Define value for property 'artifactId': : my-cyaction-app
Define value for property 'version':  1.0-SNAPSHOT: : 
Define value for property 'package':  org.cytoscape.myapp: : 

Specify "org.cytoscape.myapp" for the group ID, "my-cyaction-app" for the artifact ID, and use the defaults for all other options (just press Enter). A summary of the specified options will be displayed at the end:

Confirm properties configuration:
groupId: org.cytoscape.myapp
artifactId: my-cyaction-app
version: 1.0-SNAPSHOT
package: org.cytoscape.myapp
Y: : Y

If these are correct, confirm by entering "Y" at the prompt. A basic project will be built with the options you supplied.

Compile the project

To build, type

mvn clean install

at the top level of the project. If compilation succeeded, you will see a new directory ‘target’, and can find your bundle jar there; it will be also installed in the .m2/repository directory of your home directory (i.e., your local Maven repository, following standard Maven rules).

Run Generated App

  • Copy the app JAR file (in the target directory) to the ~/CytoscapeConfiguration/3/apps/installed/ directory (under your home directory).
    • Note: If you are developing an app and will be making regular changes, it may be easier to create a symbolic link to the JAR file in ~/CytoscapeConfiguration/3/apps/installed/ instead of copying it. The advantage of this is that you won't have to copy the JAR every time you rebuild - the downside being that deleting the target directory uninstalls the JAR as well. This can be done using the mklink command (Windows) or the ln command using the -s option (Mac/Linux). Note that you may need administrative privileges to do this on Windows.
  • Run Cytoscape 3 by executing the cytoscape.sh/bat file.
  • From the command line, type 'list'. This command displays bundles running on the current OSGi runtime. Make sure your bundle is running.

Eclipse4.png

  • Type 'ls -a YOUR_BUNDLE_ID'. This indicates that your new app bundle is running and exporting an OSGi service! The template generates a very simple app template to create an instance of a class and export it as an OSGi service.
  • Click the Apps menu - note that there is a new menu item, "Hello World App".

Add Your Function

  • In this example, you are going to add the same function as in the simple Cytoscape app tutorial, i.e., to hide all unconnected (singleton) nodes in the current network view.
  • To start, you will need to add dependencies to the pom.xml file as necessary. In this example, you will need to add one new dependency - presentation-api.
<dependency>
	<groupId>org.cytoscape</groupId>
	<artifactId>presentation-api</artifactId>
	<version>3.0.0</version>
</dependency>


  • Next, edit the MenuAction class such that it looks like the following. This is the only class you need for this app.
package org.cytoscape.myapp.internal;
import java.awt.event.ActionEvent;
import org.cytoscape.application.swing.AbstractCyAction;
import org.cytoscape.application.CyApplicationManager;
import org.cytoscape.model.CyNode;
import org.cytoscape.model.CyEdge;
import org.cytoscape.model.CyNetwork;
import org.cytoscape.view.model.CyNetworkView;
import org.cytoscape.view.presentation.property.BasicVisualLexicon;

/**
 * Creates a new menu item under Apps menu section.
 *
 */
public class MenuAction extends AbstractCyAction {

	private final CyApplicationManager applicationManager;
	
	public MenuAction(final CyApplicationManager applicationManager, final String menuTitle) {
		super(menuTitle, applicationManager, null, null);
		this.applicationManager = applicationManager;
		setPreferredMenu("Apps");
	}
	
	public void actionPerformed(ActionEvent e) {

	    final CyNetworkView currentNetworkView = applicationManager.getCurrentNetworkView();
	    if (currentNetworkView == null)
	       return;
	    
	    // View is always associated with its model.
	    final CyNetwork network = currentNetworkView.getModel();
	    for (CyNode node : network.getNodeList()) {

	        if (network.getNeighborList(node,CyEdge.Type.ANY).isEmpty()) {
	        	currentNetworkView.getNodeView(node).setVisualProperty(BasicVisualLexicon.NODE_VISIBLE, false);	        	
	        }
	    }
	    currentNetworkView.updateView();
	}
	
}
  • Finally, edit the CyActivator class: replace the string "Hello World App" with "Hide unconnected nodes (OSGi bundle version)".

Try the App

  • Build again. Recopy the JAR file to ~/CytoscapeConfiguration/3/apps/installed/ directory (under your home directory) if necessary.
  • Run Cytoscape. You will see a new menu item 'Hide unconnected nodes (OSGi bundle version)' under Apps. Try to load a network and make sure this works as expected.

Eclipse12.png