Accueil > Eclipse RAP, Equinox > My first steps with Eclipse RAP [step2]

My first steps with Eclipse RAP [step2]


In [step1] we have generated our first RAP Hello World Application. RAP Application is (like RCP Application) an Eclipse Plugin which is an OSGi bundle. Before explaining generated code of the RAP Hello World Application you need to understand OSGi.

I’ve decided to explain quickly OSGi by using PDE (Plug-in Development Environment) with 3 articles :

  • [step2] (this article) explains how to create OSGi bundle with PDE, how to run the OSGi container (Equinox) which manage a set of bundles (coming from Workspace + Target Platform) to start/stop bundle with OSGi console.
  • [step3] explains how to OSGi manage the dependencies between several bundles with Required-Bundle and Import-Package declared in the MANIFEST.MF and show in action the OSGi registry services which is used to share services between bundles (SOA Architecture).
  • [step4] explains how to use Servlet into OSGi context with OSGi HttpService. This article is interesting because it will explain how RAP Application works : RAP Servlet org.eclipse.rap.ui.internal.servlet.RequestHandler is called when URL http://127.0.0.1:8080/rap/ is accessed.

In this article we create an OSGi bundle org.akrogen.dynaresume.osgiapplication which defines a simple OSGi Activator which displays in the System.out when the bundle is started and stopped. Here is a scheme which shows in action org.akrogen.dynaresume.osgiapplication managed with OSGi container (Equinox) :

Download

You can download rap_step2.zip which contains the following explained projects :

  • org.akrogen.dynaresume.osgiapplication which is the generated OSGi Bundle explained in this article.

org.akrogen.dynaresume.osgiapplication

In this section we create org.akrogen.dynaresume.osgiapplication which defines a simple Activator which displays in the System.out when the bundle is started and stopped.

Create Bundle

Here we create the bundle org.akrogen.dynaresume.osgiapplication with PDE (Plug-in Development Environment). To do that go to the menu File/New/Other and Plug-in Development/Plug-in Project :

Click on Next button, and :

  • fill Project name field with org.akrogen.dynaresume.osgiapplication.
  • select the radio button an OSGI framework because we want to develop an OSGi bundle and select the combo standard.

Click on Next button, the wizard page which configures the OSGi bundle is displayed :

  • ID field is the Bundle identifier (Bundle-SymbolicName: org.akrogen.dynaresume.osgiapplication).
  • Version field is the Bundle version (Bundle-Version: 1.0.0.qualifier).
  • Name field is the Bundle name (Bundle-Name: OSGi Application).
  • Execution Environment set the minimal version of the JRE where the bundle can be executed (Bundle-RequiredExecutionEnvironment: J2SE-1.6).
  • generate an activator, a Java class that controls the plug-in’s life cycle option must be selected to generate a Bundle Activator. The Activator package name use « internal » package org.akrogen.dynaresume.osgiapplication.internal because we want forbid the use of this class in another bundles. We will see how to manage that in [step3], but a (Eclipse) common way is to set classes forbidden for another bundles in an internal package.

Click on Finish button to generate the OSGi bundle project. Your workspace looks like this :

An OSGi bundle contains a MANIFEST.MF which declares some meta-data. If you open the META-INF/MANIFEST.MF file you will see that :

  • Activator class which implement OSGi interface org.osgi.framework.BundleActivator, is declared with Bundle-Activator :
    Bundle-Activator: org.akrogen.dynaresume.osgiapplication.internal.Activator

    An OSGi Activator is like Java Main. It’s the main entry for the OSGi bundle. It can be started and stopped with OSGi console.

  • our bundle depends on OSGi interface org.osgi.framework.BundleActivator, so there are Plugin-Dependencies of the JAR org.eclipse.osgi*.jar which contains this interface. OSGi dependencies are managed with Required-Bundle or Import-Package (see [step3] for more information). In our case, Import-Package is used :
    Import-Package: org.osgi.framework;version="1.3.0"

OSGi bundle content

