View source for EIG:Remote Services Admin

Since ECF has provided a full implementation of the OSGi Remote Services specification.  This specification for remote services (RS) is in the OSGi 5 enterprise specification, chapter 100, and the remote service admin (RSA) is in the OSGi enterprise specification, chapter 122.  You can [http://www.osgi.org/Download/HomePage download specifications here].

==What's Remote Services Admin?==

RSA (chapter 122) is the specification of a '''management agent''' for remote services.  The RS spec (chapter 100)], defines the programmer-specified service properties for exporting an OSGi service as a remote service, but does not say anything about the mechanism or implementation of the two major subsystems involved:  '''discovery''' (for knowing that a remote service is available on some network), and '''distribution''' (for accessing and using that remote service).  For those that need to control and/or customize the actual discovery and distribution of an OSGi service over a network, the management agent specified by RSA allows them to have a much greater degree of control...i.e. to allow them to more easily '''secure''' remote services, to optionally use multiple/alternative communications protocols for both discovery and distribution, to '''customize and extend''' the behavior of both discovery and distribution as needed for more complex/enterprise use cases.  The RSA specification defines the API for this remote services management agent, and ECF provides a complete/spec-compliant, small, easily customizable and extensible, cross-framework implementation.

==ECF's RSA Implementation==

The RSA implementation uses [[ECF API Docs | ECF's discovery API]] and [[ECF API Docs | ECF's Remote Service API]] to implement the management agent's '''discovery''' and '''distribution''' subsystems.  ECF's RSA implementation is complete and fully compliant with the specfication.  We are in the process of getting access to the OSGi Test Compatibility Kit (TCK), and will verify full compliance with the specification through use of that TCK as soon as possible.

===Unique ECF-provided Features===

====Transport Independence====

Since both the discovery and remote services apis are transport independent, and the ECF RSA implementation only uses these APIs themselves, the ECF RSA impl is also transport independent, allowing remote services to 'mix and match' discovery and distribution systems.  For example, ECF currently has discovery providers based upon the following network discovery protocols:

*Apache Zookeeper
*Bonjour/Zeroconf
*Service Locator Protocol/SLP
*DNS-SD (DNS Service Discovery)
*Others

and the following distribution providers

*R-osgi
*ECF Generic
*REST-based protocols
*SOAP-based protocols
*JMS-based protocols
*XMPP
*JavaGroups
*Others

Discovery and distribution providers...implemented as OSGi modules...may be mixed and matched in order to satisfy development-time and/or deployment-time requirements...for remote service security, for scalability, and/or for interoperability and integration with existing systems.

As well, new (proprietary or open) discovery providers and/or distribution providers can be easily created and used as specification-compliant implementations of both RS and RSA...without any changes to the applications that export remote services or use RSA specification-defined programmatic API.  This is possible because of ECF's transport-independent, open, community-tested APIs (discovery and remote services).  

Further, ECF's transport independence makes it extremely convenient to develop and test remote services using one discovery provider (e.g. Bonjour/Zeroconf) and deploy with another (e.g. Zookeeper).

====Asynchronous Remote Services====

In addition to fully supporting the OSGi-specified synchronous remote services, ECF provides the means to easily define and use asynchronous remote services.  This capability is described with code examples [[ECF/Asynchronous_Remote_Services | here]].

====Cross-Framework====

ECF's RSA implementation is written to OSGi specifications, and so can/does run on multiple OSGi frameworks.  We have some (small) amount of cross-framework testing, but are looking to do much more.  [http://www.eclipse.org/equinox/ Equinox] is currently our primary framework (for development and testing), and [https://github.com/ECF/ECF4Felix Felix] has been minimally tested.  We would be very interested in working with anyone willing to help us test more thoroughly on Felix or other OSGi frameworks.

===Source Code===

ECF has moved to git for source code control, and the ECF repo can be found [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git here].

The main bundles for the RSA are in '''osgi/bundles''' in the following projects:

*'''org.eclipse.ecf.osgi.remoteserviceadmin''': OSGi-provided specified API classes
*'''org.eclipse.ecf.osgi.services.remoteserviceadmin''': The ECF RSA implementation
*'''org.eclipse.ecf.osgi.services.remoteserviceadmin.proxy'''

==Bug Reporting and Support==

For support in use of ECF's RSA implementation, see the [https://dev.eclipse.org/mailman/listinfo/ecf-dev  ecf-dev mailing list]. 

To report bugs for the ECF RSA implementation open a bug with the component=ecf.remoteservices and subject line containing '''[remoteserviceadmin]''' [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=ECF here].

==Architecture==

From the [http://www.osgi.org/download/r4v42/r4.enterprise.pdf RSA specification], here is a high-level diagram of the RSA Architecture

[[Image:Rsa1.png]]

There are two roles that use these system entities:

*'''Service Host'''.  This is the OSGi framework that '''exports''' an OSGi service, making it available for remote access and optionally publishing it for network discovery.  The entities from the architecture diagram involved in host export are the '''Topology Manager Impl''' (for deciding when/what services to export), the '''Remote Service Admin impl''' (for actually performing the export), and the '''Discovery Impl''' (for publishing the remote service for automatic discovery.

*'''Service Consumer'''.  This is the OSGi framework that '''imports''' an OSGi service, creating a proxy for the remote service, and then registering the proxy in the '''local''' OSGi service registry.  The entities from the architecture diagram involved in consumer import are the '''Topology Manager Impl''' (for deciding when/what services to import),  the '''Remote Service Admin impl''' (for actually performing the import as described above), and the '''Discovery Impl''' (for discovering the remote service via some discovery mechanism).

==Topology Managers==

Part of the flexibility provided by the RSA specification is that there can be many different impls of Topology Managers.  This allows those that wish to control the export (on service host), or import (on service consumer) to do so simply by creating their own Topology Manager.  ECF's implementation of the RSA specification supports creating custom Topology Managers...either by customizing the ECF '''BasicTopologyManager''' [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/internal/osgi/services/distribution/BasicTopologyManager.java src],extending the ECF '''AbstractTopologyManager''' [http://download.eclipse.org/rt/ecf/3.5Test/javadoc/org/eclipse/ecf/osgi/services/remoteserviceadmin/AbstractTopologyManager.html javadoc],[http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/osgi/bundles/org.eclipse.ecf.osgi.services.remoteserviceadmin/src/org/eclipse/ecf/osgi/services/remoteserviceadmin/AbstractTopologyManager.java src], or by creating one's own TopologyManager implementation entirely, and accessing the ECF impl of the Remote Service Admin service (via ServiceTracker, declarative services, or other mechanism for accessing an OSGi service).  Note that the TopologyManagers that come with ECF's RSA impl can also be used as examples for creating one's own Topology Manager.

For a more complete description of the role for Topology Managers in RSA, see section 122.3 of the OSGi enterprise specification.

==Remote Service Admin==

ECF's impl of the RSA spec includes a full implementation of the Remote Service Admin service.  This service is specified by the OSGi service type '''org.osgi.service.remoteserviceadmin.RemoteServiceAdmin'''.  See section 122.10.10 for a detailed description of this service.  The RemoteServiceAdmin has the two key methods for exporting and importing a remote service:

<pre>
public Collection<ExportRegistration> exportService(ServiceReference reference, Map<String,
Object> properties)

and

public ImportRegistration importService(EndpointDescription endpoint)
</pre>

For a complete description of the role of RemoteServiceAdmin, see section 122.5 of the OSGi enterprise specification.

===Notification of Remote Service Admin Events===

The Remote Service Admin service will generate events...e.g. upon remote service export and upon remote service import.   These events are defined as instances of '''org.osgi.service.remoteserviceadmin.RemoteServiceAdminEvent'''.  See section 122.10.11 for a description of these event types.  Note that the RSA notification mechanisms (both synchronous and asynchronous) provide a useful mechanism for testing and debugging the RSA export (on host) and import (on consumer).

====RemoteServiceAdminListener for Synchronous Notification====

For applications that wish to be '''synchronously''' notified of remote service exports and imports, there is the  '''org.osgi.service.remoteserviceadmin.RemoteServiceAdminListener''' interface.  To receive RemoteServiceAdmin events, all that's necessary is to implement the '''RemoteServiceAdminListener''' interface, and register your implementation as an OSGi service using the whiteboard pattern...e.g.:

<pre>
bundleContext.registerService(RemoteServiceAdminListener.class.getName(),new MyRemoteServiceAdminListener(),null);
</pre>

Please see [[EIG:RemoteServiceAdminListener | Remote Service Admin Listener]] for a more complete description of this standard synchronous notification mechanism.

====EventHandler for Asynchronous Notification====

For applications that wish to be '''asynchronously''' notified of remote service exports and imports, the specification defines an Event Admin topic to which RemoteServiceAdminEvents are asynchronously delivered.  The topic for EventHandlers to be asynchronously notified of RemoteServiceAdmin events is '''org/osgi/service/remoteserviceadmin/<type>''', where '''<type>''' is one of the enumerated types on the RemoteServiceAdminEvent class...documented in secion 122.10.11 of the OSGi 4.2 enterprise specification.  Example:  '''org/osgi/service/remoteserviceadmin/EXPORT_REGISTRATION'''.

==Remote Service Admin Discovery==

The RSA specification standardizes the meta-data for describing remote services, allowing arbitrary remote services to be published upon export, and discovered by consumers (possibly leading to import).  This standardized form of remote service meta-data is called the EndpointDescription, and in ECF is represented by the class EndpointDescription [http://download.eclipse.org/rt/ecf/3.5Test/javadoc/org/eclipse/ecf/osgi/services/remoteserviceadmin/EndpointDescription.html javadoc] [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/osgi/bundles/org.eclipse.ecf.osgi.services.remoteserviceadmin/src/org/eclipse/ecf/osgi/services/remoteserviceadmin/EndpointDescription.java src].  Instances of the EndpointDescription class are used to '''advertise''' remote services upon remote service export, and then discovered by consumers...to use for the call to RemoteServiceAdmin.importService(EndpointDescription).

===EndpointListeners===

The RemoteServiceAdmin specification defines a service called the EndpointListener, that is notified of discovered and undiscovered endpoint descriptions.  Here are the methods called by the RSA discovery mechanism when an endpoint is discovered and undiscovered:

<pre>
public void endpointAdded( EndpointDescription endpoint, String matchedFilter )

and

public void endpointRemoved( EndpointDescription endpoint, String matchedFilter )
</pre>

To receive notifications of discovered/undiscovered endpoints, all one must do is to register as a local OSGi service an EndpointListener service...for example:

Properties props = new Properties();
// setup a scope for the desired endpoints
props.put("endpoint.listener.scope","(endpoint.id=*)");
// Register using whiteboard pattern
bundleContext.registerService(EndpointListener.class.getName(),new MyEndpointListener(),props);

where MyEndpointListener implements the EndpointListener interface.

This provides a useful mechanism for testing and debugging Remote Service Admin discovery.

ECF's implementation of the RemoteServiceAdmin discovery is provided by our abstract [[ECF/API_Docs#Discovery_API | discovery api]].  The separation of the discovery provider from the various protocol implementations of network discovery (e.g. Apache Zookeeper, Zeroconf, Service Locator Protocol, DNS-SD, proprietary discovery) allows the ECF RSA implementation to easily use whatever discovery provider meets the individual use case for network discovery (including no network discovery at all, or multiple discovery providers/protocols).  

As well, the decision about what discovery protocol to use can be different during development and deployment...allowing development and testing on one discovery provider (e.g. Zeroconf), with actual remote service deployment on some completely different discovery provider (e.g. Apache Zookeeper), without any differences in the actual service implementation.

===Host:  Advertising an EndpointDescription for Discovery===

ECF's remote service admin implementation defines a service:  IEndpointDescriptionAdvertiser [http://download.eclipse.org/rt/ecf/3.5Test/javadoc/org/eclipse/ecf/osgi/services/remoteserviceadmin/IEndpointDescriptionAdvertiser.html javadoc] [http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/osgi/bundles/org.eclipse.ecf.osgi.services.remoteserviceadmin/src/org/eclipse/ecf/osgi/services/remoteserviceadmin/IEndpointDescriptionAdvertiser.java src].  This service is used by the BasicTopologyManager (as described above) to advertise all successfully exported services.  Alternative/other topology managers can also use this service if they wish.

===Consumer:  Discovering an EndpointDescription===

When the '''org.eclipse.ecf.osgi.service.remoteserviceadmin''' bundle is started, the ECF RSA impl starts a '''locator''', that uses any/all ECF discovery/providers present to respond to discovered EndpointDescriptions.  So, for example, if an EndpointDescription has been advertised for a given remote services (as described above) via the Apache Zookeeper discovery protocol, if the Apache Zookeeper provider also exists on the consumer, and is configured correctly, it will discover the advertised EndpointDescription, and notify any EndpointListeners about the newly discovered EndpointDescription.

===File-Based Discovery - The Endpoint Description Extender Format (EDEF)===

In addition to dynamic network-based discovery of Endpoints, he OSGi RemoteServiceAdmin specification defines a standard serialized form for EndpointDescriptions, called the Endpoint Description Extender Format (EDEF).  This format allows '''file-based''' or static discovery of EndpointDescriptions.   This is referred to as static because rather than delivering the EndpointDescription dynamically across some network using a network discovery protocol (as described above), the remote service's EndpointDescription is written to an xml file and this file is subsequently read by a RemoteServiceAdmin discovery implementation, resulting in the 'discovery' of an EndpointDescription, and possibly the subsequent import of the remote services described by that EndpointDescription.  See section 122.8 of the enterprise specification for a complete description of this format.  This is an xml file-based format for discovering EndpointDescriptions.  

ECF's RSA implementation supports the EDEF format, allowing endpoints to be discovered by providing an xml file to the consumer.  See [[File-based_Discovery_with_the_Endpoint_Description_Extender_Format | Discovery with the Endpoint Description Extender Format]] for more information, and an example.