Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "ECF/Getting Started with Remote Services API"

< ECF
(→‎Asynchronous Remote Method Invocation)
 
(13 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
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).  
 
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===
 
===Service Interface===
  
−
As with any OSGi service, you must first define your service interface.  Here is a trivial example 'hello' 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;
 
<source lang="java">package org.eclipse.ecf.examples.remoteservices.hello;
Line 11: Line 13:
 
public interface IHello {
 
public interface IHello {
  
−
public void hello(String from);
+
public String hello(String from);
 
 
 
}
 
}
 
</source>
 
</source>
  
−
This service is defined, along with a simple implementation, in this project in CVS
+
[[Getting the Hello Example Remote Service | Click here to retrieve the Hello Example source into your local workspace]]
−
 
+
−
cvs: ''':pserver:anonymous@dev.eclipse.org:/cvsroot/rt'''<br>
+
−
modules: '''org.eclipse.ecf/examples/bundles/org.eclipse.ecf.examples.remoteservices.hello''', '''org.eclipse.ecf/examples/bundles/org.eclipse.ecf.examples.remoteservices.hello.host.rs''', '''org.eclipse.ecf/examples/bundles/org.eclipse.ecf.examples.remoteservices.hello.consumer.rs'''
+
−
 
+
−
Here is a [[Media:Hellors.psf|project set file]] for these projects.
+
−
 
+
−
The service interface above is contained in the o.e.e.e.remoteservices.hello bundle, along with a trivial implementation (in org.eclipse.ecf.examples.remoteservices.hello.impl.Hello).
+
  
 
===Registering the Service (Host)===
 
===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 RFC119 implementation:
+
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">
 
<source lang="java">
Line 86: Line 81:
 
IRemoteServiceReference[] helloReferences = containerAdapter
 
IRemoteServiceReference[] helloReferences = containerAdapter
 
.getRemoteServiceReferences(IDFactory.getDefault().createID(
 
.getRemoteServiceReferences(IDFactory.getDefault().createID(
−
container.getConnectNamespace(), RSGI_SERVICE_HOST),
+
container.getConnectNamespace(), ROSGI_SERVICE_HOST),
 
IHello.class.getName(), null);
 
IHello.class.getName(), null);
 
Assert.isNotNull(helloReferences);
 
Assert.isNotNull(helloReferences);
Line 96: Line 91:
 
IHello proxy = (IHello) remoteService.getProxy();
 
IHello proxy = (IHello) remoteService.getProxy();
 
// 6. Finally...call the proxy
 
// 6. Finally...call the proxy
−
proxy.hello("RemoteService Consumer");
+
String response = proxy.hello("RemoteService Consumer");
  
 
}
 
}
Line 121: Line 116:
 
===Asynchronous Remote Method Invocation===
 
===Asynchronous Remote Method Invocation===
  
−
Sometimes it's desirable to invoke remote methods asynchronously, without blocking until the remote method call completes.  This is sometimes desirable, for example, if your user interface thread is doing the calling, as remote methods can/could block for a much longer time than would be acceptable for users.
+
New: See support for [[Asynchronous Remote Services]]
  
−
ECF remote services provides an API to invoke remote methods with a guarantee that they will be executed asynchronously, in some other thread, and allowing the calling thread not to be blocked.
 
  
−
This capability is exposed via the IRemoteService.  Here is the example code on the consumer to invoke the hello service asynchronously (non-blocking)
+
===Related Documentation===
  
−
<source lang="java">
+
[[Asynchronous Remote Services]]
−
//Invoke callAsync
+
−
remoteService.callAsync(createRemoteCall(), createRemoteCallListener());
+
−
System.out.println("callAsync invoked");
+
−
 
+
−
 
+
−
IRemoteCall createRemoteCall() {
+
−
return new IRemoteCall() {
+
−
 
+
−
public String getMethod() {
+
−
return "hello";
+
−
}
+
−
 
+
−
public Object[] getParameters() {
+
−
return new Object[] { "Asynch RemoteService Consumer" };
+
−
}
+
−
 
+
−
public long getTimeout() {
+
−
return 0;
+
−
}
+
−
};
+
−
}
+
−
 
+
−
IRemoteCallListener createRemoteCallListener() {
+
−
return new IRemoteCallListener() {
+
−
 
+
−
public void handleEvent(IRemoteCallEvent event) {
+
−
if (event instanceof IRemoteCallCompleteEvent) {
+
−
IRemoteCallCompleteEvent cce = (IRemoteCallCompleteEvent) event;
+
−
if (!cce.hadException())
+
−
System.out
+
−
.println("Remote call completed successfully!");
+
−
else
+
−
System.out
+
−
.println("Remote call completed with exception: "
+
−
+ cce.getException());
+
−
}
+
−
}
+
−
};
+
−
}
+
−
 
+
−
</source>
+
−
 
+
−
When run, this produces output like this on the client
+
−
 
+
−
<pre>
+
−
callAsync invoked
+
−
Remote call completed successfully!
+
−
</pre>
+
  
−
As you can see from the ordering of the messages in the output, the callAsync method completes '''before''' the asynchronous remote call
+
[[Distributed OSGi Services with ECF]]
−
actually completes.  When the call actually completes the IRemoteCallListener is called back via some other thread and the "Remote call completed successfully!" is then printed.
+
  
 +
[[Getting Started with ECF's RFC119 Implementation]]
  
 +
[[Disabling R-OSGi]]
  
 +
[[R-OSGi_Properties]]
  
 +
[[Distributed EventAdmin Service]]
  
 
{{ECF}}
 
{{ECF}}
 
[[Category:Eclipse Communication Framework]]
 
[[Category:Eclipse Communication Framework]]
 
[[Category:EclipseRT]]
 
[[Category:EclipseRT]]
 +
[[Category:Draft Documentation]]

Latest revision as of 03:56, 16 July 2011

Install ECF 3.0. See ecf download.

In addition you will need Equinox in your target platform (either the 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: 

package org.eclipse.ecf.examples.remoteservices.hello;
 
public interface IHello {
 
	public String hello(String from);
 
}

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: 

	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");
	}

This code does the following:

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

Here is the expected output to the console for this host 

osgi> IHello RemoteService registered

If you get the following warning when starting the host: 

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

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 

	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");
 
	}

This code

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

The output on the remote service host is 

osgi> IHello RemoteService registered
hello from=RemoteService Consumer

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

Eclipse Communication Framework
API
API Documentation • Javadoc • Providers
Development
Development Guidelines • Integrators Guide
Retrieved from "https://wiki.eclipse.org/index.php?title=ECF/Getting_Started_with_Remote_Services_API&oldid=261459"

This page was last modified 03:56, 16 July 2011 by Hendy Irawan. Based on work by Scott Lewis and Scott Lewis.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.