View source for ECF/Getting Started with Remote Services API

Install ECF 3.0. See [http://www.eclipse.org/ecf/downloads.php ecf download].

In addition you will need Equinox in your target platform (either the [http://download.eclipse.org/equinox/ Equinox 3.5 SDK] or the parts that come with Eclipse). 

To see how the ECF Remote Services API fits into the overall picture of supporting Distributed OSGi, see [[Distributed OSGi Services with ECF]].

===Service Interface===

As with any OSGi service, you must first define your service interface.  Here is a example 'hello' service interface:

<source lang="java">package org.eclipse.ecf.examples.remoteservices.hello;

public interface IHello {

	public String hello(String from);
	
}
</source>

[[Getting the Hello Example Remote Service | Click here to retrieve the Hello Example source into your local workspace]]

===Registering the Service (Host)===

Here is the code in org.eclipse.ecf.internal.examples.remoteservices.hello.host.rs.Activator that registers a remote service with the ECF Remote Service API:

<source lang="java">
	public void start(BundleContext context) throws Exception {
		this.context = context;
		// Create R-OSGi Container
		IContainerManager containerManager = getContainerManagerService();
		container = containerManager.getContainerFactory().createContainer(
				"ecf.r_osgi.peer");
		// Get remote service container adapter
		IRemoteServiceContainerAdapter containerAdapter = (IRemoteServiceContainerAdapter) container
				.getAdapter(IRemoteServiceContainerAdapter.class);
		// Register remote service
		serviceRegistration = containerAdapter.registerRemoteService(
				new String[] { IHello.class.getName() }, new Hello(), null);
		System.out.println("IHello RemoteService registered");
	}
</source>

This code does the following:

# Creates an r-osgi ECF container to do the distribution.
# Gets the containerAdapter from the container instance so that remote services can be registered/accessed.
# Creates and registers the IHello implementation.

Here is the expected output to the console for this host

<pre>
osgi> IHello RemoteService registered
</pre>

If you get the following warning when starting the host:

<pre>
osgi> WARNING: Port 9278 already in use. This instance of R-OSGi is running on port 9279
</pre>

This means that there is some other R-OSGi instance running on that same system, and that port 9278 is not available for use by the host.  In this case, you need to stop the host, and disable the other R-OSGi instance before running the host again.  To disable R-OSGI, see [[Disabling R-OSGi]] and [[R-OSGI Properties]].

===Using the Service (Consumer)===

The ECF remote services API consumer essentially needs to lookup the remote reference, and then use the 
Here is code from org.eclipse.ecf.internal.examples.remoteservices.hello.consumer.rs.Activator

<source lang="java">
	public static final String ROSGI_SERVICE_HOST = "r-osgi://localhost:9278";

	public void start(BundleContext context) throws Exception {
		this.context = context;
		// 1. Create R-OSGi Container
		IContainerManager containerManager = getContainerManagerService();
		container = containerManager.getContainerFactory().createContainer(
				"ecf.r_osgi.peer");
		// 2. Get remote service container adapter
		IRemoteServiceContainerAdapter containerAdapter = (IRemoteServiceContainerAdapter) container
				.getAdapter(IRemoteServiceContainerAdapter.class);
		// 3. Lookup IRemoteServiceReference
		IRemoteServiceReference[] helloReferences = containerAdapter
				.getRemoteServiceReferences(IDFactory.getDefault().createID(
						container.getConnectNamespace(), ROSGI_SERVICE_HOST),
						IHello.class.getName(), null);
		Assert.isNotNull(helloReferences);
		Assert.isTrue(helloReferences.length > 0);
		// 4. Get remote service for reference
		IRemoteService remoteService = containerAdapter
				.getRemoteService(helloReferences[0]);
		// 5. Get the proxy
		IHello proxy = (IHello) remoteService.getProxy();
		// 6. Finally...call the proxy
		String response = proxy.hello("RemoteService Consumer");

	}
</source>

This code

#Creates a container r-osgi container instance.
#Gets the remote service container adapter.
#Looks up IRemoteServiceReference array for the IHello service using ID with value 'r-osgi://localhost:9278'.
#Gets the IRemoteService for the given IRemoteServiceReference.
#Gets a proxy via the IRemoteService.getProxy(), and casts it to the IHello interface.
#Makes the remote call (proxy.hello("RemoteService Consumer")

The output on the remote service host is

<pre>
osgi> IHello RemoteService registered
hello from=RemoteService Consumer
</pre>

the 'hello from=RemoteService Consumer' is the host receiving the remote method call.

===Asynchronous Remote Method Invocation===

New: See support for [[Asynchronous Remote Services]]


===Related Documentation===

[[Asynchronous Remote Services]]

[[Distributed OSGi Services with ECF]]

[[Getting Started with ECF's RFC119 Implementation]]

[[Disabling R-OSGi]]

[[R-OSGi_Properties]]

[[Distributed EventAdmin Service]]

{{ECF}}
[[Category:Eclipse Communication Framework]]
[[Category:EclipseRT]]
[[Category:Draft Documentation]]