View source for Tutorial: Building your first OSGi Remote Service

==Introduction==

The OSGi Alliance specifies a very simple model to expose arbitrary services within a local runtime.  As of OSGi 4.2, however, also available is a specification of how to use this service model for remote services (Chapter 100 in the EEG specification)...services that are exported by a distribution provider, and allow remote access by multiple client/consumers.  

This tutorial will guide the reader through

#Defining and implementing an OSGi remote service
#Exposing that service for remote access via OSGi Remote Services standard, using the implementation provided by the Eclipse Communication Project (ECF)

==Define the Service==

The key to building a system with low coupling and high cohesion is to create clear and coherent boundaries between different parts of your system.  Central to this is defining simple, clear interfaces between subsystems...to allow the subsystems to interact as needed, but only in clearly defined ways.  

For example, here's a simple time service:

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
package com.mycorp.examples.timeservice;

public interface ITimeService {

	public Long getCurrentTime();

}
</source>
</div>

The purpose of this service is simply to provide the current time...in the form of a long value specifying the number of milliseconds since 1970 returned from a call to '''getCurrentTime()'''.  Of course, declarations of much more complex services are possible, with multiple methods, multiple arguments for each method, and complex types as arguments and return values.  In short, any java interface can be used as the service interface.  OSGi also allows the use of multiple interfaces exposed by a single implementation.

With OSGi services it's a best practice to put the service interface (and any class referred to by the service interface) in a distinct bundle.  This creates a clear, modular, framework-enforced separation between the service API, the service implementation, and any code that uses the service.   This minimizes the coupling between subsystems.  For Remote Services such separation and low-coupling is particularly important, since the host implementation is in a separate process from the service client/consumers...making it highly desirable to minimize the coupling and clarify the interface between systems.

[http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice Here is a complete source for the bundle with the ITimeService interface class].   The package containing this class is exported via the [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice/META-INF/MANIFEST.MF manifest] so that the Host and Consumer bundles (below) can refer to the service interface in their own code.

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
Export-Package: com.mycorp.examples.timeservice;version="1.0.0"
</source>
</div>

Note also the version information associated with the package...OSGi Remote Services supports versioning of service interfaces.  Being able to version service interfaces, and have the underlying framework automatically restrict the service binding to compatible versions is a very useful feature for enhancing and maintaining APIs over time.

==Service Host: Implement the Service==

