EIG:Remote Services Admin
Since ECF 3.3/Helios release in June 2010, ECF has provided a full implementation of the OSGi Remote Services specification. This specification is in the OSGi 4.2 compendium, chapter 13. You can download the compendium specification here.
As of our 3.5 release (March 2011), we now also support the Remote Services Admin specification. This is chapter 122 from the OSGi enterprise specification, and you can download this specification here.
- 1 What's Remote Services Admin?
- 2 ECF's RSA Implementation
- 3 Bug Reporting and Support
- 4 Architecture
What's Remote Services Admin?
Remote Services Admin (RSA) is the specification of a management agent for remote services. The Remote Services spec (chapter 13), 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 3.5 provides a complete/spec-compliant, small, easily customizable and extensible, cross-framework implementation.
ECF's RSA Implementation
The RSA implementation uses ECF's discovery API and 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
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
- Service Locator Protocol/SLP
- DNS-SD (DNS Service Discovery)
and the following distribution providers
- ECF Generic
- REST-based protocols
- SOAP-based protocols
- JMS-based protocols
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 here.
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. Equinox is currently our primary framework (for development and testing), and 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.
ECF has moved to git for source code control, and the ECF repo can be found 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
Bug Reporting and Support
For support in use of ECF's RSA implementation, see the 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] here.
From the RSA specification, here is a high-level diagram of the RSA Architecture
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).
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 src,extending the ECF AbstractTopologyManager javadoc,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:
public Collection<ExportRegistration> exportService(ServiceReference reference, Map<String, Object> properties) and public ImportRegistration importService(EndpointDescription endpoint)
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.
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 this implementation as an OSGi service using the whiteboard pattern...e.g.:
Where MyRemoteServiceAdminListener implements the standard org.osgi.service.remoteserviceadmin.RemoteServiceAdminListener interface.
For details on doing receiving events, see section 122.7 of the OSGi enterprise specification.
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.