Create a plugin project "de.vogella.osgi.quote" and the package "de.vogella.osgi.quote". Do not use a template. You do not need an activator. Afterwards select the MANIFEST.MF and the "Runtime" tab. Add "de.vogella.osgi.quote" to the exported packages.

Create the following interface "IQuoteService".

				
package de.vogella.osgi.quote;

public interface IQuoteService {
	String getQuote();
}

			

We will now define a bundle which will provide the service.

Create a plugin project "de.vogella.osgi.quoteservice". Do not use a template.

Select the MANIFEST.MF and dependecy tab. Add "de.vogella.osgi.quote" to the required plugins.

Create the following class "QuoteService".

				
package de.vogella.osgi.quoteservice.internal;

import java.util.Random;

import de.vogella.osgi.quote.IQuoteService;

public class QuoteService implements IQuoteService {

	@Override
	public String getQuote() {
		Random random = new Random();
		// Create a number between 0 and 2
		int nextInt = random.nextInt(3);
		switch (nextInt) {
		case 0:
			return "Tell them I said something";
		case 1:
			return "I feel better already";
		default:
			return "Hubba Bubba, Baby!";
		}

	}
}

			

Register the service in the class Activator.

				
package de.vogella.osgi.quoteservice;

import java.util.Hashtable;

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

import de.vogella.osgi.quote.IQuoteService;
import de.vogella.osgi.quoteservice.internal.QuoteService;

public class Activator implements BundleActivator {

	public void start(BundleContext context) throws Exception {
		IQuoteService service = new QuoteService();
		// Third parameter is a hashmap which allows to configure the service
		// Not required in this example
		context.registerService(IQuoteService.class.getName(), service,
				null);
		System.out.println("IQuoteService is registered");
	}

	public void stop(BundleContext context) throws Exception {
	}
}

			

Export your bundles and install them on your server. Start the service bundle.

Create a new plugin "de.vogella.osgi.quoteconsumer". Add also a dependency to the package "de.vogella.osgi.quote".

Lets register directly to the service and use it.

				
package de.vogella.osgi.quoteconsumer;

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

import de.vogella.osgi.quote.IQuoteService;

public class Activator implements BundleActivator {

	private BundleContext context;
	private IQuoteService service;

	public void start(BundleContext context) throws Exception {
		this.context = context;
		// Register directly with the service
		ServiceReference reference = context
				.getServiceReference(IQuoteService.class.getName());
		service = (IQuoteService) context.getService(reference);
		System.out.println(service.getQuote());
	}

	public void stop(BundleContext context) throws Exception {
		System.out.println(service.getQuote());
	}

}

			

Export this bundle, install it and start and stop it. Everything work. But if you stop the service bundle then your receive an error.

The reason for this is that OSGi is a very dynamic environment and service may be registered and de-registered any time. The next chapter will use a service tracker to improve this.

Declare a package dependency to the package "org.osgi.util.tracker" in your bundle.

To use this define the following class "MyQuoteServiceTrackerCustomizer"

				
package de.vogella.osgi.quoteconsumer;

import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.util.tracker.ServiceTrackerCustomizer;

import de.vogella.osgi.quote.IQuoteService;

public class MyQuoteServiceTrackerCustomizer implements
		ServiceTrackerCustomizer {

	private final BundleContext context;

	public MyQuoteServiceTrackerCustomizer(BundleContext context) {
		this.context = context;
	}

	private MyThread thread;

	@Override
	public Object addingService(ServiceReference reference) {
		IQuoteService service = (IQuoteService) context.getService(reference);
		thread = new MyThread(service);
		thread.start();
		return service;
	}

	@Override
	public void modifiedService(ServiceReference reference, Object service) {
		// removedService(reference, service);
		// addingService(reference);
	}

	@Override
	public void removedService(ServiceReference reference, Object service) {
		context.ungetService(reference);
		System.out.println("How sad. Service for quote is gone");
		thread.stopThread();
	}

	public static class MyThread extends Thread {

		private volatile boolean active = true;
		private final IQuoteService service;

		public MyThread(IQuoteService service) {
			this.service = service;
		}

		public void run() {
			while (active) {
				System.out.println(service.getQuote());
				try {
					Thread.sleep(5000);
				} catch (Exception e) {
					System.out.println("Thread interrupted " + e.getMessage());
				}
			}
		}

		public void stopThread() {
			active = false;
		}
	}

}

			

You also need to register a service tracker in your activator of your serviceconsumer.

				
package de.vogella.osgi.quoteconsumer;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.util.tracker.ServiceTracker;

import de.vogella.osgi.quote.IQuoteService;

public class Activator implements BundleActivator {

	private ServiceTracker serviceTracker;

	public void start(BundleContext context) throws Exception {
		System.out.println("Starting quoteconsumer bundles");
		// Register directly with the service
		MyQuoteServiceTrackerCustomizer customer = new MyQuoteServiceTrackerCustomizer(
				context);
		serviceTracker = new ServiceTracker(context, IQuoteService.class
				.getName(), customer);
		serviceTracker.open();
	}

	public void stop(BundleContext context) throws Exception {
		System.out.println("Stopping quoteconsumer bundles");
		serviceTracker.close();
	}

}

			

Export your bundle again. Start the OSGI console. Use the update command or the install command to get the new version of your bundle and start it. Once you start your service the tracker will be called and the consumer bundle will start writing messages to the console. Stop the service and verify that the consumer does not use the service anymore.

Declarative services (DS) allow to define and consume services via metadata (XML). Via DS you can define OSGi services without extending or implementing OSGi classes. This allows that these services can be tested independently of the OSGi runtime.

