| :doctype: book |
| |
| Title: Remote Service Admin |
| |
| = RSA (Remote Service Admin) |
| |
| The Aries Remote Service Admin (RSA) project allows to transparently use OSGi services for remote communication. |
| OSGi services can be marked for export by adding a service property `service.exported.interfaces=*`. |
| Various other properties can be used to customize how the service is to be exposed. |
| |
| For more information, check out section "122 JPA Service Specification Version 1.0" in the "OSGi Service Platform Enterprise Specification, Release 4, Version 4.2" available for public download from the http://www.osgi.org/Download/Release4V43[OSGi Alliance]. |
| |
| == Source |
| |
| The Aries RSA source is in a separate https://git-wip-us.apache.org/repos/asf/aries-rsa.git[git repository aries-rsa] there is also a https://github.com/apache/aries-rsa[mirror on github]. |
| |
| == Build |
| |
| mvn clean install |
| |
| == Architecture |
| |
| image::https://cwiki.apache.org/confluence/download/attachments/30739778/remote-service-admin-spec.png?version=2&modificationDate=1362365400000&api=v2[Remote Service Admin Architecture overview] |
| |
| === Some definitions |
| |
| * EndpointDescription Describes a remote service using service interfaces, remote url and all other properties to import the remote service. |
| * EndpointListener a service that is to be notified when remote Endpoints described by OSGi filters appear or disappear. |
| |
| === https://github.com/apache/aries-rsa/tree/master/topology-manager[Topology Manager] |
| |
| * Listens to local services and decides which to expose. |
| It can also add properties to change the way services are exposed. |
| For the services to be exported it calls RemoteServiceAdmin.exportService to do the actual export. |
| Then notifies EndpointListeners about the new Endpoint. |
| * Listens for service requests from consumers and creates EndpointListeners for these interests. |
| |
| The TopologyManager by default exposes all suitably marked local services for export and imports all service interests with matching remote Endpoints. |
| |
| It is the best place to implement system wide governance rules. |
| Some examples what can be done: |
| |
| * Enhancing all exposed remote endpoints with SSL, basic auth, logging |
| * Exporting OSGi services with annotations for JAX-WS or JAX-RS even when not specially marked for export |
| |
| According to its role the TopologyManager of course does not directly implement the enhancements above. |
| It simply creates the necessary calls to a suitable RemoteServiceAdmin. |
| |
| === https://github.com/apache/aries-rsa/tree/master/rsa[Remote Service Admin] |
| |
| Is called by the Topology Manager to expose local services as remote endpoints and create local proxy services as clients for remote endpoints. |
| |
| Aries RSA has a custom SPI https://github.com/apache/aries-rsa/blob/master/spi/src/main/java/org/apache/aries/rsa/spi/DistributionProvider.java[DistributionProvider] that allows to easily create new transports and serializations. |
| Existing providers are: |
| |
| * http://cxf.apache.org/distributed-osgi.html[CXF-DOSGi] |
| ** uses Apache CXF for transport |
| ** service endpoints consumable with non-java software (XML/JSON) |
| * https://github.com/apache/aries-rsa/tree/master/provider/tcp[TCP] |
| ** Java serialization over TCP (one port per service) |
| ** very few dependencies |
| ** easy to comprehend blueprint for own transport implementations |
| * https://github.com/apache/aries-rsa/tree/master/provider/fastbin[Fastbin] |
| ** tuned Java serialization (or Protobuf) over TCP using NIO |
| ** multiplexing over a single port |
| ** transparently handles InputSteams and OutputStreams in remote services |
| ** synchronous and asnychronous calls supported |
| |
| === Discovery |
| |
| A discovery implementation uses EndpointListeners to listen for local Endpoints and publishs them for other containers. |
| It also listens to remote Endpoints and notifies EndpointListeners about their presence. |
| |
| Existing implementations: |
| |
| * https://github.com/apache/aries-rsa/tree/master/discovery/local[Local discovery] using xml descriptors |
| * https://github.com/apache/aries-rsa/tree/master/discovery/zookeeper[Zookeeper based discovery] |
| |
| == A simple example using Apache Karaf |
| |
| See https://github.com/apache/aries-rsa/tree/master/examples/echotcp[EchoTCP example]. |
| Follow the Readme to install the example in Apache Karaf. |
| |
| The EchoTCP example implements a simple echo service that can be called remotely. |
| The example uses declarative services to publish and bind services. |
| |
| === Modules |
| |
| * api : EchoService interface |
| * service : EchoService implementation |
| * consumer : Small consumer that uses the EchoService |
| |
| The example installation uses the tcp transport to do the remoting but the example code is not tied to any transport. |
| |
| == Example using fastbin transport |
| |
| A similar https://github.com/apache/aries-rsa/tree/master/examples/echofastbin[example] exists for the fastbin transport . Follow the Readme to install the example in Apache Karaf. |
| |
| The example implements an echo service that showcases synchronous calls, asnychronous calls and InputStream as parameter and return value. |