Next, it's necessary to create a service 'host' implementing the '''ITimeService''' interface.   

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
package com.mycorp.examples.timeservice.host;

import com.mycorp.examples.timeservice.ITimeService;

public class TimeServiceImpl implements ITimeService {

	public Long getCurrentTime() {
		return new Long(System.currentTimeMillis());
	}
}
</source>
</div>

This implementation simply returns the local system's current time.  To refer to the '''ITimeService''' service the host bundle manifest must import the '''com.mycorp.examples.timeservice''' package from the bundle defined above by adding a line like this to the host bundle manifest:

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
Import-Package: com.mycorp.examples.timeservice;version="1.0.0",
</source>
</div>

==Service Host: Register the Service==

In the OSGi Service model it's necessary to '''register''' the service with the OSGi service registry.   There are multiple ways of registering a service...programmatically java code,  declaratively via Declarative Services (DS).   For introductions about various approaches to register an OSGi Service see [http://www.vogella.com/articles/OSGiServices/article.html Vogella's OSGi Services Tutorial].  For this tutorial we will register our TimeServiceImpl via a single line of java code:

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
bundleContext.registerService(ITimeService.class, new TimeServiceImpl(),null);
</source>
</div>

With a local OSGi Service the above line is all that's necessary to register the service.   For a Remote Service, a little more is required to trigger the distribution provider to export the service:

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
Dictionary<String, String> props = new Hashtable<String, String>();
// OSGi Standard Property - indicates which of the interfaces of the service will be exported.  '*' means 'all'.
props.put("service.exported.interfaces", "*");
// OSGi Standard Property - indicates which provider config(s) will be used to export the service
props.put("service.exported.configs","ecf.generic.server");
// Optional ECF Generic Provider Configuration Property
props.put("ecf.generic.server.id","ecftcp://localhost:3288/server");
// Register a new TimeServiceImpl with the above props
bundleContext.registerService(ITimeService.class, new TimeServiceImpl(), props); 
</source>
</div>

With an OSGi RS distribution provider present, adding these service properties will trigger the export of the service.   Here's an explanation of each of the service props:

With the ECF RS implementation present in the host runtime, adding these service properties will result in the following occurring before the registerService call returns:

#The TimeServiceImpl will be exported via the distribution provider identified via config..i.e. "ecf.generic.server"
#The exported service will be published for discovery, using any installed and available network discovery providers

The full source for the host bundle, with the host implementation and registration code can be found in the [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice.host com.mycorp.examples.timeservice.host project].

Note that there are no references to additional OSGi classes...or ECF classes...but rather only classes exposed by the service interface (in this case '''ITimeService''').  For all of the remoting information, standardized service properties are used to qualify the '''ITimeService''' API as a remote service, and to select and configure a remote services provider.  This provides a great deal of flexibility to the '''ITimeService''' implementer, and allows the dynamic selection and use of a variety of distribution providers...from ECF or not...and multiple configurations.

==Consumer:  Discover and Use the Service==

For consumers to use a remote service they must first discover the service.  With OSGi Remote Services this discovery can be accomplished several ways.   The easiest and most automatic is to use a network discovery protocol, such that when the remote service is exported by a host and published via a network discovery protocol (as described above), a consumer can then automatically discover the remote service over the network.

For this tutorial, we'll assume that ECF's Zeroconf implementation is present, meaning that if the remote service host and consumer are on the same LAN, the consumer will automatically discover the remote service via the Zeroconf network discovery protocol.  Using Zeroconf for network discovery, one can simply use OSGi Declarative Services to inject the service into client code and then call the timeService.getCurrentTime() method:

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
package com.mycorp.examples.timeservice.consumer.ds;

import com.mycorp.examples.timeservice.ITimeService;

public class TimeServiceComponent {

	void bindTimeService(ITimeService timeService) {
		System.out.println("Discovered ITimeService via DS");
		// Call the service and print out result!
		System.out.println("Current time is: " + timeService.getCurrentTime());  // Call the ITimeService remote service
	}
}
</source>
</div>

OSGi Declarative Services will automatically inject the '''ITimeService''' proxy by calling the bindTimeService method when the remote service is discovered.  

As with the host, to refer to the '''ITimeService''' the consumer must import the '''com.mycorp.examples.timeservice''' package by importing the package via it's manifest:

<div style="background-color: #fafafa; padding: 20px; border-color: #ddd; border-width: 3px; border-style: solid; border-radius: 5px; margin-left: 10px; margin-right: 10px; overflow-x: auto;">
<source lang="java">
Import-Package: com.mycorp.examples.timeservice;version="1.0.0",
</source>
</div>

The only other requirement for the consumer is to have DS markup so that DS can call '''bindTimeService''' when the '''ITimeService''' proxy is registered by the consumer's distribution provider.  The required DS markup is available in [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice.consumer.ds/OSGI-INF/timeservicecomponent.xml this xml file].

The complete project for this consumer (TimeServiceComponent class, DS markup, and manifest.mf) [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice.consumer.ds is available here].  

With the three bundles defined...i.e. 

#[http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice the service interface bundle]
#[http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice.host the host bundle]
#[http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice.consumer.ds the consumer bundle]

along with the ECF remote service implementation, we may now run the '''ITimeService''' host implementation. The consumer can then be run...to discovery, inject, and to use the '''ITimeService'''.

==Starting the Host==

In the com.mycorp.examples.timeservice.host project, in the launch directory is a launch config named TimeServiceHost.launch.  In Eclipse, you can launch the host by right-clicking on this launch config and choosing '''Run As -> TimeServiceHost'''.  In the console output, you should see something like this

<pre>
osgi> MyTimeService host registered with registration={com.mycorp.examples.timeservice.ITimeService}=...
Service Exported by RemoteServiceAdmin.  EndpointDescription Properties=...
</pre>

This indicates that the service was registered and exported by ECF's remote service implementation.

==Starting the Consumer to Execute the Remote Service==

In the com.mycorp.examples.timeservice.consumer.ds project, in the launch directory is a launch config named TimeServiceConsumer DS.launch.  In Eclipse, you may launch the consumer by right-clicking on this launch config and choosing '''Run As -> TimeServiceConsumer DS'''.  In the console output, you should immediately see:

<pre>
osgi>
</pre>

But then after a few seconds (for the Zeroconf discovery protocol to operate) the service will be discovered, proxy created and injected into the TimeServiceComponent, resulting in console output:

<pre>
osgi> Discovered ITimeService via DS
Current time is: 1386354647672
</pre>

As well as host console output:

<pre>
TimeServiceImpl.  Received call to getCurrentTime()
</pre>

This constitutes a successful test of the time service.

==Background and Related Articles==

[[EIG:Download|Download ECF Remote Services/RSA Implementation]]

[[EIG:Add to Target Platform|How to Add Remote Services/RSA to Your Target Platform]]

[[Getting Started with ECF's OSGi Remote Services Implementation]]

[[OSGi Remote Services and ECF]]

[[Remote Services Admin|OSGi Remote Service Admin (RSA) Management Agent]]

[[Asynchronous Proxies for Remote Services]]

[[File-based Discovery | Static File-based Discovery of Remote Service Endpoints]]