The "OSGi service component" is responsible for starting the service (service component). For the service consumer it is not visible if the service has been created via declarative service or via other means.

Service Components consists of an XML description (Component Description) and an object (Component Instance). The component description contains all information about the service component, e.g. the class name of the component instance and the service interface.

A reference to the component description is maintained in the "MANIFEST.MF" file. This file is read by the OSGi runtime and if a component description is found the corresponding service is created. The component description in the "MANIFEST.MF" file looks for example like the following:

				
Service-Component: component.xml, OSGI-INF/component.xml
			

To run declarative services you require the following bundles.

Typically component definitions are created in the project folder "OSGI-INF" via New → Other → Plug-in Development → Component Definition . The wizard will also add the Service-Component entry to the "MANIFEST.MF" file.

On the next page of the wizard, you can maintain the name of the component definition file, a name and the class which implements the services (or consumes the services).

If you press finish, the service editor opens.

On the service tab you can maintain provided services or referred services. For example to provide a service you would press "Add" under "Provided Services" and select the service interface you want to implement.

As a final step you would implement the class which would provide the service.

A correctly maintained component.xml would look like the following in XML.

				
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www./xmlns/scr/v1.1.0" name="de.vogella.osgi.ds.quoteservice">
   <implementation class="de.vogella.osgi.ds.quoteservice.QuoteService"/>
   <service>
      <provide interface="de.vogella.osgi.quote.IQuoteService"/>
   </service>
</scr:component>

			

This means that there is a component called "de.vogella.osgi.ds.quoteservice" which provides a service to the OSGI Service Registry under the interface "de.vogella.osgi.quote.IQuoteService". This component is implemented by the class "de.vogella.osgi.ds.quoteservice.QuoteService.

After the definition of the component your MANIFEST.MF would contain an entry to the service component.

				
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Quoteservice
Bundle-SymbolicName: de.vogella.osgi.ds.quoteservice
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Import-Package: de.vogella.osgi.quote
Service-Component: OSGI-INF/component.xml

			

The org.eclipse.equinox.ds bundle is the bundle which is responsible for reading the component meta data and registering services.

Therefore this bundle needs to start before the service becomes available.

You can ensure this in your run configuration by setting .ds bundle and the bundle which contains the new service to auto start.

Please note that using start levels to ensure the correct starting of the OSGi bundles is not a good approach, but other ways are even worse of have been unrealiable.

			
package de.vogella.osgi.ds.quoteservice;

import java.util.Random;

import de.vogella.osgi.quote.IQuoteService;

public class QuoteService implements IQuoteService {

	@Override
	public String getQuote() {
		Random random = new Random();
		// Create a number between 0 and 2
		int nextInt = random.nextInt(3);
		switch (nextInt) {
		case 0:
			return "Ds: Tell them I said something";
		case 1:
			return "Ds: I feel better already";
		default:
			return "Ds: Hubba Bubba, Baby!";
		}
	}

}

		

			
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www./xmlns/scr/v1.1.0" name="de.vogella.osgi.ds.quoteservice">
   <implementation class="de.vogella.osgi.ds.quoteservice.QuoteService"/>
   <service>
      <provide interface="de.vogella.osgi.quote.IQuoteService"/>
   </service>
</scr:component>

		

			
install file:c:\temp\bundles\plugins\org.eclipse.equinox.ds.jar
install file:c:\temp\bundles\plugins\org.eclipse.equinox.util.jar
install file:c:\temp\bundles\plugins\org.eclipse.osgi.services.jar

		

			
install file:c:\temp\bundles\plugins\de.vogella.osgi.ds.quoteservice.jar

		

			
package de.vogella.osgi.ds.quoteconsumer;

import de.vogella.osgi.quote.IQuoteService;

public class QuoteConsumer {
	private IQuoteService service;

	public void quote() {
		System.out.println(service.getQuote());
	}
	
	// Method will be used by DS to set the quote service
	public synchronized void setQuote(IQuoteService service) {
		System.out.println("Service was set. Thank you DS!");
		this.service = service;
		// I know I should not use the service here but just for demonstration
		System.out.println(service.getQuote());
	}

	// Method will be used by DS to unset the quote service
	public synchronized void unsetQuote(IQuoteService service) {
		System.out.println("Service was unset. Why did you do this to me?");
		if (this.service == service) {
			this.service = null;
		}
	}
}

		

Tip

Note that this class has no dependency to OSGi.

			
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www./xmlns/scr/v1.1.0" name="de.vogella.osgi.ds.quoteconsumer">
   <implementation class="de.vogella.osgi.ds.quoteconsumer.QuoteConsumer"/>
   <reference bind="setQuote" cardinality="1..1" interface="de.vogella.osgi.quote.IQuoteService" name="IQuoteService" policy="static" unbind="unsetQuote"/>
</scr:component>

		

			
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Quoteconsumer
Bundle-SymbolicName: de.vogella.osgi.ds.quoteconsumer
Bundle-Version: 1.0.4
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Import-Package: de.vogella.osgi.quote
Service-Component: OSGI-INF/component.xml

		

Source Code of Examples

http://www. OSGi Homepage

http://www./equinox Equinox Homepage

http://www./equinox/documents/quickstart.php Equinox Quickstart guide

http://www.ibm.com/developerworks/opensource/library/os-osgiblueprint/ OSGi Blueprint services

Eclipse RCP Training (German) Eclipse RCP Training with Lars Vogel

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java and compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put everything you have under distributed version control system