The bundle org.akrogen.dynaresume.osgiapplication is generated. It contains :

  • A META-INF/MANIFEST.MF which contains OSGi bundles meta-data :
    Manifest-Version: 1.0
    Bundle-ManifestVersion: 2
    Bundle-Name: OSGi Application
    Bundle-SymbolicName: org.akrogen.dynaresume.osgiapplication
    Bundle-Version: 1.0.0.qualifier
    Bundle-Activator: org.akrogen.dynaresume.osgiapplication.internal.Activator
    Import-Package: org.osgi.framework;version="1.3.0"
    Bundle-RequiredExecutionEnvironment: JavaSE-1.6
    

    Interesting meta-data are :

    • Bundle-SymbolicName defines the ID of the bundle. This ID can be used when another bundle want depend on this bundle with Required-Bundle meta-data.
    • Import-Package is used to use classes/interfaces from org.osgi.framework package which comes from org.eclipse.osgi.*.jar. This JAR exports the org.osgi.framework package with Export-Package meta-data (see [step3] for more information).
  • A Java class org.akrogen.dynaresume.osgiapplication.internal.Activator with this content :
    package org.akrogen.dynaresume.osgiapplication.internal;
    
    import org.osgi.framework.BundleActivator;
    import org.osgi.framework.BundleContext;
    
    public class Activator implements BundleActivator {
    
    	private static BundleContext context;
    
    	static BundleContext getContext() {
    		return context;
    	}
    
    	/*
    	 * (non-Javadoc)
    	 * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
    	 */
    	public void start(BundleContext bundleContext) throws Exception {			
    		Activator.context = bundleContext;
    	}
    
    	/*
    	 * (non-Javadoc)
    	 * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
    	 */
    	public void stop(BundleContext bundleContext) throws Exception {
    		Activator.context = null;
    	}
    
    }

In OSGi console section ,we will see that OSGi bundle org.akrogen.dynaresume.osgiapplication could be :

  • started with OSGi console, the Activator#start(BundleContext bundleContext) will be called.
  • stopped with OSGi console, the Activator#stop(BundleContext bundleContext) will be called.

The Activator class implements org.osgi.framework.BundleActivator and it is declared in the META-INF/MANIFEST.MF like this :

...
Bundle-Activator: org.akrogen.dynaresume.osgiapplication.internal.Activator

OSGi bundle follows a Life cycle (RESOLVED, INSTALLED, …). To see it in action, we add System.out in the start/stop method of the Activator like this :

package org.akrogen.dynaresume.osgiapplication.internal;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {

	private static BundleContext context;

	static BundleContext getContext() {
		return context;
	}

	/*
	 * (non-Javadoc)
	 * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
	 */
	public void start(BundleContext bundleContext) throws Exception {		
		System.out.println("Start Bundle [" + bundleContext.getBundle().getSymbolicName() + "]");
		Activator.context = bundleContext;
	}

	/*
	 * (non-Javadoc)
	 * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
	 */
	public void stop(BundleContext bundleContext) throws Exception {
		System.out.println("Stop Bundle [" + bundleContext.getBundle().getSymbolicName() + "]");
		Activator.context = null;
	}

}

OSGi container

OSGi bundles works with an OSGi container. You can compare WEB Application (WAR) with OSGi bundle (JAR with META-INF) :

  • WEB Application works with Servlet Container and OSGI bundle works with OSGi container (Felix, Equinox).
  • Servlet container provides javax.servlet.* interfaces and OSGi container provides org.osgi.framework.* interfaces.
  • There are several Servlet container implementations like Tomcat, Jetty, there are several OSGi container implementations like Felix, Equinox.

OSGi containers manage for instance the life cycle of OSGi bundles, the dependencies with Import-Package/Required-Bundle between bundles, and OSGi registry services. Here, Equinox, which is an Eclipse implementation of an OSGi container, is used. But you can start the OSGi bundle created in this article with another OSGi container like Felix. For Eclipse Plugin like RAP Application, only Equinox can be used, because, this OSGi container manage extension point declared in a plugin.xml file used by RAP/RCP Application.

Run OSGi container

