Skip to main content
Jump to: navigation, search

Difference between revisions of "Tutorial: Creating Custom Distribution Providers"

(Step 2: Server)
 
(14 intermediate revisions by the same user not shown)
Line 74: Line 74:
 
==Introduction==
 
==Introduction==
  
The ECF project provides an implementation of the OSGi R6 [https://www.osgi.org/developer/specifications/ Remote Services and Remote Service Admin specifications].   
+
The ECF project provides an implementation of the OSGi R6 [https://www.osgi.org/developer/specifications/ Remote Services and Remote Service Admin specifications].  The RSA specification defines two major subsystems:  discovery and distribution.  Discovery concerns finding remote services exported by other processes on the network.  The distribution subsystem is responsible for the actual communication of invoking a remote call:  serializing remote method parameters, communicating with the remote service host via some network transport protocol, unmarshalling and invoking the service method with provided parameters, and returning a result to the consumer.
  
The RSA specification defines two major subsystems:  discovery and distribution.   Discovery concerns finding remote services exported by other processes on the networkThe distribution subsystem is responsible for the actual communication of invoking a remote call:  serializing remote method parameters, communicating with the remote service host via some network transport protocol, unmarshalling and invoking the service method with provided parameters, and returning a result to the consumer.
+
ECF's implementation of RSA defines an API to create new distribution providers. This API is declared in the [[Distribution_Providers#Remote_Services_API | ECF remote services API, provided by the org.eclipse.ecf.remoteservices bundle]]Custom distribution providers implement a portion of this API and then will be used at runtime to supply the necessary functions of the distribution provider.
  
ECF's implementation of RSA defines an abstract API that allows distribution providers to be easily created and used to implement remote invocation.  This ECF API is declared in the [[Distribution_Providers#Remote_Services_API | ECF remote services API]], provided by the org.eclipse.ecf.remoteservices bundle.  Custom distribution providers simply implement needed part of this API, and then at runtime they will be used to provide the functions of the distribution provider.
+
This tutorial will describe the creation of a simple custom distribution provider using the relevant portions of the ECF remote services API.
 
+
This tutorial will describe the creation of a simple custom distribution provider.
+
  
 
==Remote Service Containers, IDs, and Namespaces==
 
==Remote Service Containers, IDs, and Namespaces==
  
ECF has the concept of a 'container' ([http://download.eclipse.org/rt/ecf/3.13.0/javadoc/org/eclipse/ecf/core/IContainer.html IContainer]), which is an object that implements the remote services API and represents a network-accessible endpoint.
+
ECF has the concept of a 'container' ([http://download.eclipse.org/rt/ecf/3.13.0/javadoc/org/eclipse/ecf/core/IContainer.html IContainer]), which is an object instance that implements the remote services API and represents a network-accessible endpoint.
  
 
Containers have unique transport-specific [http://download.eclipse.org/rt/ecf/3.13.0/javadoc/org/eclipse/ecf/core/identity/ID.html ID].  Some examples of transport-specific container IDs:<br>
 
Containers have unique transport-specific [http://download.eclipse.org/rt/ecf/3.13.0/javadoc/org/eclipse/ecf/core/identity/ID.html ID].  Some examples of transport-specific container IDs:<br>
Line 91: Line 89:
 
ecftcp://localhost:3282/server<br>
 
ecftcp://localhost:3282/server<br>
 
mqtt://mybroker.com/mytopic<br>
 
mqtt://mybroker.com/mytopic<br>
jms://jmsbroker.com:6686/jmstopic<br>
+
jms:tcp://jmsbroker.com:6686/jmstopic<br>
 
r_osgi://somehost/<br>
 
r_osgi://somehost/<br>
hazelcast:///mytopicname
+
hazelcast:///mytopicname<br>
 +
g6YuiWAjkk34je1lJlNmv==<br>
 +
uuid:de305d54-75b4-431b-adb2-eb6b9e546014<br>
 +
241<br>
  
Each ID must be unique within a [http://download.eclipse.org/rt/ecf/latest/javadoc/org/eclipse/ecf/core/identity/Namespace.html Namespace].
+
Each ID instance must be unique within a [http://download.eclipse.org/rt/ecf/latest/javadoc/org/eclipse/ecf/core/identity/Namespace.html Namespace].  Distribution providers must define a new Namespace that enforces the expected syntax requirements of the endpoint identifier.
  
==Registering a new Namespace==
+
==Step 1: Namespace==
  
 
The first thing a distribution provider must do is to register a new type of Namespace.  ECF provides a number of Namespace classes that can be extended to make this easy.  For example, the URIIDNamespace can handle any ID syntax that can be represented as a URI, like all of the above.  Here is an example Namespace class that extends the URIIDNamespace:
 
The first thing a distribution provider must do is to register a new type of Namespace.  ECF provides a number of Namespace classes that can be extended to make this easy.  For example, the URIIDNamespace can handle any ID syntax that can be represented as a URI, like all of the above.  Here is an example Namespace class that extends the URIIDNamespace:
  
 
<source lang="java">
 
<source lang="java">
package org.eclipse.ecf.example1.provider.dist.common;
 
 
import org.eclipse.ecf.core.identity.URIID.URIIDNamespace;
 
 
// Example1Namespace simply inherits from URIIDNamespace
 
 
public class Example1Namespace extends URIIDNamespace {
 
public class Example1Namespace extends URIIDNamespace {
 +
 +
private static final long serialVersionUID = 2460015768559081873L;
  
 
public static final String NAME = "ecf.example1.namespace";
 
public static final String NAME = "ecf.example1.namespace";
public static final String SCHEME = "ecf.example1";
+
private static final String SCHEME = "ecf.example1";
public static Example1Namespace INSTANCE;
+
private static Example1Namespace INSTANCE;
 
 
 
/**
 
/**
Line 123: Line 121:
 
}
 
}
  
 +
public static Example1Namespace getInstance() {
 +
return INSTANCE;
 +
}
 +
 
@Override
 
@Override
 
public String getScheme() {
 
public String getScheme() {
Line 130: Line 132:
 
</source>
 
</source>
  
In the Activator class, the singleton Example1Namespace is created and registered:
+
In bundle Activator start, the singleton Example1Namespace is created and registered:
  
 
<source lang="java">
 
<source lang="java">
Line 139: Line 141:
 
The same Example1Namespace type must be used by both servers and clients, and so it typically makes sense to define the Namespace in a small common bundle, which can be deployed on both servers and clients.  For the source code for this example, see the [https://github.com/ECF/ExampleRSADistributionProviders/tree/master/bundles/org.eclipse.ecf.example1.provider.dist.common bundle here].
 
The same Example1Namespace type must be used by both servers and clients, and so it typically makes sense to define the Namespace in a small common bundle, which can be deployed on both servers and clients.  For the source code for this example, see the [https://github.com/ECF/ExampleRSADistributionProviders/tree/master/bundles/org.eclipse.ecf.example1.provider.dist.common bundle here].
  
Note that other type of ID syntax can be easily supported by either inheriting from other Namespace classes (e.g. LongIDNamespace, StringIDNamespace, etc.), or creating one's own Namespace subclass.
+
Note that other type of ID syntax can be easily supported by either inheriting from other Namespace classes (e.g. LongIDNamespace, StringIDNamespace, UUIDNamespace, etc.), or creating one's own Namespace subclass.
  
==Registering the Distribution Provider Server==
+
==Step 2: Server==
  
==Service-Level Concerns==
+
In addition to registering a new Namespace, distribution providers must implement and register the [http://download.eclipse.org/rt/ecf/3.13.0/javadoc/org/eclipse/ecf/remoteservice/provider/IRemoteServiceDistributionProvider.html IRemoteServiceDistributionProvider] interface using the whiteboard pattern.
  
Although frequently of secondary concern to service implementers, service-level concerns are typically of primary importance to service '''consumers'''.  For example, before I can use any REST-based service, I have to know about (discover) the service and needed meta-data:  the service location (i.e. it's URL), what methods exist and arguments are required, and what can be expected in response.  Additionally, what version of the service is being accessed, what credentials/security are required, what are the run-time qualities of the remote service?
+
For example, here is the code for registering a new custom distribution provider server
  
===OSGi Remote Services===
+
<source lang="java">
 +
public static final String SERVER_ID_PARAMETER = "id";
 +
public static final String SERVER_ID_PARAMETER_DEFAULT = "tcp://localhost:3333";
 +
// register this remote service distribution provider
 +
context.registerService(IRemoteServiceDistributionProvider.class,
 +
  new RemoteServiceDistributionProvider.Builder().setName(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE)
 +
      .setInstantiator(new RemoteServiceContainerInstantiator(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,
 +
        ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) {
 +
        @Override
 +
        public IContainer createInstance(ContainerTypeDescription description,Map<String, ?> parameters) {
 +
            // Create and configure an instance of our server
 +
            // container type
 +
            return new Example1ServerContainer(getIDParameterValue(Example1Namespace.getInstance(), parameters,
 +
SERVER_ID_PARAMETER, SERVER_ID_PARAMETER_DEFAULT));
 +
        }
 +
  }).build(),
 +
null);
 +
</source>
  
In recent releases the OSGi Alliance has defined a specification called [http://www.osgi.org/Specifications/HomePage Remote Services] (chapter 100 in the enterprise spec).  Along with the Remote Service Admin specification (chapter 122 in enterprise spec), Remote Services defines ways to express answers to service-level concerns in an implementation-independent way, similar to what JAX-RS does for transport-level concerns.  For example, the Remote Service spec allows meta-data for service type, service version, service endpoint/URL identification, security, and quality of service properties to be communicated between service implementer and service consumer without referring to any Remote Services implementation.  Further, Remote Services/RSA defines a way to dynamically discover and un-discover remote services, allowing for easy consumer support for networked and frequently unreliable services.
+
Notes for the above code<br>
  
Several implementations of OSGi Remote Services exist, including open source [https://wiki.eclipse.org/ECF#OSGi_Remote_Services ECF], [http://cxf.apache.org/ CXF], [http://www.amdatu.org/ Amdatu] and commercial implementations.
+
The RemoteServiceDistributionProvider.Builder class is used to create the IRemoteServiceDistributionProvider instance. <br>
 +
<br>
 +
The <b>setName(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE)</b> method on the Builder sets the distribution provider's name (ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE==ecf.example1.provider.dist.server).
  
OSGi RSA has the concept of a distribution system responsible for exporting a local service and making it available for remote accessAccording to the specification, many distributions systems may be used even for a single service.  ECF's implementation is unique because it has an open API for creating/adding new distribution providersCurrently, ECF committers have implemented the following distribution providers
+
This name corresponds to the OSGi Remote Service config type, and must uniquely identify the distribution providerWhen a remote service is registered, the standard service property <b>service.exported.configs</b> may be specified so that the remote service will be exported via this distribution provider rather than some other distribution providerFor example:
  
*[https://www.eclipse.org/ecf/downloads.php ECF 'generic']
+
<source lang="java">
*[https://www.eclipse.org/ecf/downloads.php r-OSGi]
+
Hashtable serviceProperties = new Hashtable();
*[https://github.com/ECF/JMS Java Messaging Service (JMS)]
+
serviceProperties.put("service.exported.interfaces","*");
*[https://github.com/ECF/Mqtt-Provider MQTT]
+
serviceProperties.put("service.exported.configs","ecf.example1.provider.dist.server");
*[https://github.com/ECF/HazelcastProvider Hazelcast]
+
...
*[https://github.com/ECF/JGroups JavaGroups]
+
context.registerService(MyService.class,serviceInstance,serviceProperties);
*[https://github.com/ECF/JaxRSProviders Jax-RS/Jersey and Jax-RS/CXF ]
+
</source>
  
==Jax-RS with OSGi Remote Services==
+
The underlying ECF RSA implementation will export the serviceInstance via the ecf.example2.provider.dist.server distribution provider.
  
Since ECF's RSA implementation implements the OSGi RS and RSA specifications, and Jersey implements the Jax-RS specification, it's possible create and export a remote service that deals with both the transport and service-level concerns in a way completely standardized, and not dependent upon either the OSGi RS/RSA implementation (e.g. ECF), nor on the distribution system provider implementation (Jersey).
+
'''NOTE:''' As above, the IRemoteServiceDistributionProvider should be registered '''before''' any remote services using these distribution providers are exported.  In other words, if you create and register a IRemoteServiceDistributionProvider with name 'ecf.example1.provider.dist.server' the provider implementation bundle should be started and the IRemoteServiceDistributionProvider service should be registered <b>prior</b> to registering the service to be exported using that provider.   If the distribution provider is not registered prior to the remote service export, then the correct
 +
distribution provider will not be available to do the export.
  
For example, here is some example OSGi code for exporting a remote service using the [https://github.com/ECF/JaxRSProviders Jax-RS/Jersey] provider:
+
The other required part of the distribution provider is the container instantiator:
  
 
<source lang="java">
 
<source lang="java">
BundleContext bundleContext;
+
      .setInstantiator(new RemoteServiceContainerInstantiator(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,
Dictionary<String, String> props = new Hashtable<String,String>();
+
        ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) {
// osgi rs property to signal to distribution system
+
        @Override
// that this is a remote service
+
        public IContainer createInstance(ContainerTypeDescription description,Map<String, ?> parameters) {
props.put("service.exported.interfaces","*");
+
            // Create and configure an instance of our server
// specify the distribution provider with osgi rs property
+
            // container type
props.put("service.exported.configs", "ecf.jaxrs.jersey.server");
+
            return new Example1ServerContainer(getIDParameterValue(Example1Namespace.getInstance(), parameters,
// as per spec, <provider>.<prop> represents a property intended for use by this provider
+
SERVER_ID_PARAMETER, SERVER_ID_PARAMETER_DEFAULT));
props.put("ecf.jaxrs.jersey.server.alias", "/jersey");
+
        }
// register (and export) HelloImpl as remote service described by Hello interface
+
  })
bundleContext.registerService(HelloWorldService.class, new HelloWorldResource(), props);
+
 
</source>
 
</source>
  
HelloWorldResource implements a HelloWorldService interface which is defined
+
This code uses the RemoteServiceContainerInstantiator class.  The two constants in the constructor (ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) sets up the instantiator so that these two config types (server and client for distribution provider) are associated with each other so at remote service consumer import time the ECF RSA implementation can select the appropriate client config type associated with the exporting server config type.  For example, when ecf.example1.provider.dist.server is used as the exporting config type, then on the client/consumer the selected config type will be:  ecf.example1.provider.dist.client
 +
<br>
 +
The createInstance method then creates an instance of the appropriate container type.  This method allows the container to be created and configured based upon a Map of parameters.  As per the RSA specification, if the remote service registration has service properties with keys of the form:
 +
<br>
 +
<config type>.<param>
 +
<br>
 +
then the provided parameters Map will contain entries of the form
 +
<br>
 +
key: <param>=<value>
 +
<br>
 +
For example, if the remote service is registered:
 +
<source lang="java">
 +
Hashtable serviceProperties = new Hashtable();
 +
serviceProperties.put("service.exported.interfaces","*");
 +
serviceProperties.put("service.exported.configs","ecf.example1.provider.dist.server");
 +
serviceProperties.put("ecf.example1.provider.dist.server.id","tcp://localhost:3333");
 +
...
 +
context.registerService(MyService.class,serviceInstance,serviceProperties);
 +
</source>
  
 +
then the parameters Map will contain an entry with key="id" and value="tcp://localhost:3333".  Such values can be used to configure the provider.  In the case of the Example1 provider above, the id parameter is used to create an ID via the call to getIDParameterValue.  Other distribution providers can define arbitrary parameters used to configure the underlying transport such as host, port, bind address, path, etc.
 +
<br>
 +
At the appropriate time during export, the createInstance method will be called and the Example1ServerContainer instance created.  Here is the implementation of Example1Container
 
<source lang="java">
 
<source lang="java">
import javax.ws.rs.GET;
+
/**
import javax.ws.rs.Produces;
+
* Instances of this class are created via the container instantiator specified
import javax.ws.rs.Path;
+
* by the RemoteServiceDistributionProvider whiteboard service in the Activator.
 +
* @see Activator#start(org.osgi.framework.BundleContext)
 +
*
 +
*/
 +
public class Example1ServerContainer extends AbstractRSAContainer {
  
// The Java class will be hosted at the URI path "/helloworld"
+
/**
@Path("/helloworld")
+
* Create an Example1ServerContainer.  The given id must not be null,
public interface HelloWorldService {
+
* and should be created using the Example1Namespace.  The server's ID
   
+
* will then be automatically used to provide the ecf.endpoint.id to
    // The Java method will process HTTP GET requests
+
* remote service clients via the RSA-created EndpointDescription.
    @GET
+
* @param id
    // The Java method will produce content identified by the MIME Media
+
*/
    // type "text/plain"
+
public Example1ServerContainer(ID id) {
    @Produces("text/plain")
+
super(id);
    public String getMessage();
+
}
 +
 
 +
 +
@Override
 +
/**
 +
* When the ECF RSA impl is requested to export a remote service and
 +
* this container instance is selected, a remote service registration will be
 +
* created by RSA and this method will then be called to actually export the given
 +
* registration via some communications transport.  This should trigger the appropriate
 +
* networking initialization (e.g. opening listener on socket), given the info in the
 +
* registration.
 +
* The given registration will not be <code>null</code>.
 +
* If the transport would like to insert properties into the EndpointDescription
 +
* for this endpoint, a Map of name (String) -> Object map should be returned.  All
 +
* the values in the Map should be Serializable.  This provides a mechanism for
 +
* distribution providers to include arbitrary private properties for use by
 +
* clients.
 +
*
 +
* Note that keys for the Map should be unique to avoid conflicting with any other properties.
 +
*
 +
* If values are provided for either OSGI RemoteConstants or ECF Remote Services Constants
 +
* then these new values will <b>override</b> the default values in the EndpointDescription.
 +
*
 +
*/
 +
protected Map<String, Object> exportRemoteService(RSARemoteServiceRegistration registration) {
 +
// Here would be the code to export/make a remote service on the actual transport
 +
                // For example, starting a listener to handle connections, and responding to
 +
                // connection attempts, handling remote calls, etc.
 +
                // the registration parameter contains the services interfaces, the implementation, and the
 +
                // service properties passed in when the remote service is registered
 +
                // This method will be called by the same thread that calls BundleContext.registerService
 +
return null;
 +
}
 +
 
 +
@Override
 +
/**
 +
* When this remote service is unregistered, this method will be called by ECF RSA
 +
* to allow the underlying transport to unregister the remote service given
 +
* by the registration.  Necessary clean-up/shutdown of transport should be completed
 +
* before returning.
 +
*/
 +
protected void unexportRemoteService(RSARemoteServiceRegistration registration) {
 +
// This method will be called when the service registration unregister()  
 +
                // method is called, and is responsible for cleaning up/shutting down
 +
                // and network resources associated with this remote service
 +
                // This method will be called by the same thread that is calling
 +
                // ServiceRegistration.unregister()
 +
}
 
}
 
}
 +
</source>
 +
Once this container instance is created the ECF RSA implementation will then call <b>exportRemoteService(RSARemoteServiceRegistration registration)</b>
 +
and expect that upon successful completion that the distribution provider will have made the remote service described by the given registration will have been made available for remote access.  The exportRemoteService implementation is therefore where the distribution provider should actually make the remote service available over the network (e.g. by listening on socket, joining communication group, etc).  When the remote service is unregistered, the <b>unexportRemoteService(RSARemoteServiceRegistration registration)</b> will be called to allow the transport to close and clean up any network resources associated with the previous export. 
 +
<br>
 +
Each method will be called for each remote service export, with a unique RSARemoteServiceRegistration passed in by the ECF RSA implementation.
 +
<br>
 +
For the exportRemoteService method, the implementation can return a Map of service properties (or null).  If a Map instance is returned, the values in the given map will be merged with the other endpoint description properties defined/required by ECF's RSA implementation.  For example, one required ECF remote service property is ecf.endpoint.id.  The default value of the ecf.endpoint.id is the exporting container's ID...e.g. by default
 +
<br>
 +
ecf.endpoint.id will be set to: "tcp://localhost:3333" because the Example1Container's ID is set by construction to "tcp://localhost:3333".  However, if the returned Map is non null, and has the key ecf.endpoint.id, the value in the returned map will override the default value.  e.g.
 +
<source lang="java">
 +
protected Map<String, Object> exportRemoteService(RSARemoteServiceRegistration registration) {
 +
// TODO setup transport and export given remote service registration
 +
                Map<String,Object> result = new HashMap<String,Object>();
 +
                // This will override the ecf.endpoint.id value in the RSA endpoint description
 +
                result.put("ecf.endpoint.id","http://somehost:2222/foo/");
 +
                // This will add a brand new property to the RSA endpoint description
 +
                result.put("my.new.property","howdy");
 +
return result;
 +
}
 
</source>
 
</source>
  
Note that the HelloWorldService has exactly the same Jax-RS annotations as the HelloWorldResource implementation class.
+
The complete source for the distribution provider server is available [https://github.com/ECF/ExampleRSADistributionProviders/tree/master/bundles/org.eclipse.ecf.example1.provider.dist.server here].
  
With the Jax-RS/Jersey distribution provider, the above registerService call will dynamically export the remote service (via Jersey) so that remote clients (Java/OSGi-based or not) can access getMessage by sending a GET to an URL like this:
+
==Step 3: Client==
  
curl http://localhost:8080/jersey/helloworld/1
+
Like the server, the distribution provider client is registered via the whiteboard pattern using the IRemoteServiceDistributionProvider service interface.  Here is the code for registering the Example1 client distribution provider
 +
<source lang="java">
 +
context.registerService(IRemoteServiceDistributionProvider.class,
 +
new RemoteServiceDistributionProvider.Builder().setName(ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE)
 +
.setInstantiator(
 +
new RemoteServiceContainerInstantiator(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,
 +
ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) {
 +
@Override
 +
public IContainer createInstance(ContainerTypeDescription description,
 +
Map<String, ?> parameters) {
 +
        // Create and configure an instance of our client
 +
        // container type (below)
 +
// This is called by RSA when a client container of this type
 +
// is needed (e.g. to import a discovered remote service)
 +
return new Example1ClientContainer();
 +
}
 +
}).build(),
 +
null);
 +
</source>
  
Would respond with "Hello World"
+
As with the server, the setName and setInstantiator builder methods are required.  For this distribution provider all that's necessary is to return a new Example1ClientContainer which is declared
 +
<source lang="java">
 +
public class Example1ClientContainer extends AbstractRSAClientContainer {
  
The use of Jax-RS annotations to implement an ECF distribution provider, and the use of OSGi Remote Services has several important advantages for the service implementer and the service consumer:
+
public Example1ClientContainer() {
 +
super(Example1Namespace.getInstance()
 +
.createInstance(new Object[] { "uuid:" + java.util.UUID.randomUUID().toString() }));
 +
}
  
#An ability to flexibly handle both transport-level and service-level concerns in a way appropriate to the application
+
@Override
#A clean separation between service contract (HelloWorldService interface), and service implementation (HelloWorldResource)
+
// This is called when when a remote service instance is actually needed by consumers
#A clean separation between application concerns from transport '''or''' service-level concerns
+
// The remote service getProxy method will be called the first time the proxy is
#Alternative implementations of Jax-RS and/or OSGi RS/RSA may be substituted at any time without application changes
+
// to be created for a given consumer
 +
protected IRemoteService createRemoteService(RemoteServiceClientRegistration registration) {
 +
return new AbstractRSAClientService(this, registration) {
  
==Using the Remote Service==
+
@Override
 +
public Object getProxy(ClassLoader cl, @SuppressWarnings("rawtypes") Class[] interfaces) throws ECFException {
 +
return super.getProxy(cl, interfaces);
 +
}
 +
 +
@Override
 +
protected Object invokeAsync(RSARemoteCall remoteCall) throws ECFException {
 +
// TODO Auto-generated method stub
 +
return null;
 +
}
 +
// invokeSync will be called when a client needs to make a remote call on
 +
// one of the proxy methods.
 +
@Override
 +
protected Object invokeSync(RSARemoteCall remoteCall) throws ECFException {
 +
// TODO Auto-generated method stub
 +
return null;
 +
}
 +
};
 +
}
 +
}
 +
</source>
  
Since the HelloWorldService is exported via Jax-RS/Jersey provider, it may be accessed by any client (e.g. javascript, java, curl, etc) that can access via http calls.  If, however, it is an OSGi client (or a non-OSGi Java Client) ECF Remote Service can automatically construct a proxy for the remote service, and make the proxy available as an OSGi Service on the clientFor a description and example of doing this, see
+
When the ECF RSA discovers a remote service and attempts to import it, the <b>createRemoteService</b> method is called with the associated RemoteServiceClientRegistration provided.
[[Tutorial:_Exposing_a_Jax_REST_service_as_an_OSGi_Remote_Service | Exposing a Jax REST Service as an OSGi Service]].
+
<br>
 
+
In the above case an instance of AbstractRSAClientService is created for the importSometime later when the proxy is actually required by a consumer, the <b>getProxy</b> method will be called.  The code above overrides the implementation of <b>getProxy</b> to show that this process can be easily customized for a distribution provider, but in most cases the AbstractRSAClientService proxy creation can be used.
==A More Complete Example==
+
<br>
 
+
The <b>invokeSync</b> and <b>invokeAsync</b> method are called when the proxy methods are actually invoked by the consumer.  The invokeSync method is called when the proxy methods are called synchronously (normal case), and the invokeAsync is called when the [[Asynchronous_Proxies_for_Remote_Services | ECF async proxy]] methods are invokedFor the invokeSync method, the distribution provider should implement this method to make the appropriate remote call by serializing remote call arguments, sending over the distribution provider's transport, getting and deserializing the result, and returning the Object that represents the appropriate type for proxy method defined in the RSARemoteCall instance.  In invokeSync the calling thread should block until the remote call is made and the response is received, an exception occurs, or any timeout occurs. 
A more complex example exists in the [https://github.com/ECF/JaxRSProviders Jax-RS/Jersey Provider] repo.  The remote service host/server is in the [https://github.com/ECF/JaxRSProviders/tree/master/examples/com.mycorp.examples.student.remoteservice.host com.mycorp.examples.student.remoteservice.host] bundle.  The remote service consumer/client is in [https://github.com/ECF/JaxRSProviders/tree/master/examples/com.mycorp.examples.student.client com.mycorp.examples.student.client] bundleNotice that neither of these bundles has references to ECF, Jersey, or even OSGi classes, but rather only to Jax-RS standard annotation types (javax.*) and model classes defined in the [https://github.com/ECF/JaxRSProviders/tree/master/examples/com.mycorp.examples.student com.mycorp.examples.student] bundle.
+
<br>
 +
The complete source for the distribution provider client is available [https://github.com/ECF/ExampleRSADistributionProviders/tree/master/bundles/org.eclipse.ecf.example1.provider.dist.client here].
  
 
==Background and Related Articles==
 
==Background and Related Articles==
 
[[Tutorial: Exposing a Jax REST service as an OSGi Remote Service]]
 
  
 
[[Getting Started with ECF's OSGi Remote Services Implementation]]
 
[[Getting Started with ECF's OSGi Remote Services Implementation]]

Latest revision as of 15:01, 28 April 2016


Introduction

The ECF project provides an implementation of the OSGi R6 Remote Services and Remote Service Admin specifications. The RSA specification defines two major subsystems: discovery and distribution. Discovery concerns finding remote services exported by other processes on the network. The distribution subsystem is responsible for the actual communication of invoking a remote call: serializing remote method parameters, communicating with the remote service host via some network transport protocol, unmarshalling and invoking the service method with provided parameters, and returning a result to the consumer.

ECF's implementation of RSA defines an API to create new distribution providers. This API is declared in the ECF remote services API, provided by the org.eclipse.ecf.remoteservices bundle. Custom distribution providers implement a portion of this API and then will be used at runtime to supply the necessary functions of the distribution provider.

This tutorial will describe the creation of a simple custom distribution provider using the relevant portions of the ECF remote services API.

Remote Service Containers, IDs, and Namespaces

ECF has the concept of a 'container' (IContainer), which is an object instance that implements the remote services API and represents a network-accessible endpoint.

Containers have unique transport-specific ID. Some examples of transport-specific container IDs:

https://myhost.com/v1/path/to/service
ecftcp://localhost:3282/server
mqtt://mybroker.com/mytopic
jms:tcp://jmsbroker.com:6686/jmstopic
r_osgi://somehost/
hazelcast:///mytopicname
g6YuiWAjkk34je1lJlNmv==
uuid:de305d54-75b4-431b-adb2-eb6b9e546014
241

Each ID instance must be unique within a Namespace. Distribution providers must define a new Namespace that enforces the expected syntax requirements of the endpoint identifier.

Step 1: Namespace

The first thing a distribution provider must do is to register a new type of Namespace. ECF provides a number of Namespace classes that can be extended to make this easy. For example, the URIIDNamespace can handle any ID syntax that can be represented as a URI, like all of the above. Here is an example Namespace class that extends the URIIDNamespace:

public class Example1Namespace extends URIIDNamespace {
 
	private static final long serialVersionUID = 2460015768559081873L;
 
	public static final String NAME = "ecf.example1.namespace";
	private static final String SCHEME = "ecf.example1";
	private static Example1Namespace INSTANCE;
 
	/**
	 * The singleton instance of this namespace is created (and registered
	 * as a Namespace service) in the Activator class for this bundle.
	 * The singleton INSTANCE may then be used by both server and client.
	 */
	public Example1Namespace() {
		super(NAME, "Example 1 Namespace");
		INSTANCE = this;
	}
 
	public static Example1Namespace getInstance() {
		return INSTANCE;
	}
 
	@Override
	public String getScheme() {
		return SCHEME;
	}
}

In bundle Activator start, the singleton Example1Namespace is created and registered:

// Create and register the Example1Namespace
context.registerService(org.eclipse.ecf.core.identity.Namespace.class, new Example1Namespace(),  null);

The same Example1Namespace type must be used by both servers and clients, and so it typically makes sense to define the Namespace in a small common bundle, which can be deployed on both servers and clients. For the source code for this example, see the bundle here.

Note that other type of ID syntax can be easily supported by either inheriting from other Namespace classes (e.g. LongIDNamespace, StringIDNamespace, UUIDNamespace, etc.), or creating one's own Namespace subclass.

Step 2: Server

In addition to registering a new Namespace, distribution providers must implement and register the IRemoteServiceDistributionProvider interface using the whiteboard pattern.

For example, here is the code for registering a new custom distribution provider server

public static final String SERVER_ID_PARAMETER = "id";
public static final String SERVER_ID_PARAMETER_DEFAULT = "tcp://localhost:3333";
// register this remote service distribution provider
context.registerService(IRemoteServiceDistributionProvider.class,
   new RemoteServiceDistributionProvider.Builder().setName(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE)
      .setInstantiator(new RemoteServiceContainerInstantiator(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,
         ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) {
         @Override
         public IContainer createInstance(ContainerTypeDescription description,Map<String, ?> parameters) {
            // Create and configure an instance of our server 
            // container type
            return new Example1ServerContainer(getIDParameterValue(Example1Namespace.getInstance(), parameters,
				SERVER_ID_PARAMETER, SERVER_ID_PARAMETER_DEFAULT));
         }
   }).build(),	
null);

Notes for the above code

The RemoteServiceDistributionProvider.Builder class is used to create the IRemoteServiceDistributionProvider instance.

The setName(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE) method on the Builder sets the distribution provider's name (ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE==ecf.example1.provider.dist.server).

This name corresponds to the OSGi Remote Service config type, and must uniquely identify the distribution provider. When a remote service is registered, the standard service property service.exported.configs may be specified so that the remote service will be exported via this distribution provider rather than some other distribution provider. For example:

Hashtable serviceProperties = new Hashtable();
serviceProperties.put("service.exported.interfaces","*");
serviceProperties.put("service.exported.configs","ecf.example1.provider.dist.server");
...
context.registerService(MyService.class,serviceInstance,serviceProperties);

The underlying ECF RSA implementation will export the serviceInstance via the ecf.example2.provider.dist.server distribution provider.

NOTE: As above, the IRemoteServiceDistributionProvider should be registered before any remote services using these distribution providers are exported. In other words, if you create and register a IRemoteServiceDistributionProvider with name 'ecf.example1.provider.dist.server' the provider implementation bundle should be started and the IRemoteServiceDistributionProvider service should be registered prior to registering the service to be exported using that provider. If the distribution provider is not registered prior to the remote service export, then the correct distribution provider will not be available to do the export.

The other required part of the distribution provider is the container instantiator:

      .setInstantiator(new RemoteServiceContainerInstantiator(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,
         ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) {
         @Override
         public IContainer createInstance(ContainerTypeDescription description,Map<String, ?> parameters) {
            // Create and configure an instance of our server 
            // container type
            return new Example1ServerContainer(getIDParameterValue(Example1Namespace.getInstance(), parameters,
				SERVER_ID_PARAMETER, SERVER_ID_PARAMETER_DEFAULT));
         }
   })

This code uses the RemoteServiceContainerInstantiator class. The two constants in the constructor (ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) sets up the instantiator so that these two config types (server and client for distribution provider) are associated with each other so at remote service consumer import time the ECF RSA implementation can select the appropriate client config type associated with the exporting server config type. For example, when ecf.example1.provider.dist.server is used as the exporting config type, then on the client/consumer the selected config type will be: ecf.example1.provider.dist.client
The createInstance method then creates an instance of the appropriate container type. This method allows the container to be created and configured based upon a Map of parameters. As per the RSA specification, if the remote service registration has service properties with keys of the form:
<config type>.<param>
then the provided parameters Map will contain entries of the form
key: <param>=<value>
For example, if the remote service is registered:

Hashtable serviceProperties = new Hashtable();
serviceProperties.put("service.exported.interfaces","*");
serviceProperties.put("service.exported.configs","ecf.example1.provider.dist.server");
serviceProperties.put("ecf.example1.provider.dist.server.id","tcp://localhost:3333");
...
context.registerService(MyService.class,serviceInstance,serviceProperties);

then the parameters Map will contain an entry with key="id" and value="tcp://localhost:3333". Such values can be used to configure the provider. In the case of the Example1 provider above, the id parameter is used to create an ID via the call to getIDParameterValue. Other distribution providers can define arbitrary parameters used to configure the underlying transport such as host, port, bind address, path, etc.
At the appropriate time during export, the createInstance method will be called and the Example1ServerContainer instance created. Here is the implementation of Example1Container

/**
 * Instances of this class are created via the container instantiator specified
 * by the RemoteServiceDistributionProvider whiteboard service in the Activator.
 * @see Activator#start(org.osgi.framework.BundleContext)
 * 
 */
public class Example1ServerContainer extends AbstractRSAContainer {
 
	/**
	 * Create an Example1ServerContainer.  The given id must not be null,
	 * and should be created using the Example1Namespace.  The server's ID
	 * will then be automatically used to provide the ecf.endpoint.id to
	 * remote service clients via the RSA-created EndpointDescription.
	 * @param id
	 */
	public Example1ServerContainer(ID id) {
		super(id);
	}
 
 
	@Override
	/**
	 * When the ECF RSA impl is requested to export a remote service and 
	 * this container instance is selected, a remote service registration will be
	 * created by RSA and this method will then be called to actually export the given
	 * registration via some communications transport.  This should trigger the appropriate 
	 * networking initialization (e.g. opening listener on socket), given the info in the
	 * registration.
	 * The given registration will not be <code>null</code>.
	 * If the transport would like to insert properties into the EndpointDescription
	 * for this endpoint, a Map of name (String) -> Object map should be returned.  All
	 * the values in the Map should be Serializable.   This provides a mechanism for
	 * distribution providers to include arbitrary private properties for use by 
	 * clients.
	 * 
	 * Note that keys for the Map should be unique to avoid conflicting with any other properties.
	 * 
	 * If values are provided for either OSGI RemoteConstants or ECF Remote Services Constants
	 * then these new values will <b>override</b> the default values in the EndpointDescription.
	 *
	 */
	protected Map<String, Object> exportRemoteService(RSARemoteServiceRegistration registration) {
		// Here would be the code to export/make a remote service on the actual transport
                // For example, starting a listener to handle connections, and responding to
                // connection attempts, handling remote calls, etc.
                // the registration parameter contains the services interfaces, the implementation, and the
                // service properties passed in when the remote service is registered
                // This method will be called by the same thread that calls BundleContext.registerService
		return null;
	}
 
	@Override
	/**
	 * When this remote service is unregistered, this method will be called by ECF RSA
	 * to allow the underlying transport to unregister the remote service given
	 * by the registration.  Necessary clean-up/shutdown of transport should be completed
	 * before returning.
	 */
	protected void unexportRemoteService(RSARemoteServiceRegistration registration) {
		// This method will be called when the service registration unregister() 
                // method is called, and is responsible for cleaning up/shutting down
                // and network resources associated with this remote service
                // This method will be called by the same thread that is calling
                // ServiceRegistration.unregister()
	}
}

Once this container instance is created the ECF RSA implementation will then call exportRemoteService(RSARemoteServiceRegistration registration) and expect that upon successful completion that the distribution provider will have made the remote service described by the given registration will have been made available for remote access. The exportRemoteService implementation is therefore where the distribution provider should actually make the remote service available over the network (e.g. by listening on socket, joining communication group, etc). When the remote service is unregistered, the unexportRemoteService(RSARemoteServiceRegistration registration) will be called to allow the transport to close and clean up any network resources associated with the previous export.
Each method will be called for each remote service export, with a unique RSARemoteServiceRegistration passed in by the ECF RSA implementation.
For the exportRemoteService method, the implementation can return a Map of service properties (or null). If a Map instance is returned, the values in the given map will be merged with the other endpoint description properties defined/required by ECF's RSA implementation. For example, one required ECF remote service property is ecf.endpoint.id. The default value of the ecf.endpoint.id is the exporting container's ID...e.g. by default
ecf.endpoint.id will be set to: "tcp://localhost:3333" because the Example1Container's ID is set by construction to "tcp://localhost:3333". However, if the returned Map is non null, and has the key ecf.endpoint.id, the value in the returned map will override the default value. e.g.

	protected Map<String, Object> exportRemoteService(RSARemoteServiceRegistration registration) {
		// TODO setup transport and export given remote service registration
                Map<String,Object> result = new HashMap<String,Object>();
                // This will override the ecf.endpoint.id value in the RSA endpoint description
                result.put("ecf.endpoint.id","http://somehost:2222/foo/");
                // This will add a brand new property to the RSA endpoint description
                result.put("my.new.property","howdy");
		return result;
	}

The complete source for the distribution provider server is available here.

Step 3: Client

Like the server, the distribution provider client is registered via the whiteboard pattern using the IRemoteServiceDistributionProvider service interface. Here is the code for registering the Example1 client distribution provider

context.registerService(IRemoteServiceDistributionProvider.class,
	new RemoteServiceDistributionProvider.Builder().setName(ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE)
		.setInstantiator(
			new RemoteServiceContainerInstantiator(ProviderConstants.SERVER_PROVIDER_CONFIG_TYPE,
				ProviderConstants.CLIENT_PROVIDER_CONFIG_TYPE) {
				@Override
				public IContainer createInstance(ContainerTypeDescription description,
								Map<String, ?> parameters) {
				        // Create and configure an instance of our client
				        // container type (below)
					// This is called by RSA when a client container of this type
					// is needed (e.g. to import a discovered remote service)
					return new Example1ClientContainer();
				}
			}).build(),
null);

As with the server, the setName and setInstantiator builder methods are required. For this distribution provider all that's necessary is to return a new Example1ClientContainer which is declared

public class Example1ClientContainer extends AbstractRSAClientContainer {
 
	public Example1ClientContainer() {
		super(Example1Namespace.getInstance()
				.createInstance(new Object[] { "uuid:" + java.util.UUID.randomUUID().toString() }));
	}
 
	@Override
	// This is called when when a remote service instance is actually needed by consumers
	// The remote service getProxy method will be called the first time the proxy is 
	// to be created for a given consumer
	protected IRemoteService createRemoteService(RemoteServiceClientRegistration registration) {
		return new AbstractRSAClientService(this, registration) {
 
			@Override
			public Object getProxy(ClassLoader cl, @SuppressWarnings("rawtypes") Class[] interfaces) throws ECFException {
				return super.getProxy(cl, interfaces);
			}
 
			@Override
			protected Object invokeAsync(RSARemoteCall remoteCall) throws ECFException {
				// TODO Auto-generated method stub
				return null;
			}
			// invokeSync will be called when a client needs to make a remote call on 
			// one of the proxy methods.
			@Override
			protected Object invokeSync(RSARemoteCall remoteCall) throws ECFException {
				// TODO Auto-generated method stub
				return null;
			}
		};
	}
}

When the ECF RSA discovers a remote service and attempts to import it, the createRemoteService method is called with the associated RemoteServiceClientRegistration provided.
In the above case an instance of AbstractRSAClientService is created for the import. Sometime later when the proxy is actually required by a consumer, the getProxy method will be called. The code above overrides the implementation of getProxy to show that this process can be easily customized for a distribution provider, but in most cases the AbstractRSAClientService proxy creation can be used.
The invokeSync and invokeAsync method are called when the proxy methods are actually invoked by the consumer. The invokeSync method is called when the proxy methods are called synchronously (normal case), and the invokeAsync is called when the ECF async proxy methods are invoked. For the invokeSync method, the distribution provider should implement this method to make the appropriate remote call by serializing remote call arguments, sending over the distribution provider's transport, getting and deserializing the result, and returning the Object that represents the appropriate type for proxy method defined in the RSARemoteCall instance. In invokeSync the calling thread should block until the remote call is made and the response is received, an exception occurs, or any timeout occurs.
The complete source for the distribution provider client is available here.

Background and Related Articles

Getting Started with ECF's OSGi Remote Services Implementation

OSGi Remote Services and ECF

Asynchronous Proxies for Remote Services

Static File-based Discovery of Remote Service Endpoints

Download ECF Remote Services/RSA Implementation

How to Add Remote Services/RSA to Your Target Platform

Copyright © Eclipse Foundation, Inc. All Rights Reserved.