Writing your first perspective

Background

The workbench is currently built up around the idea of Perspectives, Views (or ViewParts) and Actions. A perspective can be thought of a page and can contain many views and actions that combine to give functionality for a common task. A view is one of the happy little windows that appears on the workbench. It contains UI controls that allows the user to perform tasks and to interact with the workbench. An Action is something that sits in the Tool bar of either the workbench or a view. When developing for the workbench, you don't have access to the workbench itself to reconfigure it - this must be done via perspectives, actions and views.

The IPerspectiveFactory Interface

IPerspectiveFactory (part of the org.karora.moomba.ui package) is a very simple interface to work with. If you are familiar at all with the Eclipse APIs then you will find this, and most of the workbench APIs follow much the same format. This interface consists of four essentially self explanitory methods:

public interface IPerspectiveFactory
{
   public String getId();
   public String getText();
   public HttpImageReference getImage();
   public Component createInitialLayout(IPageLayout layout);
}

getId - Must return a unique Id for this perspective. Note: IT MUST BE UNIQUE. All workbench parts must have an Id. The recommended standard for this is the fully qualified class name, i.e. my.package.MyClass. It is also highly recommended that each Workbench Part declares a public final static string variable called ID which defines this unique id.

getText - Should return a name for the perspective. This does not need to be unique, but should be a user readable name as it may appear in the user interface.

getImageReference - Returns a reference to a Cooee image should this perspective have an image associated with it. If the perspective has no image then null may be returned.

createInitialLayout - Is the key method. This method allows you to add views and actions to the page layout using the IPageLayout interface.

Writing a hello world perspective

Create an OSGi plug-in project

Use the "New Project" wizard to create a project. Follow the following screen-shots very closely.

Creating a Maven project

You will need a pom.xml file in the root directory of your project. The file should read something like the following.

<project>
      <modelVersion>4.0.0</modelVersion>
      <groupId>com.myproject.rox</groupId>
      <artifactId>MyPluginProject</artifactId>
      <packaging>osgi-bundle</packaging>
      <version>1.0-SNAPSHOT</version>
      <name>${artifactId}</name>
      <dependencies>
         <dependency>
            <groupId>org.karora</groupId>
            <artifactId>moomba</artifactId>
            <version>0.0.1-SNAPSHOT</version>
            <scope>provided</scope>
         </dependency>

         <dependency>
            <groupId>org.karora</groupId>
            <artifactId>cooee</artifactId>
            <version>0.2-SNAPSHOT</version>
            <scope>provided</scope>
         </dependency>
   </project>

Enable Maven in your Eclipse project.

Create a perspective factory class

• Create a new class that implements IPerspectiveFactory. Let's stick with convention and call it HelloWorldPerspective
• Complete the methods getId(), getTest(), and getImageReference

In createInitialLayout you would add your views and actions, but because we don't have any we can't do this. We will be adding a view to the perspective in the next tutorial.

Spring/OSGi configuration files

There are three configuration files required to create this plug-in.

• MANIFEST.MF (Plug-in manifest)
• bundle-context.xml (Spring)
• bundle-context-osgi.xml (Spring/OSGi)

MANIFEST.MF

This declares the imports the plug-in requires

yet-to-be-completed

bundle-context.xml (Create this under src/main/META-INF/spring)

This declares the perspective class as a bean

<?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
  <beans>
    <!-- regular spring configuration file defining the beans for this
         bundle. We've kept the osgi definitions in a separate
         configuration file so that this file can easily be used
         for integration testing outside of an OSGi environment -->
    <bean name="helloworld.HelloWorldPerspective" class="helloworld.HelloWorldPerspective" singleton="false"/>
  </beans>

bundle-context-osgi.xml (Create this under src/main/META-INF/spring)

This declares the bean as an OSGi service

<?xml version="1.0" encoding="UTF-8"?>
  <beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:osgi="http://www.springframework.org/schema/osgi"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                        http://www.springframework.org/schema/osgi http://www.springframework.org/schema/osgi/spring-osgi.xsd">
    <osgi:service id="helloworld.HelloWorldPerspectiveOsgi" ref="helloworld.HelloWorldPerspective" interface="org.karora.moomba.ui.IPerspectiveFactory" lazy-init="false"/>
  </beans>

Compile, Install, and Run

Build your project.

mvn clean package

Install your built jar into your Equinox Runtime and refresh the project.

Important: If this is the first time you have done this then you will also need to install the cooee_osgi bundle, the UI workbench bundle, and the UI Resource bundle into the Equinox Runtime. These can be found in your Maven repository.

Right click on your Equinox Runtime project, and select "Run On Server". Run it on Tomcat.
Once the server is up, type ss in the console to show all installed bundles and you should see both the Workbench and the HelloWorld Perspective bundles.

Start the Spring framework OSGi bundle, the OSGi extender bundle and both the Workbench and Hello World Perspective bundles.
Then go to the following url
http://localhost:8080/EquinoxRuntime/Workbench

You should now see your perspective.