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 [http://www.osgi.org/download/r4v42/r4.cmpn.pdf here].

+

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 [http://www.osgi.org/download/r4v42/r4.cmpn.pdf 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 [http://www.osgi.org/download/r4v42/r4.enterprise.pdf 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 [http://www.osgi.org/download/r4v42/r4.enterprise.pdf you can download this specification here].

==What's Remote Services Admin?==

==What's Remote Services Admin?==

Line 9:

Line 9:

==ECF's RSA 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. 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:

+

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

*Apache Zookeeper

Line 19:

Line 25:

and the following distribution providers

and the following distribution providers

−

*r-osgi (remote osgi)

+

*R-osgi

−

*ECF 'generic'

+

*ECF Generic

*REST-based protocols

*REST-based protocols

+

*SOAP-based protocols

*JMS-based protocols

*JMS-based protocols

*XMPP

*XMPP

Line 27:

Line 34:

*Others

*Others

−

Further, 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 API. This is possible because of ECF's transport-independent, open, community-tested APIs (discovery and remote services).

+

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:

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:

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

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:

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.

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.

Revision as of 18:13, 14 April 2011

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.

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

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

Source Code

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:

Architecture

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 BasicTopologyManagersrc,extending the ECF AbstractTopologyManagerjavadoc,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:

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

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 javadocsrc. 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:

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

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.