Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "ECF/Getting Started with Remote Services API"
(→Service Interface) |
|||
Line 72: | Line 72: | ||
<source lang="java"> | <source lang="java"> | ||
+ | public static final String ROSGI_SERVICE_HOST = "r-osgi://localhost:9278"; | ||
+ | |||
public void start(BundleContext context) throws Exception { | public void start(BundleContext context) throws Exception { | ||
this.context = context; | this.context = context; | ||
− | // Create R-OSGi Container | + | // 1. Create R-OSGi Container |
IContainerManager containerManager = getContainerManagerService(); | IContainerManager containerManager = getContainerManagerService(); | ||
container = containerManager.getContainerFactory().createContainer( | container = containerManager.getContainerFactory().createContainer( | ||
"ecf.r_osgi.peer"); | "ecf.r_osgi.peer"); | ||
− | // Get remote service container adapter | + | // 2. Get remote service container adapter |
IRemoteServiceContainerAdapter containerAdapter = (IRemoteServiceContainerAdapter) container | IRemoteServiceContainerAdapter containerAdapter = (IRemoteServiceContainerAdapter) container | ||
.getAdapter(IRemoteServiceContainerAdapter.class); | .getAdapter(IRemoteServiceContainerAdapter.class); | ||
− | // Lookup IRemoteServiceReference | + | // 3. Lookup IRemoteServiceReference |
IRemoteServiceReference[] helloReferences = containerAdapter | IRemoteServiceReference[] helloReferences = containerAdapter | ||
.getRemoteServiceReferences(IDFactory.getDefault().createID( | .getRemoteServiceReferences(IDFactory.getDefault().createID( | ||
Line 88: | Line 90: | ||
Assert.isNotNull(helloReferences); | Assert.isNotNull(helloReferences); | ||
Assert.isTrue(helloReferences.length > 0); | Assert.isTrue(helloReferences.length > 0); | ||
− | // Get remote service for reference | + | // 4. Get remote service for reference |
IRemoteService remoteService = containerAdapter | IRemoteService remoteService = containerAdapter | ||
.getRemoteService(helloReferences[0]); | .getRemoteService(helloReferences[0]); | ||
− | // Get the proxy | + | // 5. Get the proxy |
IHello proxy = (IHello) remoteService.getProxy(); | IHello proxy = (IHello) remoteService.getProxy(); | ||
− | // Finally...call the proxy | + | // 6. Finally...call the proxy |
proxy.hello("RemoteService Consumer"); | proxy.hello("RemoteService Consumer"); | ||
Line 103: | Line 105: | ||
#Creates a container r-osgi container instance. | #Creates a container r-osgi container instance. | ||
#Gets the remote service container adapter. | #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 the IRemoteService for the given IRemoteServiceReference. | ||
#Gets a proxy via the IRemoteService.getProxy(), and casts it to the IHello interface. | #Gets a proxy via the IRemoteService.getProxy(), and casts it to the IHello interface. | ||
Line 115: | Line 117: | ||
</pre> | </pre> | ||
+ | the 'hello from=RemoteService Consumer' is the host receiving the remote method call. | ||
+ | |||
+ | ===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. | ||
+ | |||
+ | 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 instance | ||
{{ECF}} | {{ECF}} | ||
[[Category:Eclipse Communication Framework]] | [[Category:Eclipse Communication Framework]] | ||
[[Category:EclipseRT]] | [[Category:EclipseRT]] |
Revision as of 12:49, 25 June 2009
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).
Contents
Service Interface
As with any OSGi service, you must first define your service interface. Here is a trivial example 'hello' service interface:
package org.eclipse.ecf.examples.remoteservices.hello; public interface IHello { public void hello(String from); }
This service is defined, along with a simple implementation, in this project in CVS
cvs: :pserver:anonymous@dev.eclipse.org:/cvsroot/rt
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 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)
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:
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:
- 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
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(), RSGI_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 proxy.hello("RemoteService Consumer"); }
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
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
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.
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 instance
Eclipse Communication Framework |
API |
API Documentation • Javadoc • Providers |
Development |
Development Guidelines • Integrators Guide |