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 [OSGi Alliance](http://www.osgi.org/Download/Release4V43).

## Source

The Aries RSA source is in a separate [git repository aries-rsa][1] there is also a [mirror on github][2].

## Build

    mvn clean install

## Architecture

![Remote Service Admin Architecture overview][3]

### 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.

### [Topology Manager][4]

* 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.

### [Remote Service Admin][5]

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 [DistributionProvider][6] that allows to easily create new transports and serializations.
Existing providers are:

  - [CXF-DOSGi][7]
    - uses Apache CXF for transport
    - service endpoints consumable with non-java software (XML/JSON)   
  - [TCP][8]
    - Java serialization over TCP (one port per service)
    - very few dependencies
    - easy to comprehend blueprint for own transport implementations
  - [Fastbin][9] 
    - 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:

  - [Local discovery][10] using xml descriptors
  - [Zookeeper based discovery][11]

## A simple example using Apache Karaf

See [EchoTCP example][12]. 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 [example][13] 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.


  [1]: https://git-wip-us.apache.org/repos/asf/aries-rsa.git
  [2]: https://github.com/apache/aries-rsa
  [3]: https://cwiki.apache.org/confluence/download/attachments/30739778/remote-service-admin-spec.png?version=2&modificationDate=1362365400000&api=v2
  [4]: https://github.com/apache/aries-rsa/tree/master/topology-manager
  [5]: https://github.com/apache/aries-rsa/tree/master/rsa
  [6]: https://github.com/apache/aries-rsa/blob/master/spi/src/main/java/org/apache/aries/rsa/spi/DistributionProvider.java
  [7]: http://cxf.apache.org/distributed-osgi.html
  [8]: https://github.com/apache/aries-rsa/tree/master/provider/tcp
  [9]: https://github.com/apache/aries-rsa/tree/master/provider/fastbin
  [10]: https://github.com/apache/aries-rsa/tree/master/discovery/local
  [11]: https://github.com/apache/aries-rsa/tree/master/discovery/zookeeper
  [12]: https://github.com/apache/aries-rsa/tree/master/examples/echotcp
  [13]: https://github.com/apache/aries-rsa/tree/master/examples/echofastbin