Running and Developing Cytoscape 3 on Eclipse

Introduction

This is a tutorial document to learn how to run and develop Cytoscape 3 with Eclipse PDE.

Procedure

Setting Up Your Environment

To develop Cytoscape 3 on Eclipse, you need to install several software packages.

Eclipse

This tutorial is based on the latest version of Eclipse 3.4, called Ganymede. Several distributions are available on [http://www.eclipse.org/downloads/packages/ Eclipse web site]. You need to use one of the following:

Both of these distributions include PDE (Plugin Development Environment).

Subversion

Cytoscape 3 source code is managed by [http://subversion.tigris.org/ Subversion]. To access the repository, you need to install subversion client for Eclipse. In this tutorial, I'll use [http://subclipse.tigris.org/ Subclipse]. You can install the plugin from the eclipse's update manager. Do not forget to install SVNKit. Otherwise, you will get an error message when you try to check out repository ("Unable to load default SVN Client")

Repository locations are the following:

You need to checkout the trunk directory.

Maven and Maven Integration for Eclipse

Cytoscape build system has been moved to Maven. To use maven on Eclipse, you need to follow [:MavenInfo:this] instruction.

Now your Eclipse is ready for Cytoscape 3 development!

My Testing Environment

I tested the following tutorial in the following environment:

Checkout and Create Cytoscape 3 Eclipse Project

In this section, you will learn how to create an Eclipse project from the fresh Cytoscape 3 checkout.

  1. Start Eclipse

  2. Checkout Cytoscape 3 from the current SVN trunk. Set project type to Java Project and name the project (in this example, I'll use C3 as project name).

  3. Quit Eclipse

  4. From terminal, run mvn clean install pax:eclipse. This command automatically generates Eclipse project files. This process takes about 10 minutes to complete.

  5. Start Eclipse again

  6. Select File → Import and import as Maven Project

    • attachment:eclipse_core1.png

  7. Select all pom files and press Finish. Your Eclipse workspace looks like the following image

    • attachment:eclipse_core2.png

Run Cytoscape 3 on Eclipse

Eclipse is running on an OSGi implementation called [http://www.eclipse.org/equinox/ Equinox]. Since Cytoscape 3 is following OSGi standard, (theoritically) you can run it on any OSGi environments. In this example, you will run Cytoscape 3 using Equinox.

  1. From Eclipse main window, select Run → Run Configurations

  2. Right click on OSGi Framework and select New

    • attachment:eclipse_core3.png

  3. Name the configuration Cytoscape 3

  4. By default, every bundle available in current Equinox environment is selected. Uncheck Target Platform bundles. At this point, only Cytoscape 3 bundles are selected.

  5. Press Add Required Bundles button. This function automatically select required (infrastructure) bundles to run Cytoscape 3 bundles under Workspace

    • attachment:eclipse_core4.png

  6. Press Run. After few moments, Cytoscape Desktop appears. In the console window, you can see the messages to standard output

    • attachment:eclipse_c3main.png attachment:eclipse_core5.png
    You may see several error messages or exceptions, but it is normal because current Cytoscape 3 trunk is not fully working version of Cytoscape.

  7. On the Console, hit enter. Then you will see the Equinox's command prompt 

    osgi>

  8. Type ss. This command displays current status of bundles running on Equinox. 

    osgi> ss

Framework is launched.

id      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.4.0.v20080605-1900
                    Fragments=48
1       ACTIVE      com.sun.xml.bind.jaxb-xjc_2.0.0
2       ACTIVE      csplugins.quickfind_1.0.0.SNAPSHOT
3       ACTIVE      phoebe.dnd_1.0.0.SNAPSHOT
4       ACTIVE      org.freehep.swing_2.0.2
5       ACTIVE      org.eclipse.datatools.modelbase.sql.query_1.0.1.v200805152355
6       ACTIVE      net.sourceforge.lpg.lpgjavaruntime_1.1.0.v200803061910
7       ACTIVE      cytoscape.graph.dynamic_1.0.0.SNAPSHOT
8       RESOLVED    org.eclipse.core.runtime.compatibility.registry_3.2.200.v20080610
                    Master=31
9       ACTIVE      cytoscape.graph.fixed_1.0.0.SNAPSHOT
10      ACTIVE      cytoscape-temp.sbml2_1.0.0
11      ACTIVE      cytoscape.geom.rtree_1.0.0.SNAPSHOT
12      RESOLVED    org.eclipse.core.resources.compatibility_3.4.0.v20080604-1400
                    Master=77
13      ACTIVE      org.eclipse.ant.core_3.2.0.v20080529
 .
 .
 .

  9. Type help. You will see help messages for Equinox shell commands. You can play with them by typing commands in the console. 

    osgi> help

---Application Admin Commands---
        activeApps - lists all running application IDs
        apps - lists all installed application IDs
        lockApp <application id> - locks the specified application ID
        schedApp <application id> <time filter> [true|false] - schedules the specified application id to launch at the specified time filter.  Can optionally make the schedule recurring.
        startApp <application id> - starts the specified application ID
        stopApp <application id> - stops the specified running application ID
        unlockApp <application id> - unlocks the specified application ID
        unschedApp <application id> - unschedules all scheduled applications with the specified application ID
---Extension Registry Commands---
        ns [-v] [name] - display extension points in the namespace; add -v to display extensions
        pt [-v] uniqueExtensionPointId - display the extension point and extensions; add -v to display config elements---Eclipse Runtime commands---
        diag - Displays unsatisfied constraints for the specified bundle(s).
        enableBundle - enable the specified bundle(s)
        disableBundle - disable the specified bundle(s)
        disabledBundles - list disabled bundles in the system
---Controlling the OSGi framework---
        launch - start the OSGi Framework
        shutdown - shutdown the OSGi Framework
        close - shutdown and exit
        exit - exit immediately (System.exit)
        init - uninstall all bundles

  10. To stop, type exit

Note: The behaviour of Cytoscpae 3 running on Equinox will be different from time to time. This is because budle loading timing is not properly controlled now. This will be solved by organizing bundle/service dependency. I'm working on this issue now and hopefully it will be solved soon.

Develop Cytoscape 3 Code on Eclipse PDE

Now you are ready to hack Cytoscape 3 on Eclipse. As you can see on your workspace, Cytoscape 3 is a collection of OSGi bundles. Each bundle is build as a Maven project and has a pom.xml file.

Debugging Cytoscape 3 Code with Eclipse Debugger

Essentially, there is no difference between regular Java program debugging and OSGi system debugging. Eclipse built-in OSGi environment is integrated to other part of Eclipse, and you can use

(Under construction)

This document is written by Keiichiro Ono

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