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 "Distribution Providers"

(JMS/ActiveMQ)
(Xml-Rpc Provider)
(29 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
  
The Remote Services/Remote Service Admin specifications (chaps 100 and 122 in [http://www.osgi.org/Specifications/HomePage OSGi Enterprise spec]) allows for the use of distinct distribution providers for every exported remote service.  Distribution providers are responsible for the actual marshalling/serialization and network communication that takes place when a consumer invokes a method on a remote service.
+
The Remote Services/Remote Service Admin specifications (chaps 100 and 122 in [http://www.osgi.org/Specifications/HomePage OSGi Enterprise spec]) allows for the use of multiple distribution providers.  A separate distribution provider(s) can be defined for every exported remote service.  Such providers are responsible for the actual marshalling/serialization and network communication that takes place when a consumer invokes a remote service method.
  
The [[OSGi_Remote_Services_and_ECF | ECF Architecture]] allows the use of multiple distribution providers.  Further, ECF's open APIs and implementations allows the creation of new distribution providers that may be based upon existing providers or may be created from scratch using any desired transport protocols and/or serialization formats.
+
The [[OSGi_Remote_Services_and_ECF | ECF Architecture]] also allows the use of multiple distribution providers.  Further, ECF's open APIs and implementations supports the creation of custom distribution providers using any desired transport protocols, serialization formats and/or libraries.
  
 
==Remote Services API==
 
==Remote Services API==
  
ECF's API for distribution providers is called the Remote Services API (RSAPI).  An implementation of this API is the only thing required of distribution provider implementations for them to be successfully used as a standards/compliant implementation of RS/RSA.
+
ECF's API for distribution providers is the Remote Services API (RSAPI).  Implementing this API is the only thing required to create a RS/RSA standards compliant distribution provider.
  
 
Symbolic Name:  [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/framework/bundles/org.eclipse.ecf.remoteservice org.eclipse.ecf.remoteservice]<br>
 
Symbolic Name:  [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/framework/bundles/org.eclipse.ecf.remoteservice org.eclipse.ecf.remoteservice]<br>
Line 19: Line 19:
 
[http://download.eclipse.org/rt/ecf/latest/javadoc/org/eclipse/ecf/remoteservice/package-summary.html Remote Service API Javadoc]<br>
 
[http://download.eclipse.org/rt/ecf/latest/javadoc/org/eclipse/ecf/remoteservice/package-summary.html Remote Service API Javadoc]<br>
  
All RSA distribution providers implement the Remote Services API.
+
All ECF RSA distribution providers must implement the RSAPI.
 +
 
 +
==[http://www.grpc.io/ Google RPC (grcp)] Provider==
 +
 
 +
====OSGi Configuration Types/ECF Container Types====
 +
'''ecf.grpc.server'''<br>
 +
'''ecf.grpc.client'''<br>
 +
 
 +
For example, to export an instance of [https://github.com/ECF/grpc-RemoteServicesProvider/blob/master/examples/org.eclipse.ecf.examples.provider.grpc.helloworld.host/src/org/eclipse/ecf/examples/provider/grpc/helloworld/host/GreeterImpl.java GreeterImpl]
 +
 
 +
<pre>
 +
// Set required OSGi standard service property
 +
props.put("service.exported.interfaces","io.grpc.examples.helloworld.GreeterService");
 +
// Set OSGI standard service.exported.configs property to ecf.grpc.server
 +
props.put("service.exported.configs","ecf.grpc.server");
 +
// Set ecf.grpc.server-specific properties
 +
props.put("ecf.grcp.server.uriContext","http://myhost:51001");
 +
// With service properties, will export as a remote service via an instance of ecf.grcp.server
 +
bundleContext.registerService(io.grpc.examples.helloworld.GreeterService.class, new GreeterImpl(), props);
 +
</pre>
 +
 
 +
Another example of how to register and export a remote service using Declarative Services' @Component annotations
 +
<pre>
 +
package org.eclipse.ecf.examples.provider.grpc.helloworld.host;
 +
 
 +
import io.grpc.examples.helloworld.HelloReply;
 +
import io.grpc.examples.helloworld.HelloRequest;
 +
 
 +
import org.osgi.service.component.annotations.Component;
 +
 
 +
import io.grpc.examples.helloworld.GreeterGrpc.AbstractGreeter;
 +
import io.grpc.examples.helloworld.GreeterService;
 +
import io.grpc.stub.StreamObserver;
 +
 
 +
@Component(immediate = true, service = GreeterService.class, property = {
 +
"service.exported.interfaces=io.grpc.examples.helloworld.GreeterService",
 +
"service.exported.configs=ecf.grpc.server",
 +
"ecf.grpc.server.uriContext=http://localhost:50001" })
 +
public class GreeterImpl extends AbstractGreeter implements GreeterService {
 +
 
 +
@Override
 +
public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
 +
// Call synchronous version of method to get reply
 +
HelloReply reply = sayHello(req);
 +
responseObserver.onNext(reply);
 +
responseObserver.onCompleted();
 +
}
 +
 
 +
@Override
 +
public HelloReply sayHello(HelloRequest req) {
 +
// Respond with HelloReply with message "Hello there <name"
 +
return HelloReply.newBuilder().setMessage("Hello there " + req.getName()).build();
 +
}
 +
}
 +
</pre>
 +
 
 +
The entire project for this host example is [https://github.com/ECF/grpc-RemoteServicesProvider/tree/master/examples/org.eclipse.ecf.examples.provider.grpc.helloworld.host here] in the [https://github.com/ECF/grpc-RemoteServicesProvider grpc-RemoteServicesProvider repository].
 +
 
 +
===Bundles===
 +
 
 +
org.eclipse.ecf.provider.grpc<br>
 +
 
 +
===Dependencies===
 +
'''org.eclipse.ecf.provider.grpc''':  ECF Core, RSAPI
 +
 
 +
===Download/Install===
 +
 
 +
A build of this provider is available in '''[https://github.com/ECF/grpc-RemoteServicesProvider/tree/master/bundles/org.eclipse.ecf.provider.grpc/build/]''' directory.
 +
 
 +
===Source Code===
 +
 
 +
[https://github.com/ECF ECF Github] Repo: [https://github.com/ECF/grpc-RemoteServicesProvider ECF Google RPC Provider Github Repo], Paths:<br>
 +
'''org.eclipse.ecf.provider.grpc''': bundles/org.eclipse.ecf.provider.grcp<br>
 +
 
 +
If you would like to contribute to the build/releng or the coding for this provider, or engage the ECF committers for support or custom development, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].
 +
 
 +
==[http://www.xmlrpc.com/ XML-RPC Provider]==
 +
 
 +
====OSGi Configuration Types/ECF Container Types====
 +
'''ecf.xmlrpc.server'''<br>
 +
'''ecf.xmlrpc.client'''<br>
 +
 
 +
For example, to export an instance of TimeService
 +
 
 +
<pre>
 +
// Set required OSGi standard service property
 +
props.put("service.exported.interfaces","*");
 +
// Set OSGI standard service.exported.configs property to ecf.xmlrpc.server
 +
props.put("service.exported.configs","ecf.xmlrpc.server");
 +
// Set optional ecf.xmlrpc.server-specific properties
 +
props.put("ecf.xmlrpc.server.uriContext","http://myhost:51001");
 +
props.put("ecf.xmlrpc.server.uriPath","/myxml-rpc");
 +
// With service properties, will export as a remote service via an instance of ecf.xmlrpc.server
 +
bundleContext.registerService(TimeService.class, new TimeServiceImpl(), props);
 +
</pre>
 +
 
 +
===Bundles===
 +
 
 +
org.eclipse.ecf.provider.xmlrpc<br>
 +
 
 +
===Dependencies===
 +
'''org.eclipse.ecf.provider.xmlrpc''':  ECF Core, RSAPI, Apache commons logging >= 1.1.1
 +
 
 +
===Download/Install===
 +
 
 +
A build of this provider is available in '''[https://github.com/ECF/XmlRpcProvider/tree/master/bundles/org.eclipse.ecf.provider.xmlrpc/build/]''' directory.
 +
 
 +
===Source Code===
 +
 
 +
[https://github.com/ECF ECF Github] Repo: [https://github.com/ECF/XmlRpcProvider ECF XML-RPC Provider Github Repo], Paths:<br>
 +
'''org.eclipse.ecf.provider.xmlrpc''': bundles/org.eclipse.ecf.provider.xmlrpc<br>
 +
 
 +
If you would like to contribute to the build/releng or the coding for this provider, or engage the ECF committers for support or custom development, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].
  
 
==Generic Provider==
 
==Generic Provider==
Line 61: Line 173:
 
P2 Feature ID:  '''org.eclipse.ecf.provider.generic.remoteservice.feature'''<br>
 
P2 Feature ID:  '''org.eclipse.ecf.provider.generic.remoteservice.feature'''<br>
 
<br>
 
<br>
Karaf Feature:  '''ecf-remoteservices-distprovider-generic''' in repos given on [[EIG:Install_into_Apache_Karaf |  Karaf Installation Page]]
+
Karaf Feature:  '''ecf-remoteservices-sdk''' and '''ecf-remoteservices-distprovider-generic''' in repos given on [[EIG:Install_into_Apache_Karaf |  Karaf Installation Page]]
  
 
===Source Code===
 
===Source Code===
Line 117: Line 229:
 
java_websocket:  bundles/java_websocket<br>
 
java_websocket:  bundles/java_websocket<br>
 
<br>
 
<br>
These two bundles must currently be built from source.  We would like to setup a build for this project but need releng contributions to do so.  Please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post to the ecf-dev mailing list] to convey desire for this build or to contribute.
+
[http://hereandnow.wbur.org/2016/04/20/cape-kiwanda-safety Recent build of these bundles is available here]  
  
 
==JMS/ActiveMQ Provider==
 
==JMS/ActiveMQ Provider==
Line 135: Line 247:
 
props.put("service.exported.configs","ecf.jms.activemq.tcp.manager");
 
props.put("service.exported.configs","ecf.jms.activemq.tcp.manager");
 
// Set ecf.jms.activemq.tcp.manager-specific properties
 
// Set ecf.jms.activemq.tcp.manager-specific properties
props.put("ecf.jms.activemq.tcp.manager","tcp://localhost:61616/exampleTopic");
+
props.put("ecf.jms.activemq.tcp.manager.id","tcp://localhost:61616/exampleTopic");
 
// With service properties, will export as a remote service via an instance of ecf.jms.activemq.tcp.manager
 
// With service properties, will export as a remote service via an instance of ecf.jms.activemq.tcp.manager
 
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);
 
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);
Line 154: Line 266:
 
P2 Feature ID:  '''org.eclipse.ecf.provider.jms.feature'''<br>
 
P2 Feature ID:  '''org.eclipse.ecf.provider.jms.feature'''<br>
 
<br>
 
<br>
There is currently not a Karaf feature for these providers.  We would like to create a build for this project but need releng contributions to do so. Please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post to the ecf-dev mailing list] to convey desire for this build or to contribute.
+
Karaf Repo: [http://build.ecf-project.org/repo/C-HEAD-jms.feature/lastSuccessful/archive/site.p2/karaf-features.xml http://build.ecf-project.org/repo/C-HEAD-jms.feature/lastSuccessful/archive/site.p2/karaf-features.xml]<br>
 
+
Karaf Feature:  C-HEAD-jms.feature<br>
Further, in addition to the ecf-remoteservices-sdk Karaf feature, all that's necessary to use this provider is to install the following three bundles:
+
Karaf Feature Dependencies: The ecf-remoteservices-sdk feature must be previously installed to successfully install the C-HEAD-jms.feature feature.
 
+
#'''javax.jms''' 1.1 available [http://download.eclipse.org/tools/orbit/downloads/drops/R20150821153341/repository/plugins/javax.jms_1.1.0.v201205091237.jar from Orbit]
+
#'''org.eclipse.ecf.provider.jms''' available [http://build.ecf-project.org/repo/C-HEAD-jms.feature/lastSuccessful/archive/site.p2/plugins/ from ECF builder]
+
#'''org.eclipse.ecf.provider.jms.activemq''' also available [http://build.ecf-project.org/repo/C-HEAD-jms.feature/lastSuccessful/archive/site.p2/plugins/ from ECF builder]
+
  
 
===Source Code===
 
===Source Code===
Line 171: Line 279:
  
 
Note that the org.eclipse.ecf.provider.jms bundle contains most of the provider code, and that it only depends upon javax.jms.  This makes it straightforward to create new remote service providers based upon JMS implementations other than ActiveMQ.
 
Note that the org.eclipse.ecf.provider.jms bundle contains most of the provider code, and that it only depends upon javax.jms.  This makes it straightforward to create new remote service providers based upon JMS implementations other than ActiveMQ.
 +
 +
==MQTT Provider (Paho)==
 +
 +
The ECF team has created a Remote Service provider based upon the MQTT3 [https://www.eclipse.org/paho/ Paho] implementation.  We are currently using Paho version 1.0.2.
 +
 +
===OSGi Configuration Types/ECF Container Types===
 +
'''ecf.jms.mqtt.manager'''<br>
 +
'''ecf.jms.mqtt.client'''<br>
 +
 +
For example, to export an instance of MyServiceImpl
 +
 +
<pre>
 +
// Set required OSGi standard service property
 +
props.put("service.exported.interfaces","*");
 +
// Set OSGI standard service.exported.configs property to ecf.jms.mqtt.manager
 +
props.put("service.exported.configs","ecf.jms.mqtt.manager");
 +
// Set ecf.jms.mqtt.manager-specific properties
 +
props.put("ecf.jms.mqtt.manager.id","tcp://iot.eclipse.org:1883/exampleTopic");
 +
// With service properties, will export as a remote service via an instance of ecf.jms.mqtt.manager
 +
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);
 +
</pre>
 +
 +
===Bundles===
 +
 +
org.eclipse.ecf.provider.jms.mqtt
 +
 +
===Dependencies===
 +
'''org.eclipse.ecf.provider.jms.mqtt''':  org.eclipse.ecf.provider.jms from JMS/ActiveMQ Provider above.
 +
 +
===Download/Install===
 +
 +
[https://github.com/ECF/Mqtt-Provider/tree/master/bundles/org.eclipse.ecf.provider.jms.mqtt/build A recent build is available here]
 +
 +
===Source Code===
 +
 +
[https://github.com/ECF ECF Github] Repo: [https://github.com/ECF/Mqtt-Provider ECF MQTT Provider Github Repo], Paths:<br>
 +
'''org.eclipse.ecf.provider.jms.mqtt''': bundles/org.eclipse.ecf.provider.jms.mqtt
 +
 +
If you would like to contribute to the build/releng or the coding for this provider, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].
 +
 +
==Jax-RS REST Providers==
 +
 +
The ECF team has created several REST-based Remote Service providers, all of which are based upon the Jax-RS specification.  By using OSGi Remote Service standards along with Jax-RS standards, it's possible to create remote services that can be used on any compliant Jax-RS implementation, and any RSA-compliant Remote Services implementation.  For a tutorial on how this can work, see [[Tutorial:_Using_REST_and_OSGi_Standards_for_Micro_Services  | the tutorial Using REST and OSGi Standards for Micro Services]].
 +
 +
Since REST is based upon a client-server model of services, Remote Services based upon rest may only be exported on servers.  Clients may import, but are unable to export Remote Services.
 +
 +
===Jackson Jax-RS Implementation===
 +
 +
====OSGi Configuration Types/ECF Container Types====
 +
'''ecf.jaxrs.jersey.server'''<br>
 +
'''ecf.jaxrs.jersey.client'''<br>
 +
 +
For example, to export an instance of MyServiceImpl
 +
 +
<pre>
 +
// Set required OSGi standard service property
 +
props.put("service.exported.interfaces","*");
 +
// Set OSGI standard service.exported.configs property to ecf.jaxrs.jersey.server
 +
props.put("service.exported.configs","ecf.jaxrs.jersey.server");
 +
// Set ecf.jaxrs.jersey.server-specific properties
 +
props.put("ecf.jaxrs.jersey.server.urlContext","http://myhost:8080");
 +
props.put("ecf.jaxrs.jersey.server.alias","/myservice");  // corresponds to url context of:  http://myhost:8080/myservice
 +
// With service properties, will export as a remote service via an instance of ecf.jaxrs.jersey.server
 +
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);
 +
</pre>
 +
 +
====Bundles====
 +
 +
org.eclipse.ecf.provider.jersey.server<br>
 +
org.eclipse.ecf.provider.jaxrs.server<br>
 +
org.eclipse.ecf.provider.jaxrs
 +
 +
====Dependencies====
 +
'''org.eclipse.ecf.provider.jersey.server''':  org.eclipse.ecf.provider.jaxrs.server, org.eclipse.ecf.provider.jaxrs, javax.ws.rs (Jax-RS 2.0.1 or greater), ECF Core, RSAPI, Jersey 2.14 or greater plus full extent of Jersey 2.14 dependencies with necessary addins (e.g. JSON, XML, etc).
 +
 +
====Download/Install====
 +
 +
[https://github.com/ECF/JaxRSProviders/tree/master/bundles/org.eclipse.ecf.provider.jersey.server/build A recent build of the Jersey-based provider is available here] or [https://github.com/ECF/JaxRSProviders/tree/master/bundles/org.eclipse.ecf.provider.jersey.client/build here]
 +
 +
====Source Code====
 +
 +
[https://github.com/ECF ECF Github] Repo: [https://github.com/ECF/JaxRSProviders ECF JaxRS Providers Github Repo], Paths:<br>
 +
'''org.eclipse.ecf.provider.jersey.server''': bundles/org.eclipse.ecf.provider.jersey.server<br>
 +
'''org.eclipse.ecf.provider.jaxrs.server''': bundles/org.eclipse.ecf.provider.jaxrs.server<br>
 +
'''org.eclipse.ecf.provider.jaxrs''':  bundles/org.eclipse.ecf.provider.jaxrs<br>
 +
 +
If you would like to contribute to the build/releng or the coding for this provider, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].
 +
 +
===Apache CXF Jax-RS Implementation===
 +
 +
====OSGi Configuration Types/ECF Container Types====
 +
'''ecf.jaxrs.cxf.server'''<br>
 +
'''ecf.jaxrs.cxf.client'''<br>
 +
 +
For example, to export an instance of MyServiceImpl
 +
 +
<pre>
 +
// Set required OSGi standard service property
 +
props.put("service.exported.interfaces","*");
 +
// Set OSGI standard service.exported.configs property to ecf.jaxrs.cxf.server
 +
props.put("service.exported.configs","ecf.jaxrs.cxf.server");
 +
// Set ecf.jaxrs.cxf.server-specific properties
 +
props.put("ecf.jaxrs.cxf.server.urlContext","http://myhost:8080");
 +
props.put("ecf.jaxrs.cxf.server.alias","/myservice");  // corresponds to url context of:  http://myhost:8080/myservice
 +
// With service properties, will export as a remote service via an instance of ecf.jaxrs.cxf.server
 +
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);
 +
</pre>
 +
 +
====Bundles====
 +
 +
org.eclipse.ecf.provider.cxf.server<br>
 +
org.eclipse.ecf.provider.jaxrs.server<br>
 +
org.eclipse.ecf.provider.jaxrs
 +
 +
====Dependencies====
 +
'''org.eclipse.ecf.provider.jersey.server''':  org.eclipse.ecf.provider.jaxrs.server, org.eclipse.ecf.provider.jaxrs, javax.ws.rs (Jax-RS 2.0.1 or greater), ECF Core, RSAPI, CXF 3.1.2 or greater plus full extent of CXF 3.1.2 dependencies with necessary addins (e.g. JSON, XML, etc).
 +
 +
====Download/Install====
 +
 +
Currently we do not have a binary version of this provider available.  The primary reason for this is that the CXF 3.1.2 Jax-RS implementation has a complex set of dependencies, all of which have to be available at both compile time and runtime.  If you would like to contribute to the build/releng or the coding for this provider, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].
 +
 +
====Source Code====
 +
 +
[https://github.com/ECF ECF Github] Repo: [https://github.com/ECF/JaxRSProviders ECF JaxRS Providers Github Repo], Paths:<br>
 +
'''org.eclipse.ecf.provider.cxf.server''': bundles/org.eclipse.ecf.provider.cxf.server<br>
 +
'''org.eclipse.ecf.provider.jaxrs.server''': bundles/org.eclipse.ecf.provider.jaxrs.server<br>
 +
'''org.eclipse.ecf.provider.jaxrs''':  bundles/org.eclipse.ecf.provider.jaxrs<br>
 +
 +
If you would like to contribute to the build/releng or the coding for this provider, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].
 +
 +
==Providers created via ECF REST API==
 +
 +
ECF has provided an API to aid in the creation of REST-based Remote Services provider.  Using this API, it's possible to create a Remote Service client/proxy that uses an '''existing''' REST-based service.  Thus new Remote Services can be created to expose an existing REST-based service.  The following tutorial: [[Tutorial:_ECF_Remote_Services_for_Accessing_Existing_REST_Services | ECF Remote Services for Accessing Existing REST Services]] describes how to use the ECF REST API to create client provider to access an existing REST service.
 +
 +
===OSGi Configuration Types/ECF Container Types===
 +
'''ecf.rest.client'''<br>
 +
 +
As mentioned above, only REST servers may export Remote Services, so the ecf.rest.client provider may not export Remote Services.
 +
 +
===Bundles===
 +
 +
org.eclipse.ecf.remoteservice.rest<br>
 +
 +
===Dependencies===
 +
'''org.eclipse.ecf.remoteservice.rest''':  [[#Remote_Services_API | ECF core]], Apache HttpClient v4.3 or higher.
 +
 +
===Download/Install===
 +
 +
P2 Repo and Karaf Feature:  See [https://www.eclipse.org/ecf/downloads.php Download Page]<br>
 +
P2 Feature ID:  '''org.eclipse.ecf.remoteservice.rest.feature'''<br>
 +
<br>
 +
Karaf Feature:  '''ecf-remoteservices-rest''' in repos given on [[EIG:Install_into_Apache_Karaf |  Karaf Installation Page]]
 +
 +
===Source Code===
 +
 +
Git Repo: [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git ECF Git Repo], Paths:<br>
 +
'''org.eclipse.ecf.remoteservice.rest''': framework/bundles/org.eclipse.ecf.remoteservice.rest
 +
 +
==Hazelcast Provider==
 +
 +
====OSGi Configuration Types/ECF Container Types====
 +
'''ecf.jms.hazelcast.manager'''<br>
 +
'''ecf.jms.hazelcast.member'''<br>
 +
 +
For example, to export an instance of MyServiceImpl
 +
 +
<pre>
 +
// Set required OSGi standard service property
 +
props.put("service.exported.interfaces","*");
 +
// Set OSGI standard service.exported.configs property to ecf.jms.hazelcast.manager
 +
props.put("service.exported.configs","ecf.jms.hazelcast.manager");
 +
// Set ecf.jms.hazelcast.manager-specific properties
 +
props.put("ecf.jms.hazelcast.manager.id","hazelcast://localhost/exampleTopic");
 +
// With service properties, will export as a remote service via an instance of ecf.jms.hazelcast.manager
 +
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);
 +
</pre>
 +
 +
===Bundles===
 +
 +
org.eclipse.ecf.provider.jms.hazelcast<br>
 +
 +
===Dependencies===
 +
'''org.eclipse.ecf.provider.jms.hazelcast''':  org.eclipse.ecf.provider.jms from JMS provider above, ECF Core, RSAPI
 +
 +
===Download/Install===
 +
 +
[https://github.com/ECF/HazelcastProvider/tree/master/bundles/org.eclipse.ecf.provider.jms.hazelcast/build A recent build is available here]
 +
 +
===Source Code===
 +
 +
[https://github.com/ECF ECF Github] Repo: [https://github.com/ECF/HazelcastProvider ECF Hazelcast Provider Github Repo], Paths:<br>
 +
'''org.eclipse.ecf.provider.jms.hazelcast''': bundles/org.eclipse.ecf.provider.jms.hazelcast<br>
 +
 +
If you would like to contribute to the build/releng or the coding for this provider, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].
 +
 +
==JavaGroups (JGroups) Provider==
 +
 +
====OSGi Configuration Types/ECF Container Types====
 +
'''ecf.jgroups.manager'''<br>
 +
'''ecf.jgroups.client'''<br>
 +
 +
For example, to export an instance of MyServiceImpl
 +
 +
<pre>
 +
// Set required OSGi standard service property
 +
props.put("service.exported.interfaces","*");
 +
// Set OSGI standard service.exported.configs property to ecf.jgroups.manager
 +
props.put("service.exported.configs","ecf.jgroups.manager");
 +
// Set ecf.jgroups.manager-specific properties defined in JGroupsManagerContainer class
 +
props.put("ecf.jgroups.manager.managerId","jgroups:mygroupname");
 +
// With service properties, will export as a remote service via an instance of ecf.jgroups.manager
 +
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);
 +
</pre>
 +
 +
===Bundles===
 +
 +
org.eclipse.ecf.provider.jgroups<br>
 +
 +
===Dependencies===
 +
'''org.eclipse.ecf.provider.jgroups''':  org.jgroups (3.6.8.Final or more recent), ECF Core, RSAPI, org.eclipse.ecf.provider, org.eclipse.ecf.provider.remoteservice, org.eclipse.ecf.sharedobject
 +
 +
===Download/Install===
 +
 +
A build of this provider is available in '''[https://github.com/ECF/JGroups/tree/master/bundles/org.eclipse.ecf.provider.jgroups/build/ bundles/org.eclipse.ecf.provider.jgroups/build]''' directory.
 +
 +
===Source Code===
 +
 +
[https://github.com/ECF ECF Github] Repo: [https://github.com/ECF/https://github.com/ECF/JGroups ECF JavaGroups Provider Github Repo], Paths:<br>
 +
'''org.eclipse.ecf.provider.jgroups''': bundles/org.eclipse.ecf.provider.jgroups<br>
 +
 +
If you would like to contribute to the build/releng or the coding for this provider, please [https://dev.eclipse.org/mailman/listinfo/ecf-dev join and post a note to that effect to the ecf-dev mailing list].

Revision as of 12:59, 1 June 2016

Contents

Introduction

The Remote Services/Remote Service Admin specifications (chaps 100 and 122 in OSGi Enterprise spec) allows for the use of multiple distribution providers. A separate distribution provider(s) can be defined for every exported remote service. Such providers are responsible for the actual marshalling/serialization and network communication that takes place when a consumer invokes a remote service method.

The ECF Architecture also allows the use of multiple distribution providers. Further, ECF's open APIs and implementations supports the creation of custom distribution providers using any desired transport protocols, serialization formats and/or libraries.

Remote Services API

ECF's API for distribution providers is the Remote Services API (RSAPI). Implementing this API is the only thing required to create a RS/RSA standards compliant distribution provider.

Symbolic Name: org.eclipse.ecf.remoteservice
Minimum EE: J2SE-1.5+
Dependencies

  • Framework: OSGi R5+
  • ECF Core Bundles: org.eclipse.ecf, org.eclipse.ecf.identity
  • org.eclipse.equinox.concurrent.future bundle
  • org.eclipse.ecf.remoteservice.asyncproxy bundle version 1.X (Java 7) or 2.X (Java 8)

Remote Service API Javadoc

All ECF RSA distribution providers must implement the RSAPI.

Google RPC (grcp) Provider

OSGi Configuration Types/ECF Container Types

ecf.grpc.server
ecf.grpc.client

For example, to export an instance of GreeterImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","io.grpc.examples.helloworld.GreeterService");
// Set OSGI standard service.exported.configs property to ecf.grpc.server
props.put("service.exported.configs","ecf.grpc.server");
// Set ecf.grpc.server-specific properties
props.put("ecf.grcp.server.uriContext","http://myhost:51001");
// With service properties, will export as a remote service via an instance of ecf.grcp.server
bundleContext.registerService(io.grpc.examples.helloworld.GreeterService.class, new GreeterImpl(), props);

Another example of how to register and export a remote service using Declarative Services' @Component annotations

package org.eclipse.ecf.examples.provider.grpc.helloworld.host;

import io.grpc.examples.helloworld.HelloReply;
import io.grpc.examples.helloworld.HelloRequest;

import org.osgi.service.component.annotations.Component;

import io.grpc.examples.helloworld.GreeterGrpc.AbstractGreeter;
import io.grpc.examples.helloworld.GreeterService;
import io.grpc.stub.StreamObserver;

@Component(immediate = true, service = GreeterService.class, property = {
		"service.exported.interfaces=io.grpc.examples.helloworld.GreeterService",
		"service.exported.configs=ecf.grpc.server",
		"ecf.grpc.server.uriContext=http://localhost:50001" })
public class GreeterImpl extends AbstractGreeter implements GreeterService {

	@Override
	public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
		// Call synchronous version of method to get reply
		HelloReply reply = sayHello(req);
		responseObserver.onNext(reply);
		responseObserver.onCompleted();
	}

	@Override
	public HelloReply sayHello(HelloRequest req) {
		// Respond with HelloReply with message "Hello there <name"
		return HelloReply.newBuilder().setMessage("Hello there " + req.getName()).build();
	}
}

The entire project for this host example is here in the grpc-RemoteServicesProvider repository.

Bundles

org.eclipse.ecf.provider.grpc

Dependencies

org.eclipse.ecf.provider.grpc: ECF Core, RSAPI

Download/Install

A build of this provider is available in [1] directory.

Source Code

ECF Github Repo: ECF Google RPC Provider Github Repo, Paths:
org.eclipse.ecf.provider.grpc: bundles/org.eclipse.ecf.provider.grcp

If you would like to contribute to the build/releng or the coding for this provider, or engage the ECF committers for support or custom development, please join and post a note to that effect to the ecf-dev mailing list.

XML-RPC Provider

OSGi Configuration Types/ECF Container Types

ecf.xmlrpc.server
ecf.xmlrpc.client

For example, to export an instance of TimeService

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.xmlrpc.server
props.put("service.exported.configs","ecf.xmlrpc.server");
// Set optional ecf.xmlrpc.server-specific properties
props.put("ecf.xmlrpc.server.uriContext","http://myhost:51001");
props.put("ecf.xmlrpc.server.uriPath","/myxml-rpc");
// With service properties, will export as a remote service via an instance of ecf.xmlrpc.server
bundleContext.registerService(TimeService.class, new TimeServiceImpl(), props);

Bundles

org.eclipse.ecf.provider.xmlrpc

Dependencies

org.eclipse.ecf.provider.xmlrpc: ECF Core, RSAPI, Apache commons logging >= 1.1.1

Download/Install

A build of this provider is available in [2] directory.

Source Code

ECF Github Repo: ECF XML-RPC Provider Github Repo, Paths:
org.eclipse.ecf.provider.xmlrpc: bundles/org.eclipse.ecf.provider.xmlrpc

If you would like to contribute to the build/releng or the coding for this provider, or engage the ECF committers for support or custom development, please join and post a note to that effect to the ecf-dev mailing list.

Generic Provider

All the generic providers are based upon a tcp-based asynchronous messaging transport.

OSGi Configuration Types/ECF Container Types

ecf.generic.server
ecf.generic.client
ecf.generic.ssl.server
ecf.generic.ssl.client

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.generic.server
props.put("service.exported.configs","ecf.generic.server");
// Set ecf.generic.server-specific properties
props.put("ecf.generic.server.port","2121");
props.put("ecf.generic.server.hostname","mycompanyhost.com");
// With service properties, will export as a remote service via an instance of ecf.generic.server 
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

See here for a description for generic-provider-specific service properties such as ecf.generic.server.hostname, ecf.generic.server.port, etc.

Bundles

org.eclipse.ecf.provider
org.eclipse.ecf.provider.remoteservice

Dependencies

org.eclipse.ecf.provider: ECF core, org.eclipse.ecf.sharedobject
org.eclipse.ecf.provider.remoteservice: org.eclipse.ecf.provider, RSAPI

Download/Install

P2 Repo and Karaf Feature: See Download Page
P2 Feature ID: org.eclipse.ecf.provider.generic.remoteservice.feature

Karaf Feature: ecf-remoteservices-sdk and ecf-remoteservices-distprovider-generic in repos given on Karaf Installation Page

Source Code

Git Repo: ECF Git Repo, Paths:
org.eclipse.ecf.provider: framework/bundles/org.eclipse.ecf.provider
org.eclipse.ecf.provider.remoteservice: providers/bundles/org.eclipse.ecf.provider.remoteservice

r-OSGi Provider

OSGi Configuration Types/ECF Container Types

ecf.r_osgi.peer
ecf.r_osgi.peer.ws (see r-OSGi over Websockets below)
ecf.r_osgi.peer.wss (see r-OSGi over Websockets below)

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.generic.server
props.put("service.exported.configs","ecf.r_osgi.peer");
// With service properties, will export as a remote service via an instance of ecf.generic.server 
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

See here for a description for rosgi-provider System properties.

Bundles

org.eclipse.ecf.provider.r_osgi
ch.ethz.iks.r_osgi.remote

Dependencies

ch.ethz.iks.r_osgi.remote: org.objectweb.asm
org.eclipse.ecf.provider.r_osgi: ch.ethz.iks.r_osgi.remote, ECF core, RSAPI

Download/Install

P2 Repo and Karaf Feature: See Download Page
P2 Feature ID: org.eclipse.ecf.remoteservice.rosgi.feature

Karaf Feature: ecf-remoteservices-distprovider-rosgi in repos given on Karaf Installation Page

Source Code

Git Repo: ECF Git Repo, Paths:
ch.ethz.iks.r_osgi.remote: protocols/bundles/ch.ethz.iks.r_osgi.remote
org.eclipse.ecf.provider.remoteservice: providers/bundles/org.eclipse.ecf.provider.r_osgi

r-OSGi over Websockets

The two r-OSGi providers: ecf.r_osgi.peer.ws, and ecf.r_osgi.peer.wss are supported by adding two additional bundles: ch.ethz.iks.r_osgi.transport.http, and Java Websocket. These two bundles are available in the ECF Github Websockets Repo, at the following paths:
ch.ethz.iks.r_osgi.transport.http: bundles/ch.ethz.iks.r_osgi.transport.http
java_websocket: bundles/java_websocket

Recent build of these bundles is available here

JMS/ActiveMQ Provider

All the JMS/ActiveMQ providers are based upon the Java Messaging Service (JMS) specification version 1.1.

OSGi Configuration Types/ECF Container Types

ecf.jms.activemq.tcp.manager
ecf.jms.activemq.tcp.client

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.jms.activemq.tcp.manager
props.put("service.exported.configs","ecf.jms.activemq.tcp.manager");
// Set ecf.jms.activemq.tcp.manager-specific properties
props.put("ecf.jms.activemq.tcp.manager.id","tcp://localhost:61616/exampleTopic");
// With service properties, will export as a remote service via an instance of ecf.jms.activemq.tcp.manager
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

Bundles

org.eclipse.ecf.provider.jms
org.eclipse.ecf.provider.jms.activemq (based upon ActiveMQ 5.12 currently...see source code).

Dependencies

org.eclipse.ecf.provider.jms: javax.jms (1.1), ECF core, RSAPI, org.eclipse.ecf.provider, org.eclipse.ecf.provider.remoteservice
org.eclipse.ecf.provider.jms.activemq: org.eclipse.ecf.provider.jms

Download/Install

P2 Repo: http://build.ecf-project.org/repo/C-HEAD-jms.feature/lastSuccessful/archive/site.p2/
P2 Feature ID: org.eclipse.ecf.provider.jms.feature

Karaf Repo: http://build.ecf-project.org/repo/C-HEAD-jms.feature/lastSuccessful/archive/site.p2/karaf-features.xml
Karaf Feature: C-HEAD-jms.feature
Karaf Feature Dependencies: The ecf-remoteservices-sdk feature must be previously installed to successfully install the C-HEAD-jms.feature feature.

Source Code

ECF Github Repo: ECF JMS Github Repo, Paths:
org.eclipse.ecf.provider.jms: bundles/org.eclipse.ecf.provider.jms
org.eclipse.ecf.provider.jms.activemq: bundles/org.eclipse.ecf.provider.jms.activemq

If you would like to contribute to the build/releng or the coding for this provider, please join and post a note to that effect to the ecf-dev mailing list.

Note that the org.eclipse.ecf.provider.jms bundle contains most of the provider code, and that it only depends upon javax.jms. This makes it straightforward to create new remote service providers based upon JMS implementations other than ActiveMQ.

MQTT Provider (Paho)

The ECF team has created a Remote Service provider based upon the MQTT3 Paho implementation. We are currently using Paho version 1.0.2.

OSGi Configuration Types/ECF Container Types

ecf.jms.mqtt.manager
ecf.jms.mqtt.client

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.jms.mqtt.manager
props.put("service.exported.configs","ecf.jms.mqtt.manager");
// Set ecf.jms.mqtt.manager-specific properties
props.put("ecf.jms.mqtt.manager.id","tcp://iot.eclipse.org:1883/exampleTopic");
// With service properties, will export as a remote service via an instance of ecf.jms.mqtt.manager
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

Bundles

org.eclipse.ecf.provider.jms.mqtt

Dependencies

org.eclipse.ecf.provider.jms.mqtt: org.eclipse.ecf.provider.jms from JMS/ActiveMQ Provider above.

Download/Install

A recent build is available here

Source Code

ECF Github Repo: ECF MQTT Provider Github Repo, Paths:
org.eclipse.ecf.provider.jms.mqtt: bundles/org.eclipse.ecf.provider.jms.mqtt

If you would like to contribute to the build/releng or the coding for this provider, please join and post a note to that effect to the ecf-dev mailing list.

Jax-RS REST Providers

The ECF team has created several REST-based Remote Service providers, all of which are based upon the Jax-RS specification. By using OSGi Remote Service standards along with Jax-RS standards, it's possible to create remote services that can be used on any compliant Jax-RS implementation, and any RSA-compliant Remote Services implementation. For a tutorial on how this can work, see the tutorial Using REST and OSGi Standards for Micro Services.

Since REST is based upon a client-server model of services, Remote Services based upon rest may only be exported on servers. Clients may import, but are unable to export Remote Services.

Jackson Jax-RS Implementation

OSGi Configuration Types/ECF Container Types

ecf.jaxrs.jersey.server
ecf.jaxrs.jersey.client

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.jaxrs.jersey.server
props.put("service.exported.configs","ecf.jaxrs.jersey.server");
// Set ecf.jaxrs.jersey.server-specific properties
props.put("ecf.jaxrs.jersey.server.urlContext","http://myhost:8080");
props.put("ecf.jaxrs.jersey.server.alias","/myservice");  // corresponds to url context of:  http://myhost:8080/myservice
// With service properties, will export as a remote service via an instance of ecf.jaxrs.jersey.server
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

Bundles

org.eclipse.ecf.provider.jersey.server
org.eclipse.ecf.provider.jaxrs.server
org.eclipse.ecf.provider.jaxrs

Dependencies

org.eclipse.ecf.provider.jersey.server: org.eclipse.ecf.provider.jaxrs.server, org.eclipse.ecf.provider.jaxrs, javax.ws.rs (Jax-RS 2.0.1 or greater), ECF Core, RSAPI, Jersey 2.14 or greater plus full extent of Jersey 2.14 dependencies with necessary addins (e.g. JSON, XML, etc).

Download/Install

A recent build of the Jersey-based provider is available here or here

Source Code

ECF Github Repo: ECF JaxRS Providers Github Repo, Paths:
org.eclipse.ecf.provider.jersey.server: bundles/org.eclipse.ecf.provider.jersey.server
org.eclipse.ecf.provider.jaxrs.server: bundles/org.eclipse.ecf.provider.jaxrs.server
org.eclipse.ecf.provider.jaxrs: bundles/org.eclipse.ecf.provider.jaxrs

If you would like to contribute to the build/releng or the coding for this provider, please join and post a note to that effect to the ecf-dev mailing list.

Apache CXF Jax-RS Implementation

OSGi Configuration Types/ECF Container Types

ecf.jaxrs.cxf.server
ecf.jaxrs.cxf.client

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.jaxrs.cxf.server
props.put("service.exported.configs","ecf.jaxrs.cxf.server");
// Set ecf.jaxrs.cxf.server-specific properties
props.put("ecf.jaxrs.cxf.server.urlContext","http://myhost:8080");
props.put("ecf.jaxrs.cxf.server.alias","/myservice");  // corresponds to url context of:  http://myhost:8080/myservice
// With service properties, will export as a remote service via an instance of ecf.jaxrs.cxf.server
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

Bundles

org.eclipse.ecf.provider.cxf.server
org.eclipse.ecf.provider.jaxrs.server
org.eclipse.ecf.provider.jaxrs

Dependencies

org.eclipse.ecf.provider.jersey.server: org.eclipse.ecf.provider.jaxrs.server, org.eclipse.ecf.provider.jaxrs, javax.ws.rs (Jax-RS 2.0.1 or greater), ECF Core, RSAPI, CXF 3.1.2 or greater plus full extent of CXF 3.1.2 dependencies with necessary addins (e.g. JSON, XML, etc).

Download/Install

Currently we do not have a binary version of this provider available. The primary reason for this is that the CXF 3.1.2 Jax-RS implementation has a complex set of dependencies, all of which have to be available at both compile time and runtime. If you would like to contribute to the build/releng or the coding for this provider, please join and post a note to that effect to the ecf-dev mailing list.

Source Code

ECF Github Repo: ECF JaxRS Providers Github Repo, Paths:
org.eclipse.ecf.provider.cxf.server: bundles/org.eclipse.ecf.provider.cxf.server
org.eclipse.ecf.provider.jaxrs.server: bundles/org.eclipse.ecf.provider.jaxrs.server
org.eclipse.ecf.provider.jaxrs: bundles/org.eclipse.ecf.provider.jaxrs

If you would like to contribute to the build/releng or the coding for this provider, please join and post a note to that effect to the ecf-dev mailing list.

Providers created via ECF REST API

ECF has provided an API to aid in the creation of REST-based Remote Services provider. Using this API, it's possible to create a Remote Service client/proxy that uses an existing REST-based service. Thus new Remote Services can be created to expose an existing REST-based service. The following tutorial: ECF Remote Services for Accessing Existing REST Services describes how to use the ECF REST API to create client provider to access an existing REST service.

OSGi Configuration Types/ECF Container Types

ecf.rest.client

As mentioned above, only REST servers may export Remote Services, so the ecf.rest.client provider may not export Remote Services.

Bundles

org.eclipse.ecf.remoteservice.rest

Dependencies

org.eclipse.ecf.remoteservice.rest: ECF core, Apache HttpClient v4.3 or higher.

Download/Install

P2 Repo and Karaf Feature: See Download Page
P2 Feature ID: org.eclipse.ecf.remoteservice.rest.feature

Karaf Feature: ecf-remoteservices-rest in repos given on Karaf Installation Page

Source Code

Git Repo: ECF Git Repo, Paths:
org.eclipse.ecf.remoteservice.rest: framework/bundles/org.eclipse.ecf.remoteservice.rest

Hazelcast Provider

OSGi Configuration Types/ECF Container Types

ecf.jms.hazelcast.manager
ecf.jms.hazelcast.member

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.jms.hazelcast.manager
props.put("service.exported.configs","ecf.jms.hazelcast.manager");
// Set ecf.jms.hazelcast.manager-specific properties
props.put("ecf.jms.hazelcast.manager.id","hazelcast://localhost/exampleTopic");
// With service properties, will export as a remote service via an instance of ecf.jms.hazelcast.manager
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

Bundles

org.eclipse.ecf.provider.jms.hazelcast

Dependencies

org.eclipse.ecf.provider.jms.hazelcast: org.eclipse.ecf.provider.jms from JMS provider above, ECF Core, RSAPI

Download/Install

A recent build is available here

Source Code

ECF Github Repo: ECF Hazelcast Provider Github Repo, Paths:
org.eclipse.ecf.provider.jms.hazelcast: bundles/org.eclipse.ecf.provider.jms.hazelcast

If you would like to contribute to the build/releng or the coding for this provider, please join and post a note to that effect to the ecf-dev mailing list.

JavaGroups (JGroups) Provider

OSGi Configuration Types/ECF Container Types

ecf.jgroups.manager
ecf.jgroups.client

For example, to export an instance of MyServiceImpl

// Set required OSGi standard service property
props.put("service.exported.interfaces","*");
// Set OSGI standard service.exported.configs property to ecf.jgroups.manager
props.put("service.exported.configs","ecf.jgroups.manager");
// Set ecf.jgroups.manager-specific properties defined in JGroupsManagerContainer class
props.put("ecf.jgroups.manager.managerId","jgroups:mygroupname");
// With service properties, will export as a remote service via an instance of ecf.jgroups.manager
bundleContext.registerService(MyService.class, new MyServiceImpl(), props);

Bundles

org.eclipse.ecf.provider.jgroups

Dependencies

org.eclipse.ecf.provider.jgroups: org.jgroups (3.6.8.Final or more recent), ECF Core, RSAPI, org.eclipse.ecf.provider, org.eclipse.ecf.provider.remoteservice, org.eclipse.ecf.sharedobject

Download/Install

A build of this provider is available in bundles/org.eclipse.ecf.provider.jgroups/build directory.

Source Code

ECF Github Repo: ECF JavaGroups Provider Github Repo, Paths:
org.eclipse.ecf.provider.jgroups: bundles/org.eclipse.ecf.provider.jgroups

If you would like to contribute to the build/releng or the coding for this provider, please join and post a note to that effect to the ecf-dev mailing list.

Back to the top