At this step we can start OSGi container to see in action our bundle and play with it. To do that, open the META-INF/MANIFEST.MF and go to the Overview tab. Click on « Launch the framework » of the Testing section :

This action, starts OSGi container, with bundles declared in the RAP Target Platform. (which was installed) The view Console displays this trace :

We can notice that our Activator#start is called.

OSGi console

When OSGi container is started, the (generic) Eclipse View Console displays the content of the OSGi console. OSGi console is used with some commands and is useful to see bundles deployed in the OSGi container, to start/stop a bundle.

ss command

To see bundles deployed in the OSGi container, go to the view Console and type :

ss

This command (Short Status) displays a set of bundles and give some information about ID, State….

In this sample, our bundle has the 79 ID. This ID is used to apply OSGi commands (start/stop…) to the bundle. State of the bundle is ACTIVE (started).

stop command

You can stops the bundle with OSGi console. Type :

stop 79

This command stop the bundle and you can check that in the console (Activator#stop is called) :

You can check that the state of the bundle has changed to RESOLVED state. To do that, type in the OSGi console :

ss

OSGi console displays :

79 RESOLVED org.akrogen.dynaresume.osgiapplication_1.0.0.qualifier

start command

You can start the bundle with OSGi console. Type :

start 79

This command starts the bundle and you can check that in the console (Activator#start is called) :

You can check that the state of the bundle has changed to ACTIVE state. To do that, type in the OSGi console :

ss

OSGi console displays :

79 ACTIVE org.akrogen.dynaresume.osgiapplication_1.0.0.qualifier

OSGi Launch configuration

At this step, if you type ss to display Short Status of the bundles deployed in the OSGI container, you will see a lot of bundles like RAP, JFace… In our case we need not those bundles. In this section we select only the OSGi bundles that we need.

You can do that, with the launch OSGi Framework created by Testing link. To modify the launch, go to Run->Run Configurations… :

And click on the OSGi Framework launch created :

You can notice that all the bundles are selected :

  • bundles coming from Workspace are selected.
  • bundles coming from Target Platform (RAP Target Platform that we have installed) are selected .

Unselect all bundles and select only org.akrogen.dynaresume.osgiapplication bundle :

org.akrogen.dynaresume.osgiapplication import the package org.osgi.framework. So you need to select the bundles which export the package org.osgi.framework. If you click on Validate Bundles buttons, you will see this dialogue error :

You need to select the bundle which exports the org.osgi.framework package. You can select manually the correct bundle but it can be awful because the new selected bundle could depend on another bundle. It’s possible to select automatically required bundles, to do that click on the Add Required Bundles button :

This action select org.eclipse.osgi bundle which exports the package org.osgi.framework. If you click on Validate Bundles buttons, you will see that there is no error :

If you restart and click on ss, you will see just 2 bundles in the OSGi console :

Conclusion

In this article we have explained how to create OSGi bundle with PDE, how run the OSGi container (Equinox) which manages a set of bundles (coming from Workspace and Target Platform) to start/stop bundle with OSGi console.

In next article [step3] we will explain how OSGi manage dependencies between several bundles with Required-Bundle and Import-Package declared in the MANIFEST.MF and show in action the OSGi registry services which is used to share services between bundles (SOA Architecture).

Catégories :Eclipse RAP, Equinox
  1. Dave
    janvier 30, 2014 à 4:52

    hello there. interesting article, a little outdated, but interesting. thanks and congratulations.
    One question: I use git to source control my project, and I performed a git init in the folder org.akrogen.dynaresume.osgiapplication, but of course this does not checks in the run configuration we are modifying in the last part of the tutorial. and I think it should be source contrlled, since if you wrongly change it, a lot of bad things happen (osgi console does not start, and so on…)
    Any hint about that? thanks!

    • janvier 30, 2014 à 5:00

      As you said, my article is outdated, so you must not use my launch (if I remember there are felix gogo console bundles to add). On other words restart from scratch your project and lanches and don’t use my projects.

  1. mai 18, 2011 à 3:05
  2. mai 20, 2011 à 8:47

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s

%d blogueurs aiment cette page :