EIG:Remoting

Creating an OSGi Service

OSGi Services should be defined by/registered under a specific interface. Even though it's possible, with OSGi Remote Services the service should not be registered by the class name:

public interface MyServiceInterface {
    
    public String hello();

}

There is then some implementaions of this service:

public class MyService implements MyServiceInterface {

    public String hello() {
        return "Hello World!";
    }

}

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.

OSGi Remote Service Properties

service.exported.configs

service.exported.intents

service.exported.intents.extra

service.exported.interfaces

service.intents

Example

public class Activator implements BundleActivator {

    private MyServiceInterface myService = null;
    private ServiceRegistration myServiceRegistration = null;

    public void start(BundleContext bundleContext) throws Exception {
        // Instantiate a service instance
        this.myService = new MyService();

        // 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(MyServiceInterface.class.getName(), new 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) {
    MyServiceInterface myService = (MyServiceInterface) bundleContext.getService(myServiceReference);
    if(myService != hull) {
        System.out.println(myService.hello());
    } else {
        throw new ServiceException("Service object is null.");
    }
} else {
    throw new ServiceException("Service reference is null.");
}

Example: Service Tracker

public class MyServiceInterfaceTracker extends ServiceTracker {

    public MyServiceInterfaceTracker() {
        super(Activator.getContext(), MyServiceInterface.class.getName(), null);
    }

    @Override
    public Object addingService(ServiceReference reference) {
        System.out.println("MyServiceInterface has come.");
    }

    @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(MyServiceInterface.class.getName(), filter.toString());

Asynchronouse Remote Services (not yet 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.

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. The callback parameter should be an instance of the IAsyncCallback<?> interface with the original return type of your method as generic type parameter.

public interface MyServiceInterface extends IAsyncRemoteServiceProxy {
    
    public void helloAsync(IAsyncCallback<String> callback);

}

public class MyServiceInterfaceCallback implements IAsyncCallback<String> {
	@Override
	public void onSuccess(String result) {
		System.out.println(result);
	}


	@Override
	public void onFailure(Throwable e) {
		e.printStackTrace();
	}


}

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: Using the Asynchronouse Remote Service

[...]

Implementing an ECF Distribution Provider

[...]