Angelo's Blog

In [step2] we have created our first OSGi bundle org.akrogen.dynaresume.osgiapplication with PDE (Plug-in Development Environment) and we have used OSGi console to start/stop our bundle. This bundle defines an OSGi Activator which uses classes from org.osgi.framework package. This dependency use Import-Package :

Import-Package: org.osgi.framework;version="1.3.0"

OSGi dependencies can be managed with 2 means :

• Import-Package : the bundle declares packages that it needs in the MANIFEST.MF. The bundle doesn’t know which bundles export the packages.
• Require-Bundle : the bundle declares explicitly the required bundles in the MANIFEST.MF .

One other feature of OSGi, is the OSGi services registry where bundle can register/unregister services Publisher) and another bundles can consume services (Consumer) retrieved from the OSGi services registry.

In this article, we will create new Services bundle org.akrogen.dynaresume.services which will publish UserService service (which gives a list of Users) in the OSGI services registry. org.akrogen.dynaresume.osgiapplication will be modified to consume UserService and displays the list of Users in the System.out. User class will be defined in the org.akrogen.dynaresume.services bundle.

At first, org.akrogen.dynaresume.osgiapplication will use Require-Bundle,then Import-Package after to see the advantage of this kind of dependency.

At the end of this article we will have 3 OSGi bundles :

