View source for Steps for Building Applications from Bundels

{{Ecl_menu}}__NOTOC__

<h4>1. Study the Interfaces</h4>

* [http://www.osgi.org/javadoc/r4v42/org/osgi/framework/Bundle.html Bundle]
* [http://www.osgi.org/javadoc/r4v42/org/osgi/framework/BundleContext.html BundleContext]
* [http://www.osgi.org/javadoc/r4v42/org/osgi/framework/BundleActivator.html BundleActivator]
----------
<h4>2. Define the Bundle Service Interface</h4>

<h5>2.1 Define the Java Interface that exposes the services</h5>
Let us suppose that one wants to define a service that allows the user to find a book using its isbn. 
<source lang="java">
package cs.ecl.osgi.simple.bookfinder;

public interface BookFinder {
	Book findBook(int isbn) throws BookNotFoundException;
}
</source>
Define in the same bundle the classes that you need such as: Book and BookNotFoundException
<source lang="java">
package cs.ecl.osgi.simple.bookfinder;

public class Book {
	private int isbn;
	private String title;
	
	public Book(int isbn, String title) {
		super();
		this.isbn = isbn;
		this.title = title;
	}

	public String getTitle() {
		return title;
	}

	public void setTitle(String title) {
		this.title = title;
	}

	public int getIsbn() {
		return isbn;
	}

	public void setIsbn(int isbn) {
		this.isbn = isbn;
	}
}

package cs.ecl.osgi.simple.bookfinder;

public class BookNotFoundException extends Exception {
	private static final long serialVersionUID = -6184839510952070091L;

	public BookNotFoundException() {
		super();
	}

	public BookNotFoundException(String arg0) {
		super(arg0);
	}
}
</source>

<h5>2.2 Define the MANIFEST.MF  for the bundle ''cs.ecl.osgi.simple.bookfinder'' </h5>
<source lang="xml">
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Bookfinder
Bundle-SymbolicName: cs.ecl.osgi.simple.bookfinder
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Bundle-Vendor: Seneca College - Eclipse Course
Export-Package: cs.ecl.osgi.simple.bookfinder
</source>
----------

<h4>3. Define the Bundle Service Provider</h4>
The service ''bookfinder'' could be used only if there is a bundle that implements the service. The bundle ''cs.ecl.osgi.simple.bookfinderservice'' implements ''BundleActivator'' interface in the ''Activator'' class. This bundle will be called 'service provider'.

<h5>3.1 Define the Activator class for the service provider</h5>
<source lang="java">
package cs.ecl.osgi.simple.bookfinderservice;

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

import cs.ecl.osgi.simple.bookfinder.BookFinder;
import cs.ecl.osgi.simple.bookfinderservice.internals.BookFinderImplementation;

public class Activator implements BundleActivator {

	private static BundleContext context;

	static BundleContext getContext() {
		return context;
	}
	
	public void start(BundleContext bundleContext) throws Exception {
		Activator.context = bundleContext;
		BookFinder bookService = new BookFinderImplementation();
		
		context.registerService(BookFinder.class.getName(), bookService, null);
		System.out.println(" Bookfinder service registered ");
	}
	
	public void stop(BundleContext bundleContext) throws Exception {
		Activator.context = null;
		System.out.println(" Bookfinder service stopped ");
	}
}
</source>

<h5>3.2 Define the service implementation class </h5>
The class must be defined in an internal package ''cs.ecl.osgi.simple.bookfinderservice.internals'' <u>The package will not be exposed to the outside world</u>

<source lang="java">
package cs.ecl.osgi.simple.bookfinderservice.internals;

import cs.ecl.osgi.simple.bookfinder.Book;
import cs.ecl.osgi.simple.bookfinder.BookFinder;
import cs.ecl.osgi.simple.bookfinder.BookNotFoundException;

public class BookFinderImplementation implements BookFinder {
	private static final Book[] BOOKS = new Book[] {
			new Book(1234, "Java Programming Language"), 
			new Book(5678, "OSGi") };

	public Book findBook(int isbn) throws BookNotFoundException {
		Book found = null;

		for (Book b : BOOKS)
			if (b.getIsbn() == isbn) {
				found = b;
				break;
			}
		if (found == null)
			throw new BookNotFoundException("No book with isbn = " + isbn);

		return found;
	}
}
//This is a simple and trivial implementation. 
//There real implementation should use database,  distributed system, etc.
</source>

<h5>3.3 Define  the MANIFEST.MF for the ''cs.ecl.osgi.simple.bookfinderservice'' bundle</h5>
<source lang="xml">
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Bookfinderservice
Bundle-SymbolicName: cs.ecl.osgi.simple.bookfinderservice
Bundle-Version: 1.0.0.qualifier
Bundle-Activator: cs.ecl.osgi.simple.bookfinderservice.Activator
Bundle-ActivationPolicy: lazy
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Import-Package: org.osgi.framework;version="1.3.0"
Bundle-Vendor: Seneca College -  Eclipse Course
Export-Package: cs.ecl.osgi.simple.bookfinderservice
Require-Bundle: cs.ecl.osgi.simple.bookfinder;bundle-version="1.0.0"
</source>

The bundle export only the package ''cs.ecl.osgi.simple.bookfinderservice'' Meanwhile, the implementation package - ''cs.ecl.osgi.simple.bookfinderservice.internals'' -  <strong>is hidden to the outside world and can be changed dynamically any time a better implementation is created</strong>.

The bundle provider requires the osgi framework and the interface bundle (e.g. ''cs.ecl.osgi.simple.bookfinder'' bundle)

: ''Require-Bundle'': cs.ecl.osgi.simple.bookfinder;bundle-version="1.0.0"
: ''Import-Package'': org.osgi.framework;version="1.3.0"

The bundle'' cs.ecl.osgi.simple.bookfinderservice'' export its service, namely the bood finder service:

: ''Export-Package'': cs.ecl.osgi.simple.bookfinderservice

----------

<h4>4. Define the Bundle Service Consumer</h4>
The service ''bookfinder'' could be used only if there is a bundle that requests its service. The bundle ''cs.ecl.osgi.simple.bookfindconsumer'' by the time is activated ''BundleActivator'' looks for the service in the registry. This bundle will be called 'service consumer'.

<h5>4.1 Define the Activator class for the service consumer</h5>
<source lang="java">
package cs.ecl.osgi.simple.bookfinderconsumer.bookfinderconsumer;

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

import cs.ecl.osgi.simple.bookfinder.BookFinder;
import cs.ecl.osgi.simple.bookfinder.BookNotFoundException;

public class Activator implements BundleActivator {

	private static BundleContext context;
	private BookFinder finderService;

	static BundleContext getContext() {
		return context;
	}

	public void start(BundleContext bundleContext) throws Exception {
		Activator.context = bundleContext;

		ServiceReference reference = context
				.getServiceReference(BookFinder.class.getName());
		if (reference != null) {
			finderService = (BookFinder) context.getService(reference);

			if (finderService != null) {
				printBook(finderService);
				context.ungetService(reference);
			} else
				System.err.println("the service cannot be used !!!");
		} else
			System.err.println("the service cannot be found !!!");

	}

	public void stop(BundleContext bundleContext) throws Exception {
		Activator.context = null;
		System.err.println("consumer bundle stopped");
	}

	public void printBook(BookFinder finderService) {
		try {
			String s = finderService.findBook(1234).getTitle();

			System.out.print("Book found: " + s + " !!!");
		} catch (BookNotFoundException ex) {
			System.err.println(ex.getMessage());
		}
	}
}
</source>

Steps to find and use the service:

1. Look for the service reference in the bundle context:

The Framework returns ''ServiceReference'' objects from the ''BundleContext.getServiceReference'' method. 
A ''ServiceReference'' object may be shared between bundles and can be used:
1.  to examine the properties of the service
2. to get the service object. 

    <b>ServiceReference reference = context.getServiceReference(BookFinder.class.getName());</b>
   
2. Look for the service object referenced by the specified ''ServiceReference'' object, namely the ''reference'' variable obtained at the first step.
     if (reference != null) 
        <b> finderService = (BookFinder) context.getService(reference);</b>

3. If the service reference is valid, invoke its services and <b>release the service object</b> referenced by the specified ''ServiceReference'' object.
<source lang="java">
    if (finderService != null) { 
	// invoke the services
	context.ungetService(reference);
    }
</source>

The ''class org.osgi.framework.BundleContext'' defines the bundle's execution context within the Framework. The context is used to grant access to other methods so that this bundle can interact with the Framework. 

BundleContext methods allow a bundle to: 

* Subscribe to events published by the Framework. 
* Register service objects with the Framework service registry. 
* Retrieve ServiceReferences from the Framework service registry. 
* Get and release service objects for a referenced service. 
* Install new bundles in the Framework. 
* Get the list of bundles installed in the Framework. 
* Get the Bundle object for a bundle.

<h5>4.2 Define  the MANIFEST.MF for the ''cs.ecl.osgi.simple.bookfinderconsumer'' bundle</h5>
<source lang="xml">
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Bookfinderconsumer
Bundle-SymbolicName: cs.ecl.osgi.simple.bookfinderconsumer
Bundle-Version: 1.0.0.qualifier
Bundle-Activator: cs.ecl.osgi.simple.bookfinderconsumer.bookfinderconsumer.Activator
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Import-Package: cs.ecl.osgi.simple.bookfinder,
                            org.osgi.framework;version="1.3.0"
Bundle-Vendor: Seneca College - Eclipse Course
Require-Bundle: org.eclipse.osgi;bundle-version="3.6.1"
</source>