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 "EIG:Remoting"

(Asynchronouse Remote Services (not yet OSGi standard))
(Asynchronouse Remote Services (not yet OSGi standard))
 
(31 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Creating an OSGi Service<br>  ==
+
==[[EIG:Integrators Guide|Remoting]]==
 +
When we talk about services, we really talk about Java objects. We just call them services because of the way we use these Java objects. [http://www.google.com/search?q=soa+patterns Google for "SOA Patterns"] for more information on this topic. These Java objects are POJO's, as far as ECF is concerned. There is no need to implement anything from ECF in order for the "service" to be exposed as a remote service. The process to make a Java object (slash service) available on a remote machine is the mechanism we call "Remoting".
  
 +
__TOC__
 +
 +
===Creating an OSGi Service===
 
OSGi Services should be defined by/registered under a specific interface.<br>  
 
OSGi Services should be defined by/registered under a specific interface.<br>  
 
<source lang="java">public interface MyService {
 
<source lang="java">public interface MyService {
Line 18: Line 22:
 
</source>
 
</source>
  
== Registering an OSGi Remote Service<br>  ==
+
=== Registering an OSGi Remote Service<br>  ===
  
 
The registration of an OSGi Remote Service is nearly the same as with any regular service in an OSGi Framework (e.g. Eclipse Equinox). The only additional thing you need to do is setting some service properties. For the Eclipse Communication Framework (ECF) only two properties are required: The "service.exported.interfaces" property marks the service for export (as an OSGi Remote Service) and defines under which interfaces this service can be exported. The "service.exported.configs" property is a list of configuration types (endpoint types) that should be used to export the service. The other properties are optional settings for the distribution provider.<br>  
 
The registration of an OSGi Remote Service is nearly the same as with any regular service in an OSGi Framework (e.g. Eclipse Equinox). The only additional thing you need to do is setting some service properties. For the Eclipse Communication Framework (ECF) only two properties are required: The "service.exported.interfaces" property marks the service for export (as an OSGi Remote Service) and defines under which interfaces this service can be exported. The "service.exported.configs" property is a list of configuration types (endpoint types) that should be used to export the service. The other properties are optional settings for the distribution provider.<br>  
Line 33: Line 37:
 
| service.exported.configs  
 
| service.exported.configs  
 
| String+
 
| String+
| "ecf.generic.server" or "ecf.r_osgi.peer"  
+
| "ecf.generic.server", "ecf.r_osgi.peer" etc.
 
| Types of endpoints that should be used for the export of the service. Distribution Providers create endpoints for each type they support. See the [[ECF_Providers|list of Distribution Providers]] for all of the supported Providers and their configuration.
 
| Types of endpoints that should be used for the export of the service. Distribution Providers create endpoints for each type they support. See the [[ECF_Providers|list of Distribution Providers]] for all of the supported Providers and their configuration.
 
|-
 
|-
Line 72: Line 76:
 
         Activator.context = bundleContext;
 
         Activator.context = bundleContext;
  
         // Instantiate a service instance
+
         // Instantiate a service
 
         this.myService = new MyServiceImpl();
 
         this.myService = new MyServiceImpl();
  
Line 86: Line 90:
 
         if(this.myServiceRegistration != null) {
 
         if(this.myServiceRegistration != null) {
 
             this.myServiceRegistration.unregister();
 
             this.myServiceRegistration.unregister();
            this.myServiceRegistration = null;
 
            this.myService = null;
 
 
         }
 
         }
 +
        this.myServiceRegistration = null;
 +
        this.myService = null;
 
     }
 
     }
  
Line 94: Line 98:
 
</source>
 
</source>
  
== Using OSGi Remote Services<br>  ==
+
=== Using OSGi Remote Services ===
  
 
If you would like to use OSGi Remote Services this is as simple as with regular services in the framework. You don't need to do anything different as usual, all remote services discovered by an ECF Discovery Provider are registered with the service registry of your OSGi Framework. So you either use the "getServiceReference(s)" method of your bundle context or create a service tracker for your service.<br>  
 
If you would like to use OSGi Remote Services this is as simple as with regular services in the framework. You don't need to do anything different as usual, all remote services discovered by an ECF Discovery Provider are registered with the service registry of your OSGi Framework. So you either use the "getServiceReference(s)" method of your bundle context or create a service tracker for your service.<br>  
Line 100: Line 104:
 
If you have local and remote services of the same type (e.g. registered under the same interface) in your OSGi Framework, local services can be filtered out by using an LDAP filter on the property "service.imported".  
 
If you have local and remote services of the same type (e.g. registered under the same interface) in your OSGi Framework, local services can be filtered out by using an LDAP filter on the property "service.imported".  
  
=== Example: Service Reference<br>  ===
+
===Example: Service Reference===
 
<source lang="java">ServiceReference myServiceReference = bundleContext.getServiceReference(MyServiceInterface.class.getName());
 
<source lang="java">ServiceReference myServiceReference = bundleContext.getServiceReference(MyServiceInterface.class.getName());
 
if(myServiceReference != null) {
 
if(myServiceReference != null) {
Line 150: Line 154:
 
</source>
 
</source>
  
== Asynchronouse Remote Services (not yet OSGi standard)<br>  ==
+
=== Asynchronous Remote Services (not OSGi standard) ===
  
Usualy Remote Procedure Calls operates synchonously. However, ECF provides an API for asynchronouse calls that are executed in some other thread and don't block. 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.<br>  
+
Usualy Remote Procedure Calls operates synchronously. ECF provides an API for asynchronous calls that are executed in some other thread and don't block. 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.<br>  
  
For the Implementation of an asynchronouse Remote Service the only thing you need to do is implementing an additional interface for your service. This interface should extend the IAsyncRemoteServiceProxy interface with an "Async" added to the interface name. This interface then should map all of the methods of your original interface with "Async" added to the method name and an additional callback parameter. Also this interface must be located in the same(!) package as the original interface of your service.<br>
+
This asynchronous Remote Service implementation is no OSGi standard. For background on the discussion about asynchronous remote services invocation in general and possible future standardization by the OSGI standards organization see [http://www.osgi.org/blog/2010/04/calling-your-cake-and-sending-it-too.html Peter Kriens blog entry], and [http://eclipseecf.blogspot.com/2010/04/osgi-remote-services-and-ecf.html Scott Lewis' blog entry].<br>  
  
The callback parameter should be an instance of the IAsyncCallback&lt;?&gt; interface with the original return type of your method as generic type parameter.<br>
+
For the Implementation of an asynchronous Remote Service the only thing you need to do is implementing an additional interface for your service. This interface should extend the IAsyncRemoteServiceProxy interface with an "Async" added to the interface name. This interface then should map all of the methods of your original interface with "Async" added to the method name and an additional callback parameter. Also this interface must be located in the same(!) package as the original interface of your service. The last parameter of the asynchronous method should then be an instance of the IAsyncCallback&lt;?&gt; interface with the original return type of your method as generic type parameter.<br>
  
Another approach (next to IAsyncCallback&lt;?&gt;) to achieving asynchronous invocation of remote services are futures.  Future objects allow the consumer to perform operations in between initiating a remote call and receiving a result.
+
Another approach (next to IAsyncCallback&lt;?&gt;) to achieving asynchronous invocation of remote services are futures.  Future objects allow the consumer to perform operations in between initiating a remote call and receiving a result.<br>
 +
 
 +
Both of these approaches can be used seperate and also togehter.
  
 
<source lang="java">public interface MyServiceAsync extends IAsyncRemoteServiceProxy {
 
<source lang="java">public interface MyServiceAsync extends IAsyncRemoteServiceProxy {
 
      
 
      
 
     public void helloAsync(String name, IAsyncCallback<String> callback);
 
     public void helloAsync(String name, IAsyncCallback<String> callback);
 
+
    // and/or
 
     public IFuture helloAsync(String name);
 
     public IFuture helloAsync(String name);
  
 
}
 
}
 
</source>
 
</source>
Note that with this you will have direct dependencies to ECF bundles. Also some of the distribution providers still don't handle the registration of multiple interfaces correctly.  
+
Note that with this you will have direct dependencies to ECF bundles. Also some of the distribution providers still don't handle the registration of multiple interfaces correctly.
  
 
=== Example ===
 
=== Example ===
 
<source lang="java">if(myService instanceof MyServiceAsync) {
 
<source lang="java">if(myService instanceof MyServiceAsync) {
     System.out.println((MyServiceAsync)myService.helloAsync("Beavis", new MyServiceCallback()));
+
     ((MyServiceAsync)myService).helloAsync("Beavis", new MyServiceCallback());
 
}
 
}
 
</source>
 
</source>
Line 195: Line 201:
 
This initiates a remote call, performs some additional local operations and then gets a result from the future.
 
This initiates a remote call, performs some additional local operations and then gets a result from the future.
 
<source lang="java">
 
<source lang="java">
IFuture future = myServiceInterface.helloAsync("Beavis");
+
IFuture future = ((MyServiceAsync)myService).helloAsync("Beavis");
 
// Do other local operations here...
 
// Do other local operations here...
 
String result = (String) future.get();
 
String result = (String) future.get();
</source>
+
System.out.println(result);
 
+
== Implementing an ECF Distribution Provider  ==
+
 
+
[...]
+
 
+
== Topology Management  ==
+
 
+
[...]
+
 
+
<source lang="java">
+
public interface IHostContainerFinder {
+
public IRemoteServiceContainer[] findHostContainers(ServiceReference serviceReference, String[] serviceExportedInterfaces, String[] serviceExportedConfigs, String[] serviceIntents);
+
}
+
</source>
+
<source lang="java">
+
[...]
+
 
</source>
 
</source>

Latest revision as of 01:10, 24 January 2013

Remoting

When we talk about services, we really talk about Java objects. We just call them services because of the way we use these Java objects. Google for "SOA Patterns" for more information on this topic. These Java objects are POJO's, as far as ECF is concerned. There is no need to implement anything from ECF in order for the "service" to be exposed as a remote service. The process to make a Java object (slash service) available on a remote machine is the mechanism we call "Remoting".

Creating an OSGi Service

OSGi Services should be defined by/registered under a specific interface.

public interface MyService {
 
    public String hello(String name);
 
}

There should then exist some implementation of this service:

public class MyServiceImpl implements MyService {
 
    public String hello(String name) {
        return "Hi " + name + "! My name is Budhead.";
    }
 
}

Registering an OSGi Remote Service

The registration of an OSGi Remote Service is nearly the same as with any regular service in an OSGi Framework (e.g. Eclipse Equinox). The only additional thing you need to do is setting some service properties. For the Eclipse Communication Framework (ECF) only two properties are required: The "service.exported.interfaces" property marks the service for export (as an OSGi Remote Service) and defines under which interfaces this service can be exported. The "service.exported.configs" property is a list of configuration types (endpoint types) that should be used to export the service. The other properties are optional settings for the distribution provider.

Service Properties

Property Name Type Example Description
service.exported.configs String+ "ecf.generic.server", "ecf.r_osgi.peer" etc. Types of endpoints that should be used for the export of the service. Distribution Providers create endpoints for each type they support. See the list of Distribution Providers for all of the supported Providers and their configuration.
service.exported.intents String+ Intents that the distribution provider must implement.
service.exported.intents.extra String+ Configurable intents the distribution provider must implement (based on a topology).
service.exported.interfaces String+ "*" Interfaces to export.
service.intents String+ Intents that are already implemented by the exported service implementation.

Example

public class Activator implements BundleActivator {
 
    private MyService myService = null;
    private ServiceRegistration myServiceRegistration = null;
 
    private static BundleContext context;
 
    public static BundleContext getContext() {
        return context;
    }
 
    public void start(BundleContext bundleContext) throws Exception {
        Activator.context = bundleContext;
 
        // Instantiate a service
        this.myService = new MyServiceImpl();
 
        // Register the service instance as an OSGi Remote Service
        Properties props = new Properties();
        props.put("service.exported.interfaces", "*");
        props.put("service.exported.configs", "ecf.r_osgi.peer");
        this.myServiceRegistration = bundleContext.registerService(MyService.class.getName(), this.myService, props);
    }
 
    public void stop(BundleContext bundleContext) throws Exception {
        // Unregister the service
        if(this.myServiceRegistration != null) {
            this.myServiceRegistration.unregister();
        }
        this.myServiceRegistration = null;
        this.myService = null;
    }
 
}

Using OSGi Remote Services

If you would like to use OSGi Remote Services this is as simple as with regular services in the framework. You don't need to do anything different as usual, all remote services discovered by an ECF Discovery Provider are registered with the service registry of your OSGi Framework. So you either use the "getServiceReference(s)" method of your bundle context or create a service tracker for your service.

If you have local and remote services of the same type (e.g. registered under the same interface) in your OSGi Framework, local services can be filtered out by using an LDAP filter on the property "service.imported".

Example: Service Reference

ServiceReference myServiceReference = bundleContext.getServiceReference(MyServiceInterface.class.getName());
if(myServiceReference != null) {
    MyService myService = (MyService) bundleContext.getService(myServiceReference);
    if(myService != hull) {
        System.out.println(myService.hello("Beavis"));
    } else {
        throw new ServiceException("Service object is null.");
    }
} else {
    throw new ServiceException("Service reference is null.");
}

Example: Service Tracker

public class MyServiceTracker extends ServiceTracker {
 
    public MyServiceTracker() {
        super(Activator.getContext(), MyService.class.getName(), null);
    }
 
    @Override
    public Object addingService(ServiceReference reference) {
        MyService myService = null;
        if(reference != null) {
            myService = (MyService) Activator.getContext().getService(reference);
            if(myService != null) {
                System.out.println("MyServiceInterface has come.");
            } else {
                throw new ServiceException("Service object is null.");
            }
        } else {
            throw new ServiceException("Service reference is null.");
        }
        return myService;
    }
 
    @Override
    public void removedService(ServiceReference reference, Object service) {
        System.out.println("MyServiceInterface has gone.");
    }
 
}

Example: Service References with Filter

Filter filter = bundleContext.createFilter("(service.imported=*)");
ServiceReference[] myServiceReferences = bundleContext.getServiceReferences(MyService.class.getName(), filter.toString());

Asynchronous Remote Services (not OSGi standard)

Usualy Remote Procedure Calls operates synchronously. ECF provides an API for asynchronous calls that are executed in some other thread and don't block. 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.

This asynchronous Remote Service implementation is no OSGi standard. For background on the discussion about asynchronous remote services invocation in general and possible future standardization by the OSGI standards organization see Peter Kriens blog entry, and Scott Lewis' blog entry.

For the Implementation of an asynchronous Remote Service the only thing you need to do is implementing an additional interface for your service. This interface should extend the IAsyncRemoteServiceProxy interface with an "Async" added to the interface name. This interface then should map all of the methods of your original interface with "Async" added to the method name and an additional callback parameter. Also this interface must be located in the same(!) package as the original interface of your service. The last parameter of the asynchronous method should then be an instance of the IAsyncCallback<?> interface with the original return type of your method as generic type parameter.

Another approach (next to IAsyncCallback<?>) to achieving asynchronous invocation of remote services are futures. Future objects allow the consumer to perform operations in between initiating a remote call and receiving a result.

Both of these approaches can be used seperate and also togehter.

public interface MyServiceAsync extends IAsyncRemoteServiceProxy {
 
    public void helloAsync(String name, IAsyncCallback<String> callback);
    // and/or
    public IFuture helloAsync(String name);
 
}

Note that with this you will have direct dependencies to ECF bundles. Also some of the distribution providers still don't handle the registration of multiple interfaces correctly.

Example

if(myService instanceof MyServiceAsync) {
    ((MyServiceAsync)myService).helloAsync("Beavis", new MyServiceCallback());
}
public class MyServiceCallback implements IAsyncCallback<String> {
 
    @Override
    public void onSuccess(String result) {
        System.out.println(result);
    }
 
 
    @Override
    public void onFailure(Throwable e) {
        e.printStackTrace();
    }
 
}

Example (Future)

This initiates a remote call, performs some additional local operations and then gets a result from the future.

IFuture future = ((MyServiceAsync)myService).helloAsync("Beavis");
// Do other local operations here...
String result = (String) future.get();
System.out.println(result);

Back to the top