• org.akrogen.dynaresume.domain : OSGi bundle which defines and export Java Bean Domain org.akrogen.dynaresume.services.User.
• org.akrogen.dynaresume.services : OSGi bundle which registers in the OSGi services registry (in the Activator#start) an implementation of org.akrogen.dynaresume.services.UserService which is able to returns the list of Users :

  package org.akrogen.dynaresume.services;
  
  import java.util.Collection;
  
  import org.akrogen.dynaresume.domain.User;
  
  public interface UserService {
  
  	Collection<User> findAllUsers();
  }

• org.akrogen.dynaresume.osgiapplication : OSGi bundle creates a thread (in the Activator#start) which get UserService from the OSGi services registry every 5 seconds then call UserService#findAllUsers() to display User in the System.out.

This schema shows you that there are dependencies between OSGi bundles. Dependencies can be managed with Require-Bundle or Import-Package.

Require-Bundle vs Import-Package

To see the difference between Require-Bundle and Import-Package, I’ve decided to :

1. create 2 OSGi bundles which use Require-Bundle :
   • a Service bundle org.akrogen.dynaresume.services which publish service UserService in the OSGi services registry and export org.akrogen.dynaresume.domain package to give the access to the org.akrogen.dynaresume.domain.User class.
   • a Client bundle org.akrogen.dynaresume.osgiapplication which consumes UserService retrieved from the OSGi services registry.
2. create 3 OSGi bundles which use Import-Package. We will move User class from org.akrogen.dynaresume.services to a new bundle org.akrogen.dynaresume.domain. We will see with Import-Package that you don’t need to change your dependency for org.akrogen.dynaresume.osgiapplication. Although with Require-Bundle you must modify the dependency.

2 bundles dependencies

You can download rap_step3_1.zip which contains explained projects in this section.

Here is a schema that we will have at the end of this section :



• org.akrogen.dynaresume.services : OSGi bundle registers in the OSGi services registry (in the Activator#start) an implementation of the org.akrogen.dynaresume.services.UserService interface. This service is able to return a list of Users. This bundle hosts the User class and exports the good package org.akrogen.dynaresume.domain.
• org.akrogen.dynaresume.osgiapplication : OSGi bundle creates a Thread (in the Activator#start) which retrieves UserService from the OSGi services registry and call UserService#findAllUsers() every 5 seconds to display User list in the System.out.

Require-Bundle will be used in this section.

Require-Bundle/Import-Package Overview

org.akrogen.dynaresume.services

In this section we will create another OSGi bundle org.akrogen.dynaresume.services which defines the basic Domain org.akrogen.dynaresume.domain.User class :

package org.akrogen.dynaresume.domain;

public class User {

	private final String name;
	private final String lastName;

	public User(String name, String lastName) {
		this.name = name;
		this.lastName = lastName;
	}

	public String getName() {
		return name;
	}

	public String getLastName() {
		return lastName;
	}

}

Create a new OSGi bundle org.akrogen.dynaresume.services (with org.akrogen.dynaresume.services.internal.Activator, because we need it in the next section) and create org.akrogen.dynaresume.domain.User as described below. Your workspace looks like this :



For the moment, User class cannot be used in another bundle, because we must export the package org.akrogen.dynaresume.domain. We don’t do that at this step to see this problem in action.

org.akrogen.dynaresume.osgiapplication

At this step we want to use org.akrogen.dynaresume.domain.User class in the org.akrogen.dynaresume.osgiapplication Activator. To do that we must set a dependency to the org.akrogen.dynaresume.services bundle. Bundle dependencies can be managed with 2 means :

• Import-Package : the bundle declares the needed in the MANIFEST.MF. The bundle don’t know which bundles export the packages.
• Require-Bundle : the bundle declares explicitly the required bundles in the MANIFEST.MF .

Import-Package

In this section we will use Import-Package in the org.akrogen.dynaresume.osgiapplication to use User class from the org.akrogen.dynaresume.services bundle. To do that, open the org.akrogen.dynaresume.osgiapplication/META-INF/MANIFEST.MF, go to the Dependencies tab and click on Add… button from the Imported Packages section :



This action opens, Package Selection dialogue. Try to type org.a in the field to select org.akrogen.dynaresume.domain package :



You can notice that org.akrogen.dynaresume.domain doesn’t appear? This problem comes from org.akrogen.dynaresume.domain package from the org.akrogen.dynaresume.services bundle which is not accessible. To resolve this problem, you must export the package org.akrogen.dynaresume.domain in the org.akrogen.dynaresume.services bundle. Export the package org.akrogen.dynaresume.domain and try to import the package again. When you type org.a, the org.akrogen.dynaresume.domain must appear in the dialogue :



Click on OK button, and you will notice that org.akrogen.dynaresume.domain package is imported.



If you go to the MANIFEST.MF tab, you will see the Import-Package :

Import-Package: org.akrogen.dynaresume.domain,
 org.osgi.framework;version="1.3.0"

Here is the full MANIFEST.MF file content :

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.akrogen.dynaresume.domain,
 org.osgi.framework;version="1.3.0"
Bundle-RequiredExecutionEnvironment: JavaSE-1.6

After saving, you will notice that User class is accessible in the Activator class of the org.akrogen.dynaresume.osgiapplication :



Require-Bundle

If you have tried Import-Package, before starting this section :

1. remove the Import-Package org.akrogen.dynaresume.domain from the org.akrogen.dynaresume.osgiapplication bundle
2. remove the Export-Package org.akrogen.dynaresume.domain from the org.akrogen.dynaresume.services bundle to see the problem of the access User class.

In this section we will use Require-Bundle in the org.akrogen.dynaresume.osgiapplication to use User class from the org.akrogen.dynaresume.services bundle. To do that, open the org.akrogen.dynaresume.osgiapplication/META-INF/MANIFEST.MF, go to the Dependencies tab and click on Add… button from the Required Plugins section :



This action opens, Plug-in Selection dialogue. Try to type org.a in the field to select org.akrogen.dynaresume.services bundle :



Click on OK button, and you will notice that org.akrogen.dynaresume.services bundle is added :



If you go to the MANIFEST.MF tab, you will see the Require-Bundle :

Require-Bundle: org.akrogen.dynaresume.services;bundle-version="1.0.0"

You can notice that there is bundle-version token which means that our bundle works only with version>=1.0.0 of org.akrogen.dynaresume.services. Here is the full MANIFEST.MF file content :

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
Require-Bundle: org.akrogen.dynaresume.services;bundle-version="1.0.0"

If you try to access to the User class in the Activator class of the org.akrogen.dynaresume.osgiapplication, you will notice that User doesn’t appear in the Java completion?



This problem comes from org.akrogen.dynaresume.domain package from the org.akrogen.dynaresume.services bundle which is not accessible. To resolve this problem, you must export the package org.akrogen.dynaresume.domain in the org.akrogen.dynaresume.services bundle. Export the package org.akrogen.dynaresume.domain and try to access again the User class :



org.akrogen.dynaresume.services

Export Package

In this section we will export package org.akrogen.dynaresume.domain of the bundle org.akrogen.dynaresume.services to give the capability to use on another bundle classes form this package. To do that, open the org.akrogen.dynaresume.services/META-INF/MANIFEST.MF file go to the Runtime tab and click on Add… button of the Exported Packages :



Select org.akrogen.dynaresume.domain package and click on the OK button :



This action adds the org.akrogen.dynaresume.domain package in the list of Exported Packages :



If you go to the MANIFEST.MF tab you can see the content of the MANIFEST.MF which exports the package :

Export-Package: org.akrogen.dynaresume.domain

Here is the full MANIFEST.MF file content :

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: OSGi Services
Bundle-SymbolicName: org.akrogen.dynaresume.services
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Export-Package: org.akrogen.dynaresume.domain

OSGi services registry

At this step, we have 2 bundles

• org.akrogen.dynaresume.services which export package org.dynaresume.domain.
• org.akrogen.dynaresume.osgiapplication which use Require-Bundle to have dependency with org.akrogen.dynaresume.services to access to the User class.

One other feature of OSGi, is the OSGi services registry which is used to share services between several bundles (SOA). In this section we will modify org.akrogen.dynaresume.services to publish a UserService and org.akrogen.dynaresume.osgiapplication to consume this service. At the end of this section, your workspace looks like this :



Publisher – org.akrogen.dynaresume.services

UserService

Create in the bundle org.akrogen.dynaresume.services, the org.akrogen.dynaresume.services.UserService interface like this :

package org.akrogen.dynaresume.services;

import java.util.Collection;

import org.akrogen.dynaresume.domain.User;

public interface UserService {

	Collection<User> findAllUsers();
}

MANIFEST.MF

org.akrogen.dynaresume.osgiapplication will need to access to the UserService interface. To allow that, export the org.akrogen.dynaresume.osgiapplication package. Your MANIFEST.MF will export the new package org.akrogen.dynaresume.services :

Export-Package: org.akrogen.dynaresume.domain,
 org.akrogen.dynaresume.services

UserServiceImpl

Create the org.akrogen.dynaresume.services.internal.UserServiceImpl class which implements org.akrogen.dynaresume.services.UserService interface like this :

package org.akrogen.dynaresume.services.internal;

import java.util.ArrayList;
import java.util.Collection;

import org.akrogen.dynaresume.domain.User;
import org.akrogen.dynaresume.services.UserService;

public class UserServiceImpl implements UserService {

	private final Collection<User> users;

	public UserServiceImpl() {
		users = new ArrayList<User>();
		users.add(new User("Angelo", "Zerr"));
		users.add(new User("Dino", "Cosmas"));
	}

	public Collection<User> findAllUsers() {
		return users;
	}
}

internal package is used to forbid the access of this class to other bundles (because this package is not exported).

Activator

Here, we will use the Activator of the org.akrogen.dynaresume.services bundle to register/unregister the service UserService. Modify org.akrogen.dynaresume.services.internal.Activator like this :

package org.akrogen.dynaresume.services.internal;

import org.akrogen.dynaresume.services.UserService;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;

public class Activator implements BundleActivator {

	private static BundleContext context;
	private ServiceRegistration reg = null;

	static BundleContext getContext() {
		return context;
	}

	public void start(BundleContext bundleContext) throws Exception {
		// Register UserService instance into OSGi Services Registry
		reg = bundleContext.registerService(UserService.class.getName(),
				new UserServiceImpl(), null);
		Activator.context = bundleContext;
	}

	public void stop(BundleContext bundleContext) throws Exception {
		// Unregister UserService instance from OSGi Services Registry
		if (reg != null) {
			reg.unregister();
			reg = null;
		}
		Activator.context = null;
	}

}

• Activator#start register the implementation of the service UserServiceImpl like this :

  reg = bundleContext.registerService(UserService.class.getName(), new UserServiceImpl(), null);
  

  the first parameter of the BundleContext#registerService is the key of the service. You can use any String key, but a good pratice is used the interface class name (in our case UserService) When bundle consumer (in our case org.akrogen.dynaresume.osgiapplication) want to retrieve this service, it will use this key. BundleContext#registerService returns an instance of ServiceRegistration which is used to unregister the service.

• Activator#stop unregister (by using instance of ServiceRegistration) the implementation of the service UserServiceImpl like this :

  reg.unregister();

internal package is used to forbid the access to this class to another bundles (because this package is not exported).

Consumer – org.akrogen.dynaresume.osgiapplication

At this step, org.akrogen.dynaresume.services bundle publishes UserService in the OSGi services registry with the key UserService.class.getName() :

reg = bundleContext.registerService(UserService.class.getName(), new UserServiceImpl(), null);

Now we will modify org.akrogen.dynaresume.osgiapplication to retrieve the UserService from the OSGi services registry like this :

ServiceReference ref = bundleContext.getServiceReference(UserService.class.getName());
UserService userService = (UserService) context.getService(ref);

FindAllUsersThread

Now we will create a Thread org.akrogen.dynaresume.osgiapplication.internal.FindAllUsersThread which retrieves UserService every 5 seconds from the OSGi services registry and displays the list of Users in the System.out every 5 seconds. Why use a Thread instead of doing directly that in the Activator#start? The answer is that if you do that in the Activator#start, you will block the OSGi container. It’s very important not to do a big process in the Activator#start and delegate the big process to a Thread.

Create org.akrogen.dynaresume.osgiapplication.internal.FindAllUsersThread class Thread like this :

package org.akrogen.dynaresume.osgiapplication.internal;

import java.util.Collection;

import org.akrogen.dynaresume.domain.User;
import org.akrogen.dynaresume.services.UserService;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;

public class FindAllUsersThread extends Thread {

	private static final long TIMER = 5000;

	@Override
	public void run() {
		while (!super.isInterrupted()) {

			try {
				// 1. Get UserService
				System.out
						.println("--- Get UserService from OSGi registry services ---");
				UserService userService = getUserService();
				if (userService != null) {
					// 2. Display users by using UserServive
					displayUsers(userService);
				} else {
					System.out
							.println(" Cannot get UserService=> UserService is null!");
				}
			} catch (Throwable e) {
				e.printStackTrace();
			} finally {
				try {
					sleep(TIMER);
				} catch (InterruptedException e) {
					Thread.currentThread().interrupt();
				}
			}
		}
	}

	private UserService getUserService() {
		BundleContext context = Activator.getContext();
		if (context == null) {
			return null;
		}
		ServiceReference ref = context.getServiceReference(UserService.class
				.getName());
		if (ref != null) {
			return (UserService) context.getService(ref);
		}
		return null;
	}

	private void displayUsers(UserService userService) {
		Collection<User> users = userService.findAllUsers();
		for (User user : users) {
			System.out.println("User [name=" + user.getName() + ", lastName="
					+ user.getLastName() + "]");
		}
	}

}

Activator

Modify org.akrogen.dynaresume.osgiapplication.internal.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;
	}

	private Thread findAllUsersThread = null;

	public void start(BundleContext bundleContext) throws Exception {
		System.out.println("Start Bundle ["
				+ bundleContext.getBundle().getSymbolicName() + "]");
		// Start Thread which call UserService#findAllUsers();
		findAllUsersThread = new FindAllUsersThread();
		findAllUsersThread.start();
		Activator.context = bundleContext;
	}

	public void stop(BundleContext bundleContext) throws Exception {
		System.out.println("Stop Bundle ["
				+ bundleContext.getBundle().getSymbolicName() + "]");

		// Stop Thread which call UserService#findAllUsers();
		if (findAllUsersThread != null) {
			findAllUsersThread.interrupt();
			findAllUsersThread = null;
	  	}
		Activator.context = null;
	}
}

• Activator#start create the FindAllUsersThread Thread and start it.
• Activator#stop interrupt the FindAllUsersThread Thread.

Testing

At this step we can test and play with our bundles. Before Launching it, check that the 2 bundles are selected in the OSGi launch :



When you start the launch, you will see this trace :

osgi> Start Bundle [org.akrogen.dynaresume.osgiapplication]
--- Get UserService from OSGi registry services ---
User [name=Angelo, lastName=Zerr]
User [name=Dino, lastName=Cosmas]

The Activator of the org.akrogen.dynaresume.osgiapplication bundle starts the Thread FindAllUsersThread. FindAllUsersThread retrieve the service UserService and displays User list on the console. Every 5 seconds, User list must be displayed in the console.

Type ss to display the list of the bundles :

Framework is launched.

id State Bundle
0 ACTIVE org.eclipse.osgi_3.6.2.R36x_v20110210
1 ACTIVE org.akrogen.dynaresume.services_1.0.0.qualifier
2 ACTIVE org.akrogen.dynaresume.osgiapplication_1.0.0.qualifier


In my case, the ID of the org.akrogen.dynaresume.osgiapplication is 2. Type stop 2 to stop the org.akrogen.dynaresume.osgiapplication bundle :

Stop Bundle [org.akrogen.dynaresume.osgiapplication]

Type start 2 to restart the org.akrogen.dynaresume.osgiapplication bundle, console displays :

osgi> Start Bundle [org.akrogen.dynaresume.osgiapplication]
--- Get UserService from OSGi registry services ---
User [name=Angelo, lastName=Zerr]
User [name=Dino, lastName=Cosmas]

Type stop 1 to stop the org.akrogen.dynaresume.services bundle, console displays :

--- Get UserService from OSGi registry services ---
Cannot get UserService=> UserService is null!

This trace shows that UserService was unregistered.

Type start 1 to restart the org.akrogen.dynaresume.services bundle, console displays :

osgi> --- Get UserService from OSGi registry services ---
User [name=Angelo, lastName=Zerr]
User [name=Dino, lastName=Cosmas]

This trace shows that UserService was re-published.

3 bundles dependencies

You can download rap_step3_2.zip which contains explained projects in this section.

At this step we have 2 bundles org.akrogen.dynaresume.services and org.akrogen.dynaresume.osgiapplication where this last bundle depends on org.akrogen.dynaresume.services bundle with Require-Bundle.

org.akrogen.dynaresume.services hosts org.akrogen.dynaresume.domain.User class, but generally the Domain classes are stored into another bundle.

Now we will refactor our project to move org.akrogen.dynaresume.domain.User class to a new another bundle org.akrogen.dynaresume.domain. We will see problems with Require-Bundle used in org.akrogen.dynaresume.osgiapplication.

Here is a schema that we will have at the end of this section :



Your workspace will look like this :



org.akrogen.dynaresume.domain

Create a new OSGi bundle org.akrogen.dynaresume.domain with No Activator. You will notice that this bundle has no dependency to OSGi, because there is no Activator.

Move User from org.akrogen.dynaresume.services to org.akrogen.dynaresume.domain

Here we will move org.akrogen.dynaresume.domain.User class from org.akrogen.dynaresume.services bundle to the org.akrogen.dynaresume.domain bundle. To do that, select User class, click on the right mouse button and select Refactor->Move… menu item :



Move dialogue is opened :



Go to the org.akrogen.dynaresume.domain project and click on Create Package… button, New Java Package dialogue is opened :



Fill in the field name with org.akrogen.dynaresume.domain package and click on the Finish button, package is created :



Click on OK button, your workspace has compilation problems :



User class must be accessed by another bundle. To do that, export package org.akrogen.dynaresume.domain, the org.akrogen.dynaresume.domain/META-INF/MANIFEST.MF looks like this :

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: OSGi Domain
Bundle-SymbolicName: org.akrogen.dynaresume.domain
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Export-Package: org.akrogen.dynaresume.domain

Fix problem with org.akrogen.dynaresume.services

Here we will fix problems with org.akrogen.dynaresume.services bundle :

• remove Export-Package org.akrogen.dynaresume.domain.
• Import Package org.akrogen.dynaresume.domain.

The org.akrogen.dynaresume.services/META-INF/MANIFEST.MF looks like this :

Bundle-ManifestVersion: 2
Bundle-Name: OSGi Services
Bundle-SymbolicName: org.akrogen.dynaresume.services
Bundle-Version: 1.0.0.qualifier
Bundle-Activator: org.akrogen.dynaresume.services.internal.Activator
Import-Package: org.akrogen.dynaresume.domain,
 org.osgi.framework;version="1.3.0"
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Export-Package: org.akrogen.dynaresume.services

Fix problem with org.akrogen.dynaresume.osgiapplication

org.akrogen.dynaresume.osgiapplication bundle have compilation problems :



because org.akrogen.dynaresume.domain.User is not resolved. We need to add dependency to the org.akrogen.dynaresume.domain. To do that Import-Package org.akrogen.dynaresume.domain. If you use only Import-Package, the org.akrogen.dynaresume.osgiapplication/META-INF/MANIFEST.MF looks like this :

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.akrogen.dynaresume.domain,
 org.akrogen.dynaresume.services,
 org.osgi.framework;version="1.3.0"
Bundle-RequiredExecutionEnvironment: JavaSE-1.6

At this step, we have no problem and you can play with our 3 bundles.

We need to fix the problem (add Require-Bundle or Import-Package org.akrogen.dynaresume.domain) here because org.akrogen.dynaresume.osgiapplication uses only Require-Bundle. If our bundle were using Import-Package :

Import-Package: org.akrogen.dynaresume.domain,
 org.akrogen.dynaresume.services,
...

instead of using Require-Bundle :

Require-Bundle: org.akrogen.dynaresume.services;bundle-version="1.0.0"
...

we wouldn’t have need to fix the compilation problems. In other words, if you use Import-Package your bundle wouldn’t be linked to a bundle and even if the bundle were splitting several classes into several bundles, your bundle would continue to work. OSGi advices to use Import-Package as soon as possible. With Eclipse Plug-In like RAP Application, it’s difficult to import a lot of packages.

Conclusion

In this article we have seen how to manage dependencies between OSGi bundle with Require-Bundle and Import-Package. OSGi services registry is used to share services between bundles and can be started/stopped.

We will see how RAP Application use those OSGi features in the next articles. RAP Application needs OSGi Container and Servlet Container. In the next article [step4] we will see how Servlet Container and OSGi Container work together.

Partager :

• Facebook
• X

J’aime chargement…

Articles similaires