The OSGi Core Release 8 framework specifies a model where bundles can use distributed services. The basic model for OSGi remote services is that a bundle can register services that are exported to a communication Endpoint and use services that are imported from a communication Endpoint. However, chapter Remote Services does not explain what services are exported and/or imported; it leaves such decisions to the distribution provider. The distribution provider therefore performs multiple roles and cannot be leveraged by other bundles in scenarios that the distribution provider had not foreseen.
The primary role of the distribution provider is purely mechanical; it creates Endpoints and registers service proxies and enables their communication. The second role is about the policies around the desired topology. The third role is discovery. To establish a specific topology it is necessary to find out about exported services in other frameworks.
This specification therefore defines an API for the distribution provider and discovery of services in a network. A management agent can use this API to provide an actual distribution policy. This management agent, called the Topology Manager, can control the export and import of services delegating the intrinsic knowledge of the low level details of communication protocols, proxying of services, and discovering services in the network to services defined in this specification.
This specification is an extension of the Remote Service chapter. Though some aspects are repeated in this specification, a full understanding of the Remote Services chapter is required for full understanding of this document.
-
Simple - Make it as simple as possible for a Topology Manager to implement distribution policies.
-
Dynamic - Discover available Endpoints dynamically, for example through a discovery protocol like [3] Service Location Protocol (SLP) or [4] JGroups.
-
Inform - Provide a mechanism to inform other parties about created and removed Endpoints.
-
Configuration - Allow bundles to describe Endpoints as a bundle resource that are provided to the Distribution Provider.
-
Selective - Not all parties are interested in all services. Endpoint registries must be able to express the scope of services they are interested in.
-
Multiple - Allow the collaboration of multiple Topology Managers, Remote Service Admin services, and Discovery Providers.
-
Dynamic - Allow the dynamic discovery of Endpoints.
-
Federated - Enable a global view of all available services in a distributed environment.
-
Remote Service Admin - An implementation of this specification provides the mechanisms to import and export services through a set of configuration types. The Remote Service Admin service is a passive Distribution Provider, not taking any action to export or import itself.
-
Topology Manager - The Topology Manager provides the policy for importing and exporting services through the Remote Service Admin service.
-
Endpoint - An Endpoint is a communications access mechanism to a service in another framework, a (web) service, another process, or a queue or topic destination, etc., requiring some protocol for communications.
-
Endpoint Description - A properties based description of an Endpoint. Endpoint Descriptions can be exchanged between different frameworks to create connections to each other's services. Endpoint Descriptions can also be created to Endpoints not originating in an OSGi Framework.
-
Endpoint Description Provider - A party that can inform others about the existence of Endpoints.
-
Endpoint Event Listener – A listener service that receives events relating to Endpoints that match its scope. This Endpoint Event Listener is used symmetrically to implement a federated registry. The Topology Manager can use it to notify interested parties about created and removed Endpoints, as well as to receive notifications from other parties, potentially remote, about their available Endpoints.
-
Endpoint Listener – An older version of the Endpoint Event Listener defined by version
1.0
of this specification. The Endpoint Event Listener supersedes the Endpoint Listener, and should be used in preference where possible. -
Remote Service Admin Listener - A listener service that is informed of all the primitive actions that the Remote Service Admin performs like importing and exporting as well as errors.
-
Endpoint Configuration Extender - A bundle that can detect configuration data describing an Endpoint Description in a bundle resource, using the extender pattern.
-
Discovery – An Endpoint Event Listener that detects the Endpoint Descriptions through some discovery protocol.
-
Cluster - A group of computing systems that closely work together, usually in a fast network.
Topology Managers are responsible for the distribution policies of a OSGi framework. To implement a policy, a Topology Manager must be aware of the environment, for this reason, it can register:
-
Service listeners to detect services that can be exported according to the Remote Services chapter.
-
Listener and Find Hook services to detect bundles that have an interest in specific services that potentially could be imported.
-
A Remote Service Admin Listener service to detect the activity of other Topology Managers.
-
Endpoint Event Listener and Endpoint Listener services to detect Endpoints that are made available through discovery protocols, configuration data, or other means.
Using this information, the manager implements a topology using
the Remote Service Admin service. A Topology Manager that wants to
export a service can create an Export Registration
by providing one or more Remote Service Admin services a Service
Reference plus a Map with the required properties. A Remote Service
Admin service then creates a number of Endpoints based on the available
configuration types and returns a collection of
ExportRegistration
objects. A collection is returned
because a single service can be exported to multiple Endpoints depending
on the available configuration type properties.
Each Export Registration is specific for the caller and represents an existing or newly created Endpoint. The Export Registration associates the exported Service Reference with an Endpoint Description. If there are problems with the export operation, the Remote Service Admin service reports these on the Export Registration objects. That is, not all the returned Export Registrations have to be valid.
An Endpoint Description is a property based description of an Endpoint. Some of these properties are defined in this specification, other properties are defined by configuration types. These configuration types must follow the same rules as the configuration types defined in the Remote Services chapter. Remote Service Admin services that support the configuration types in the Endpoint Description can import a service from that Endpoint solely based on that Endpoint Description.
In similar vein, the Topology Manager can import a service from a
remote system by creating an Import Registration out of an Endpoint
Description. The Remote Service Admin service then registers a service
that is a proxy for the remote Endpoint and returns an
ImportRegistration
object. If there are problems with the
import, the Remote Service Admin service that cannot be detected early,
then the Remote Service Admin service reports these on the returned
ImportRegistration
object.
For introspection, the Remote Service Admin can list its current set of Import and Export References so that a Topology Manager can get the current state. The Remote Service Admin service also informs all Topology Managers and observers of the creation, deletion, and errors of Import and Export Registrations through the Remote Service Admin Listener service. Interested parties like the Topology Manager can register such a service and will be called back with the initial state as well as any subsequent changes.
An important aspect of the Topology Manager is the distributed nature of the scenarios it plays an orchestrating role in. A Topology Manager needs to be aware of Endpoints in the network, not just the ones provided by Remote Service Admin services in its local framework. The Endpoint Event Listener service is specified for this purpose. This service is provided for both directions, symmetrically. That is, it is used by the Topology Manager to inform any observers about the existence of Endpoints that are locally available, as well as for parties that represent a discovery mechanism. For example Endpoints available on other systems, Endpoint Descriptions embedded in resources in bundles, or Endpoint Descriptions that are available in some other form.
Endpoint Event Listener services are not always interested in the complete set of available Endpoints because this set can potentially be very large. For example, if a remote registry like [5] UDDI is used then the number of Endpoints can run into the thousands or more. An Endpoint Event Listener service can therefore scope the set of Endpoints with an OSGi LDAP style filter. Parties that can provide information about Endpoints must only notify Endpoint Event Listener services when the Endpoint Description falls within the scope of the Endpoint Listener service. Parties that use some discovery mechanism can use the scope to trigger directed searches across the network.
The 1.0
version of this specification defined an
Endpoint Listener service, which has an identical purpose and similar
behaviors to an Endpoint Event Listener service. Unfortunately the
design of the Endpoint Listener limited its extensibility, meaning
that it had to be replaced in version 1.1
of this
specification.
In order to maintain backward compatible interoperability with
Remote Service Admin 1.0
actors, Remote Service Admin
1.1
actors must continue to register Endpoint Listener
services as well as Endpoint Event Listener services. They must also
continue to call Endpoint Listener services as well as
EndpointEventListener services.
The OSGi Remote Services specification is about the distribution of services. This specification does not outline the details of how the distribution provider knows the desired topology, this policy aspect is left up to implementations. In many situations, this is a desirable architecture because it provides freedom of implementation to the distribution provider. However, such an architecture does not enable a separation of the mechanisms and policy. Therefore, this Remote Service Admin specification provides an architecture that enables a separate bundle from the distribution provider to define the topology. It splits the responsibility of the Remote Service specification in a number of roles. These roles can all have different implementations but they can collaborate through the services defined in this specification. These roles are:
-
Topology Managers - Topology Managers are the (anonymous) players that implement the policies for distributing services; they are closely aligned with the concept of an OSGi management agent. It is expected that Topology Managers will be developed for scenarios like import/export all applicable services, configuration based imports- and exports, and scenarios like fail-over, load-balancing, as well as standards like domain managers for the [6] Service Component Architecture (SCA).
-
Remote Service Admin - The Remote Service Admin service provides the basic mechanism to import and export services. This service is policy free; it will not distribute services without explicitly being told so. A OSGi framework can host multiple Remote Service Admin services that, for example, support different configuration types.
-
Discovery - To implement a distribution policy, a Topology Manager must be aware of what Endpoints are available. This specification provides an abstraction of a federated Endpoint registry. This registry can be used to both publish as well as consume Endpoints from many different sources. The federated registry is defined for local services but is intended to be used with standard and proprietary service discovery protocols. The federated registry is implemented with the Endpoint Event Listener service.
These roles are depicted in Figure 122.2 on page .
Distributed processing has become mainstream because of the massive scale required for Internet applications. Only with distributed architectures is it possible to scale systems to Internet size with hundreds of millions of users. To allow a system to scale, servers are grouped in clusters where they can work in unison or geographically dispersed in even larger configurations. The distribution of the work-load is crucial for the amount of scalability provided by an architecture and often has domain specific dispatching techniques. For example, the hash of a user id can be used to select the correct profile database server. In this fast moving world it is very unlikely that a single architecture or distribution policy would be sufficient to satisfy many users. It is therefore that this specification separates the how from the what. The complex mechanics of importing and exporting services are managed by a Remote Service Admin service (the how) while the different policies are implemented by Topology Managers (the what). This separation of concerns enables the development of Topology Managers that can run on many different systems, providing high user functionality. For example, a Topology Manager could implement a fail-over policy where some strategic services are redirected when their connections fail. Other Topology Managers could use a discovery protocol like SLP to find out about other systems in a cluster and automatically configure the cluster.
The key value of this architecture is demonstrated by the example of an SCA domain controller. An SCA domain controller receives a description of a domain (a set of systems and modules) and must ensure that the proper connections are made between the participating SCA modules. By splitting the roles, an SCA domain manager can be developed that can run on any compatible Remote Service Admin service implementation.
There is no restriction on the number of Topology Managers, nor is there a restriction on the number of Remote Service Admin service implementations. It is up to the deployer of the OSGi framework to select the appropriate set of these service implementations. It is the responsibility of the Topology Managers to listen to the Remote Service Admin Listener and track Endpoints created and deleted by other Topology Managers and act appropriately.
A cluster is a set of machines that are
connected in a network. The simplest policy for a Topology Manager is
to share exported services in such a cluster. Such a policy is very
easy to implement with the Remote Services Admin service. In the most
basic form, this Topology Manager would use some multicast protocol to
communicate with its peers. These peers would exchange
EndpointDescription
objects of exported services. Each
Topology Manager would then import any exported service.
This scenario can be improved by separating the promiscuous policy from the discovery. Instead of embedding the multicast protocol, a Topology manager could use the Endpoint Event Listener service. This service allows the discovery of remote services. At the same time, the Topology Manager could tell all other Endpoint Event Listener services about the services it has created, allowing them to be used by others in the network.
Splitting the Topology Manager and discovery in two bundles allows different implementations of the discovery bundle, for example, to use different protocols. See PROMISCUOUS_POLICY.
A more elaborate scheme is a fail-over policy. In such a policy a service can be replaced by a service from another machine. There are many ways to implement such a policy, an simple example strategy is provided here for illustration.
A Fail-Over Topology Manager is given a list of stateless services that require fail-over, for example through the Configuration Admin Service Specification. The Fail-Over Manager tracks the systems in the its cluster that provide such services. This tracking can use an embedded protocol or it can be based on the Endpoint Event Listener service model.
In the Fail-Over policy, the fail-over manager only imports a
single service and then tracks the error status of the imported
service through the Remote Service Admin Listener service. If it
detects the service is becoming unavailable, it closes the
corresponding Import Registration and imports a service from an
alternative system instead. In Figure 122.3, there are 4
systems in a cluster. The topology/fail-over manager ensures that
there is always one of the services in system A
,
B
, or C
available in D
.
There are many possible variations on this scenario. The managers could exchange load information, allowing the service switch to be influenced by the load of the target systems. The important aspect is that the Topology Manager can ignore the complex details of discovery protocols, communication protocols, and service proxying and instead focus on the topology. See FAIL_OVER_POLICY.
An Endpoint is a point of rendezvous of distribution providers. It is created by an exporting distribution provider or some other party, and is used by importing distribution providers to create a connection. An Endpoint Description describes an Endpoint in such a way that an importing Remote Service Admin service can create this connection if it recognizes the configuration type that is used for that Endpoint. The configuration type consists of a name and a set of properties associated with that name.
The core concept of the Endpoint Description is a Map of properties.
The structure of this map is the same as service properties, and the
defined properties are closely aligned with the properties of an imported
service. An EndpointDescription
object must only consist of
the data types that are supported for service properties. This makes the
property map serializable with many different mechanisms. The
EndpointDescription
class provides a convenient way to access
the properties in a type safe way.
An Endpoint Description has case insensitive keys, just like the Service Reference's properties.
The properties map must contain all the prescribed service
properties of the exported service after intents have been processed, as
if the service was registered as an imported service. That is, the map
must not contain any properties that start with
service.exported.*
but it must contain the
service.imported
.* variation of these properties. The
Endpoint Description must reflect the imported service properties because
this simplifies the use of filters from the service hooks. Filters applied
to the Endpoint Description can then be the same filters as applied by a
bundle to select an imported service from the service registry.
The properties that can be used in an Endpoint Description are
listed in Table 122.1. The
RemoteConstants
class contains the constants for all of these
property names.
Table 122.1 Endpoint Properties
Endpoint Property Name | Type | Description |
---|---|---|
service.exported.* |
Must not be set |
|
service.imported |
* |
Must always be set to some value. See SERVICE_IMPORTED. |
objectClass |
String[] |
Must be set to the value of
|
service.intents |
String+ |
Intents implemented by the exporting distribution provider and, if applicable, the exported service itself. Any qualified intents must have their expanded form present. These expanded intents are available with the getIntents() method. See SERVICE_INTENTS. |
endpoint.service.id |
Long |
The service id of the exported service. Can be absent or 0 if the corresponding Endpoint is not for an OSGi service. The remote service id is available as getServiceId(). See also ENDPOINT_SERVICE_ID. |
endpoint.framework.uuid |
String |
A universally unique id identifying the instance of the exporting framework. Can be absent if the corresponding Endpoint is not for an OSGi service. See Framework UUID. The remote framework UUID is available with the getFrameworkUUID() method. See also ENDPOINT_FRAMEWORK_UUID. |
endpoint.id |
String |
The Id for this Endpoint, can never be
|
|
String |
The Java package version for the embedded
<package>. For example, the property
The version does not have to be set, if not set, the value must be assumed to be 0. |
service.imported.configs |
String+ |
The configuration types that can be used to implement the corresponding Endpoint. This property maps to the corresponding property in the Remote Services chapter. This property can be obtained with the getConfigurationTypes() method. The Export Registration has all the possible configuration types, where the Import Registration reports the configuration type actually used. SERVICE_IMPORTED_CONFIGS. |
<config>.* |
* |
Where |
* |
* |
All remaining public service properties must be
present (that is, not starting with full stop ( |
The EndpointDescription
class has a number of
constructors that make it convenient to instantiate it for different
purposes:
-
EndpointDescription(Map) - Instantiate the Endpoint Description from a
Map
object. -
EndpointDescription(ServiceReference,Map) - Instantiate an Endpoint Description based on a Service Reference and a Map. The base properties of this Endpoint Description are the Service Reference properties but the properties in the given Map must override any of their case variants in the Service Reference. This allows the construction of an Endpoint Description from an exportable service while still allowing overrides of specific properties by the Topology Manager.
The Endpoint Description must use the allowed properties as given in
Table 122.1 on page . The Endpoint Description must
automatically skip any service.exported.*
properties.
The Endpoint Description provides the following methods to access the properties in a more convenient way:
-
getInterfaces() - Answers a list of Java interface names. These are the interfaces under which the services must be registered. These interface names can also be found at the
objectClass
property. A service can only be imported when there is at least one Java interface name available. -
getConfigurationTypes() - Answer the configuration types that are used for exporting this Endpoint. The configuration types are associated with a number of properties.
-
getId() - Returns an Id uniquely identifying an Endpoint. The syntax of this Id should be defined in the specification for the associated configuration type. Two Endpoint Descriptions with the same Id describe the same Endpoint.
-
getFrameworkUUID() - Get a Universally Unique Identifier (UUID) for the framework instance that has created the Endpoint, Framework UUID.
-
getServiceId() - Get the service id for the framework instance that has created the Endpoint. If there is no service on the remote side the value must be 0.
-
getPackageVersion(String) - Get the version for the given package.
-
getIntents() - Get the list of specified intents.
-
getProperties() - Get all the properties.
Two Endpoint Descriptions are deemed equal when their Endpoint Id is equal. The Endpoint Id is a mandatory property of an Endpoint Description, it is further described at Endpoint Id. The hash code is therefore also based on the Endpoint Id.
A valid Endpoint Description must at least satisfy the following assertions:
-
It must have a non-
null
Id that uniquely identifies the Endpoint -
It must at least have one Java interface name
-
It must at least have one configuration type set
-
Any version for the packages must have a valid version syntax.
An EndpointDescription
object is immutable and with
all final fields. It can be freely used between different
threads.
An Endpoint Id is an opaque unique identifier for an Endpoint. This uniqueness must at least hold for the entire network in which the Endpoint is used. There is no syntax defined for this string except that white space at the beginning and ending must be ignored. The actual syntax for this Endpoint Id must be defined by the actual configuration type.
Two Endpoint Descriptions are deemed identical when their Endpoint
Id is equal. The Endpoint Ids must be compared as string compares with
leading and trailing spaces removed. The Endpoint Description class must
use the String
class' hash Code from the Endpoint Id as its
own hashCode
.
The simplest way to ensure that a growth in the number of EndpointDescriptions and/or the size of the connected group does not violate the required uniqueness of Endpoint Ids is for implementations to make their Endpoint Ids globally unique. This protects against clashes regardless of changes to the connected group.
Whilst globally unique identifiers (GUIDs) are a simple solution to the Endpoint Id uniqueness problem, they are not easy to implement in all environments. In some systems they can be prohibitively expensive to create, or of insufficient entropy to be genuinely unique. Some distribution providers may therefore choose not to use random GUIDs.
In the case where no globally unique value is used the following actions are recommended (although not required).
-
Distribution Providers protect against intra-framework clashes using some known value unique to the service, for example the service id.
-
Distribution Providers protect against inter-provider collisions within a single framework by using some unique value, such as the distribution provider's bundle id. The distribution provider bundle's symbolic name is insufficient, as there may be multiple versions of the same distribution provider installed within a single framework.
-
Distribution Providers protect against inter-framework collisions using some value unique to the framework, such as the framework UUID.
Each framework registers its services with a service id that is only unique for that specific framework. The OSGi framework is not a singleton, making it possible that a single VM process holds multiple OSGi frameworks. Therefore, to identify an OSGi service uniquely it is necessary to identify the framework that has registered it. This identifier is a Universally Unique IDentifier (UUID) that is set for each framework. This UUID is contained in the following framework property:
org.osgi.framework.uuid
If an Endpoint Description has no associated OSGi service then the UUID of that Endpoint Description must not be set and its service id must be 0.
A local Endpoint Description will have its framework UUID set to the local framework. This makes it straightforward to filter for Endpoint Descriptions that are describing local Endpoints or that describe remote Endpoints. For example, a manager can take the filter from a listener and ensure that it is only getting remote Endpoint Descriptions:
(&
(!
(service.remote.framework.uuid
=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)
)
(objectClass=org.osgi.service.log.LogService)
)
Where 72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72
is the
UUID of the local framework. A discovery bundle can register the
following filter in its scope to receive all locally generated
Endpoints:
(service.remote.framework.uuid
=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)
Configuration types can use URLs to point to local resources describing in detail the Endpoint parameters for specific protocols. However, the purpose of an Endpoint Description is to describe an Endpoint to a remote system. This implies that there is some marshaling process that will transfer the Endpoint Description to another process. This other process is unlikely to be able to access resource URLs. Local bundle resource URLs are only usable in the framework that originates them but even HTTP based URLs can easily run into problems due to firewalls or lack of routing.
Therefore, the properties for a configuration type should be stored in such a way that the receiving process can access them. One way to achieve this is to contain the configuration properties completely in the Endpoint Description and ensure they only use the basic data types that the remote services chapter in the core requires every Distribution Provider to support.
The Endpoint Description XML format provides an xml
element that is specifically added to make it easy to embed XML based
configuration documents. The XML Schema is defined in Endpoint Description Extender Format.
The Remote Service Admin service abstracts the core functionality of a distribution provider: exporting a service to an Endpoint and importing services from an Endpoint. However, in contrast with the distribution provider of the Remote Services specification, the Remote Service Admin service must be told explicitly what services to import and export.
An exportable service can be exported with the exportService(ServiceReference,Map) method. This method creates a number of
Endpoints by inspecting the merged properties from the Service Reference
and the given Map. Any property in the Map overrides the Service
Reference properties, regardless of case. That is, if the map contains a
key then it will override any case variant of this key in the Service
Reference. However, if the Map contains the objectClass
or
service.id
property key in any case variant, then these
properties must not override the Service Reference's value.
The Remote Service Admin service must interpret the merged properties according to the Remote Services chapter. This means that it must look at the following properties (as defined in chapter Remote Services ):
-
service.exported.configs
-(String+ )
A list of configuration types that should be used to export this service. Each configuration type represents the configuration parameters for an Endpoint. A Remote Service Admin service should create an Endpoint for each configuration type that it supports and ignore the types it does not recognize. If this property is not set, then the Remote Service Admin implementation must choose a convenient configuration type that then must be reported on the Endpoint Description with theservice.imported.configs
associated with the returned Export Registration. -
service.exported.intents
- (String+)
A list of intents that the Remote Service Admin service must implement to distribute the given service. -
service.exported.intents.extra
-(String+)
This property is merged with theservice.exported.intents
property. -
service.exported.interfaces
-(String+)
This property must be set; it marks this service for export and defines the interfaces. The list members must all be contained in the types listed in theobjectClass
service property from the Service Reference. The single value of an asterisk ('*' \u002A
) indicates all interfaces in the registration'sobjectClass
property and ignore the classes. Being able to set this property outside the Service Reference implies that the Topology Manager can export any registered service, also services not specifically marked to be exported. -
service.intents
-(String+)
A list of intents that this service has implemented.
A Topology Manager cannot remove properties, null
is
invalid as a property value.
The Remote Service Admin returns a collection of
ExportRegistration
objects. This collection must contain an
entry for each configuration type the Remote Service Admin has
recognized. Unrecognized configuration types must be ignored. Recognized
configuration types which require intents that are not supported by the
Remote Service Admin must also be ignored. However, it is possible that
this list contains invalid registrations, see Invalid Registrations.
If a Service was already exported then the Remote Service Admin
must still return a new ExportRegistration
object that is
linked with the earlier registrations. That is, an Endpoint can be
shared between multiple Export Registrations. The Remote Service Admin
service must ensure that the corresponding Endpoint remains available as
long as there is at least one open Export Registration for that
Endpoint.
For each successful creation of an export registration, the Remote Service Admin service must publish an EXPORT_REGISTRATION event, see Events. This event must be emitted, even if the Endpoint already existed and is thus shared with another Export Registration. If the creation of an Endpoint runs into an error, an EXPORT_ERROR event must be emitted.
Each valid Export Registration corresponds to an Endpoint for the given service. This Endpoint must remain active until all of the Export Registrations are closed that share this Endpoint.
The Endpoint can now be published so that other processes or systems can import this Endpoint. To aid with this import, the Export Registration has a getExportReference() method that returns an ExportReference object. This reference provides the following information:
-
getExportedEndpoint() - This is the associated Endpoint Description. This Endpoint Description is a properties based description of an Endpoint. The property keys and their semantics are outlined in Endpoint Description. It can be used to inform other systems of the availability of an Endpoint.
-
getExportedService() - The Service Reference to the exported service.
Both methods must return null
when the associated
Export Registration is closed.
A Distribution Provider that recognizes the configuration type in an Endpoint can create a connection to an Endpoint on other systems as long as firewalls and networks permit. The Endpoint Description can therefore be communicated to other systems to announce the availability of an Endpoint. The Topology Manager can optionally announce the availability of an Endpoint to the Endpoint Event Listener services, see Discovery. The decision to announce the availability of an Endpoint is one of the policies that is provided by a specific Topology Manager.
The Export Registrations remain open until:
-
Explicitly closed by the Topology Manager, or
-
The Remote Service Admin service is no longer used by the Topology Manager that created the Export Registration.
If the Remote Service Admin service can no longer maintain the corresponding Endpoint due to failures than these should be reported through the events. However, the registrations should remain open until explicitly closed by the Topology Manager.
See Registration Life Cycle for more information.
The Export Registrations are not permanent; persistence is in the realm of the Topology Manager.
To import a service, a Topology Manager must have an Endpoint Description that describes the Endpoint the imported service should connect to. With this Endpoint Description, a Remote Service Admin service can then import the corresponding Endpoint. A Topology Manager can obtain these Endpoint Descriptions through internal configuration; it can use the discovery model enabled by the Endpoint Event Listener service, see Discovery, or some alternate means.
A service can be imported with the Remote Service Admin importService(EndpointDescription) method. This method takes an Endpoint Description and picks one of the embedded configuration types to establish a connection with the corresponding Endpoint to create a local service proxy. This proxy can then be mapped to either a remote OSGi service or an alternative, for example a web service. In certain cases the service proxy can be lazy, only verifying the reachability of the Endpoint when it is actually invoked for the first time. This implies that a service proxy can block when invoked until the proper communication setup has taken place.
If the Remote Service Admin service does not recognize any of the
configuration types then it must return null
. If there are
multiple configuration types recognized then the Remote Service Admin is
free to select any one of the recognized types.
The Remote Service Admin service must ensure that service properties are according to the Remote Services chapter for an imported service. This means that it must register the following properties:
-
service.imported
-(*)
Must be set to any value. -
service.imported.configs
-(String+)
The configuration information used to import this service. Any associated properties for this configuration types must be properly mapped to the importing system. For example, a URL in these properties must point to a valid resource when used in the importing framework, see Resource Containment. Multiple configuration types can be listed if they are synonyms for exactly the same Endpoint that is used to export this service. -
service.intents
-(String+)
The Remote Service Admin must set this property to convey the combined intents of:-
The exporting service, and
-
The intents that the exporting distribution provider adds, and
-
The intents that the importing distribution provider adds.
-
-
Any additional properties listed in the Endpoint Description that should not be excluded. See Endpoint Description for more details about the properties in the Endpoint Description.
A Remote Service Admin service must strictly follow the rules for importing a service as outlined in the Remote Services chapter.
The Remote Service Admin must return an
ImportRegistration
object or null
. Even if an
Import Registration is returned, it can still be an invalid
registration, see Invalid Registrations if the setup of
the connection failed asynchronously. The Import Registration must
always be a new object. Each valid Import Registration corresponds to a
proxy service, potentially shared, that was created for the given
Endpoint. The issues around proxying are described in Proxying.
For each successful creation of an import registration, the Remote Service Admin service must publish an IMPORT_REGISTRATION event, if there is an error it must publish an IMPORT_ERROR, see Events.
For more information see Registration Life Cycle.
The Import Registration provides access to an ImportReference object with the getImportReference(). This object has the following methods:
-
getImportedEndpoint() - Provides the Endpoint Description for this imported service.
-
getImportedService() - Provides the Service Reference for the service proxy.
The Import Registration will remain open as long as:
-
The corresponding remote Endpoint remains available, and
-
The Remote Service Admin service is still in use by the Topology Manager that created the Import Registration.
That is, the Import Registrations are not permanent, any persistence is in the realm of the Topology Manager. See Registration Life Cycle for more details.
Services Registrations are dynamic and service properties may change during the lifetime of a service. Remote services must mirror these dynamics without making it appear as though the service has become unavailable. This requires that the exporting distribution provider and the importing distribution provider support the changing of service properties.
There are two types of service properties:
-
Properties that are intended to be consumed by the distribution provider, such as: the exported interfaces and configuration types, exported intents and configuration type specific properties. These properties are typically prefixed with
'service.'
or'endpoint.'
see Table 122.1 on page . -
Service properties not intended for the distribution provider. These are typically used to communicate information to the consumer of the service and are often specific to the domain of the service.
The following methods to support the updating of service properties on Export Registrations and the propagation of these updates to the remote proxies via Import Registrations.
-
ExportRegistration.update(Map) - Allows the Topology Manager to update an existing export registration it created after receiving a notification of changed properties on the remoted service.
-
ImportRegistration.update(EndpointDescription) - Allows the Topology Manager to update the import registration representing a remote service after the remote service properties have been updated. Typically the topology manager is notified of such change via the Discovery mechanism.
The distribution provider must support the updates of service properties not intended for the distribution provider, where supported property values are as defined in the Filter Syntax of OSGi Core Release 8. Distribution providers may support updates to a wider set of properties or data types, but these may fail with other implementations.
The Remote Service Admin service provides the following methods to get the list of the current exported and imported services:
-
getExportedServices() - List the Export References for services that are exported by this Remote Service Admin service as directed by any of the Topology Managers.
-
getImportedEndpoints() - List the Import References for services that have been imported by this Remote Service Admin service as directed by any of the Topology Managers.
All registrations obtained through a Remote Service Admin service are life cycle bound to the Topology Manager that created it. That is, if a Topology Manager ungets its Remote Service Admin service, all registrations obtained through this service must automatically be closed. This model ensures that all registrations are properly closed if either the Remote Service Admin or the Topology Manager stops because in both cases the framework performs the unget automatically. Such behavior can be achieved by implementing the Remote Service Admin service as a Service Factory.
The Remote Service Admin service is explicitly allowed to return invalid Import and Export Registrations. First, in a communications stack it can take time to discover that there are issues, allowing the registration to return before it has completed can potentially save time. Second, it allows the Topology Manager to discover problems with the configuration information. Without the invalid Export Registrations, the Topology Manager would have to scan the log or associate the Remote Service Admin Events with a specific import/export method call, something that can be difficult to do.
If the registration is invalid, the getException() method must return a Throwable
object. If the registration has initialized correctly, this method will
return null
. The getExportReference() and getImportReference() methods must throw an Illegal State Exception
when the registration is invalid. A Remote Service Admin service is
allowed to block for a reasonable amount of time when any of these
methods is called, including the getException
method, to
finish initialization.
An invalid registration can be considered as never having been opened, it is therefore not necessary to close it; however, closing an invalid or closed registration must be a dummy operation and never throw an Exception. However, a failed registration must generate a corresponding error event.
It is the responsibility of the Remote Service Admin service to properly proxy an imported service. This specification does not mandate the technique used to proxy an Endpoint as a service in the OSGi framework. The OSGi Remote Services specification allows a distribution provider to limit what it can proxy.
One of the primary aspects of a proxy is to ensure class space consistency between the exporting bundle and importing bundles. This can require the generation of a proxy-per-bundle to match the proper class spaces. It is the responsibility of the Remote Service Admin to ensure that no Class Cast Exceptions occur.
A common technique to achieve maximum class space compatibility is to use a Service Factory. A Service Factory provides the calling bundle when it first gets the service, making it straightforward to verify the package version of the interface that the calling bundle uses. Knowing the bundle that requests the service allows the creation of specialized proxies for each bundle. The interface class(es) for the proxy can then be loaded directly from the bundle, ensuring class compatibility. Interfaces should be loadable by the bundle otherwise that bundle can not use the interface in its code. If an interface cannot be loaded then it can be skipped. A dedicated class loader can then be created that has visibility to all these interfaces and is used to define the proxy class. This design ensures proper visibility and consistency. Implementations can optimize this model by sharing compatible class loaders between bundles.
The proxy will have to call arbitrary methods on arbitrary services. This has a large number of security implications, see Security.
The topology of the distributed system is decided by the Topology Manager. However, in a distributed environment, the Topology Manager needs to discover Endpoints in other frameworks. There is a very large number of ways how a Topology Manager could learn about other Endpoints, ranging from static configuration, a centralized administration, all the way to fully dynamic discovery protocols like the Service Location Protocol (SLP) or JGroups. To support the required flexibility, this specification defines an Endpoint Event Listener service that allows the dissemination of Endpoint information. This service provides a symmetric solution because the problem is symmetric: it is used by a Topology Manager to announce changes in its local topology as well as find out about other Endpoint Descriptions. Where those other Endpoint Descriptions come from can vary widely. This design is depicted in Figure 122.4 on page .
The design of the Endpoint Event Listener allows a federated registry of Endpoint Descriptions. Any party that is interested in Endpoint Descriptions should register an Endpoint Event Listener service. This will signal that it is interested in topology information to any Endpoint Description Providers. Each Endpoint Event Listener service must be registered with a service property that holds a set of filter strings to indicate the scope of its interest. These filters must match an Endpoint Description before the corresponding Endpoint Event Listener service is notified of the availability of an Endpoint Description. Scoping is intended to limit the delivery of unnecessary Endpoint Descriptions as well as signal the need for specific Endpoints.
In addition to providing an Endpoint Event Listener actors must
provide an Endpoint Listener. This may, or may not, be the same service
object as the Endpoint Event Listener. Registering an Endpoint Listener in
addition to an Endpoint Event Listener ensures that Endpoint announcements
from version 1.0
actors will continue to be visible. If a
service object is advertised as both an Endpoint Listener
and an Endpoint Event Listener then version
1.1
actors must use the Endpoint Event Listener interface of
the service in preference, and not call it as an Endpoint Listener. For
this reason the Endpoint Listener interface is marked as
Deprecated
. The reason that the Endpoint Event Listener
interface should be preferred is that it supports more advanced
notification types, such as modification events.
A Topology Manager has knowledge of its local Endpoints and is likely to be only interested in remote Endpoints. It can therefore set the scope to only match remote Endpoint Descriptions. See Framework UUID for how to limit the scope to local or remote Endpoints. At the same time, a Topology manager should inform any locally registered Endpoint Event Listener and Endpoint Listener services about Endpoints that it has created or deleted.
This architecture allows many different use cases. For example, a bundle could display a map of the topology by registering an Endpoint Event Listener with a scope for local Endpoints. Another example is the use of SLP to announce local Endpoints to a network and to discover remote Endpoints from other parties on this network.
An instance of this design is shown in Figure 122.5 on page . In this figure, there are 3
frameworks that collaborate through some discovery bundle. The
Top
framework has created an Endpoint and decides to notify
all Endpoint Event Listeners and Endpoint Listeners registered in this
framework that are scoped to this new Endpoint. Local bundle
D
has set its scope to all Endpoint Descriptions that
originate from its local framework, it therefore receives the Endpoint
Description from T
. Bundle D
then sends the
Endpoint Description to all its peers on the network.
In the Quark
framework, the manager bundle
T
has expressed an interest by setting its scope to a filter
that matches the Endpoint Description from the Top
framework.
When the bundle D
on the Quark
framework
receives the Endpoint Description from bundle D
on the
Top
framework, it matches it against all local Endpoint Event
Listener's scope. In this case, the local manager bundle T
matches and is given the Endpoint Description. The manager then uses the
Remote Service Admin service to import the exported service described by
the given Endpoint Description.
The previous description is just one of the possible usages of the Endpoint Event Listener. For example, the discovery bundles could communicate the scopes to their peers. These peers could then register an Endpoint Event Listener per peer, minimizing the network traffic because Endpoint Descriptions do not have to be broadcast to all peers.
Another alternative usage is described in Endpoint Description Extender Format. In this chapter the extender pattern is used to retrieve Endpoint Descriptions from resources in locally active bundles.
An Endpoint Event Listener or Endpoint Listener service is
registered with the ENDPOINT_LISTENER_SCOPE service property. This property, which is
String+
, must be set and must contain at least one filter.
If there is not at least one filter, then that Endpoint Event Listener
or Endpoint Listener must not receive any Endpoint Descriptions.
Each filter in the scope is applied against the properties of the Endpoint Description until one succeeds. Only if one succeeds is the Endpoint informed about the existence of an Endpoint.
The Endpoint Description is designed to reflect the properties of the imported service, there is therefore a correspondence with the filters that are used by bundles that are listening for service registrations. The purpose of this design is to match the filter available through Listener Hook services, see On Demand.
However, the purpose of the filters is more generic than just this
use case. It can also be used to specify the interest in local Endpoints
or remote Endpoints. For example, Topology Managers are only interested
in remote Endpoints while discoverers are only interested in local
Endpoints. It is easy to discriminate between local and remote by
filtering on the endpoint.framework.uuid
property. Endpoint
Descriptions contain the Universally Unique ID (UUID) of the originating
framework. This UUID must be available from the local framework as well.
See Framework UUID.
The EndpointEventListener
interface has the following
method:
-
endpointChanged(EndpointEvent,String) – Notify the Endpoint Event Listener of changes to an Endpoint. The change could entail the addition or removal of an Endpoint or the modification of the properties of an existing Endpoint. Multiple identical events should be counted as a single such event.
These methods must only be called if the Endpoint Event Listener service has a filter in its scope that matches the Endpoint Description properties.
The Endpoint Event Listener interface is idempotent. Endpoint Description Providers must inform an Endpoint Event Listener service (and its deprecated predecessor Endpoint Listener service) that is registered of all their matching Endpoints. The only way to find out about all available Endpoints is to register an Endpoint Event Listener (or Endpoint Listener) that is then informed by all available Endpoint Description Providers of their known Endpoint Descriptions that match their scope.
The EndpointListener
interface is marked as
Deprecated
because the EndpointEventListener
interface must be used in preference when both are implemented by the
same object. The EndpointEvent
interface has the following
methods:
-
endpointAdded(EndpointDescription,String) – Notify the Endpoint Listener of a new Endpoint Description. The second parameter is the filter that matched the Endpoint Description. Registering the same Endpoint multiple times counts as a single registration.
-
endpointRemoved(EndpointDescription,String) – Notify the Endpoint Listener that the provided Endpoint Description is no longer available.
These methods must only be called if the Endpoint Listener service has a filter in its scope that matches the Endpoint Description properties. The reason for the filter string in the methods is to simplify and speed up matching an Endpoint Description to the cause of interest. For example, if the Listener Hook is used to do on demand import of services, then the filter can be associated with the Listener Info of the hook, see On Demand. If multiple filters in the scope match the Endpoint Description than the first filter in the scope must be passed.
The Endpoint Listener interface is idempotent. Endpoint Description Providers must inform an Endpoint Listener service that is registered of all their matching Endpoints.
An Endpoint Event Listener service tracks the known Endpoints in its given scope. There are potentially a large number of bundles involved in creating this federated registry of Endpoints. To ensure that no Endpoint Descriptions are orphaned or unnecessarily missed, an Endpoint Event Listener implementation must follow the following rules:
-
Registration – The Endpoint Event Listener service is called with an event of type ADDED for all known Endpoint Descriptions that the bundles in the local framework are aware of. Similarly, Endpoint Listener services are called with an endpointAdded(EndpointDescription,String) method for all these.
-
Tracking providers – An Endpoint Event Listener or Endpoint Listener must track the bundles that provide it with Endpoint Descriptions. If a bundle that provided Endpoint Descriptions is stopped, all Endpoint Descriptions that were provided by that bundle must be removed. This can be implemented straightforwardly with a Service Factory.
-
Scope modification – An Endpoint Event Listener or Endpoint Listener is allowed to modify the set of filters in its scope through a service property modification. This modification must result in new and/or existing Endpoint Descriptions to be added, however, existing Endpoints that are no longer in scope are not required to be explicitly removed by the their sources. It is the responsibility for the Endpoint Listener to remove these orphaned Endpoint Description from its view.
-
Endpoint mutability – An Endpoint Description can change its Properties. The way this is handled is different for Endpoint Event Listeners and Endpoint Listeners. An Endpoint Event Listener receives a change event of type MODIFIED when the Properties of an existing Endpoint are modified. If the modification means that the Endpoint no longer matches the listener scope an event of type MODIFIED_ENDMATCH is sent instead. Endpoint Listener services receive a sequence of endpointRemoved(EndpointDescription,String) and endpointAdded(EndpointDescription,String) callbacks when the Properties of an Endpoint are modified.
Endpoint Descriptions can be added from different sources and
providers of Endpoint Descriptions often use asynchronous and
potentially unreliable communications. An implementation must therefore
handle the addition of multiple equal Endpoint Descriptions from
different sources as well as from the same source. Implementations must
not count the number of registrations, a remove operation of an Endpoint
Description is final for each source. That is, if source A
added Endpoint Description e
, then it can only be removed
by source A
. However, if source A
added
e
multiple times, then it only needs to be removed once.
Removals of Endpoint Descriptions that have not been added (or were
removed before) should be ignored.
The discovery of Endpoints is a fundamentally indeterministic process and implementations of Endpoint Event Listener services should realize that there are no guarantees that an added Endpoint Description is always describing a valid Endpoint.
The Endpoint Event Listener and Endpoint Listener services are based on an asynchronous, unreliable, best effort model because there are few guarantees in a distributed world. It is the task of an Endpoint Description Provider, for example a discovery bundle, to keep the Endpoint Event Listener services up to date of any Endpoint Descriptions the provider is aware of and that match the tracked service's scope.
If an Endpoint Event Listener or Endpoint Listener service is registered, a provider must add all matching Endpoint Descriptions that it is aware of and match the tracked listener's scope. This can be done during registration or asynchronously later. For example, it is possible to use the filters in the scope to request remote systems for any Endpoint Descriptions that match those filters. For expediency reasons, the service registration event should not be delayed until those results return; it is therefore applicable to add these Endpoint Descriptions later when the returns from the remote systems finally arrive.
If a tracked listener service object is advertised as both an
Endpoint Event Listener and an Endpoint Listener then the
EndpointDescription Provider must ignore the
EndpointListener
interface, and treat the listener only as
an Endpoint Event Listener. Remote Service Admin 1.0
actors
will be unaware of the EndpointEventListener
interface, and
will treat the service object purely as an Endpoint Listener. This
restriction ensures that all actors will treat the service either as an
Endpoint Event Listener, or an Endpoint Listener, but never as both. As
a result the listener service will not have to disambiguate duplicate
events from a single source. If an Endpoint Description Provider uses
both the Endpoint Listener and Endpoint Event Listener interfaces of a
single service object then the resulting behavior is undefined. The
implementation may detect the misuse and throw an Exception, process or
ignore the events from one of the interfaces, or it may simply corrupt
the internal registry of Endpoints within the listener.
A tracked Endpoint Event Listener or Endpoint Listener is allowed to modify its scope by setting new properties on its Service Registration. An Endpoint Description provider must process the new scope and add any newly matching Endpoint Descriptions. It is not necessary to remove any Endpoint Descriptions that were added before but no longer match the new scope. Removing those orphaned descriptions is the responsibility of the listener implementation.
It is not necessary to remove any registered Endpoint Descriptions when the Endpoint Event Listener or Endpoint Listener is unregistered; also here it is the responsibility of the listener to do the proper cleanup.
A common distribution policy is to import services that are being listened for by local bundles. For example, when a bundle opens a Service Tracker on the Log Service, a Topology Manager could be notified and attempt to find a Log Service in the local cluster and then import this service in the local Service Registry.
The OSGi framework provides service hooks for exactly this purpose. A Topology Manager can register a Listener Hook service and receive the information about bundles that have specified an interests in specific services.
For example, a bundle creates the following Service Tracker:
ServiceTracker st = new ServiceTracker(context,
LogService.class.getName() );
st.open();
This Service Tracker will register a Service Listener with the
OSGi framework. This will cause the framework to add a
ListenerInfo
to any Listener Hook services. The
getFilter
method on a ListenerInfo
object
provides a filter that is directly applicable for the Endpoint Event
Listener's scope. In the previous example, this would be the
filter:
(objectClass=org.osgi.service.log.LogService)
A Topology Manager could verify if this listener is satisfied. That is, if it has at least one service. If no such service could be found, it could then add this filter to its Endpoint Event Listener's scope to detect remote implementations of this service. If such an Endpoint is detected, it could then request the import of this service through the Remote Service Admin service.
The Remote Service Admin service must synchronously inform any Remote Service Admin Listener services of events as they happen. Client of the events should return quickly and not perform any but trivial processing in the same thread.
The following event types are defined:
-
EXPORT_ERROR - An exported service has run into an unrecoverable error, although the Export Registration has not been closed yet. The event carries the Export Registration as well as the Exception that caused the problem, if present.
-
EXPORT_REGISTRATION - The Remote Service Admin has registered a new Export Registration.
-
EXPORT_UNREGISTRATION - An Export Registration has been closed, the service is no longer exported and the Endpoint is no longer active when this was the last registration for that service/Endpoint combination.
-
EXPORT_UPDATE - An exported service is updated. The service properties have changed.
-
EXPORT_WARNING - An exported service is experiencing problems but the Endpoint is still available.
-
IMPORT_ERROR - An imported service has run into a fatal error and has been shut down. The Import Registration should be closed by the Topology Manager that created them.
-
IMPORT_REGISTRATION - A new Import Registration was created for a potentially existing service/Endpoint combination.
-
IMPORT_UNREGISTRATION - An Import Registration was closed, removing the proxy if this was the last registration.
-
IMPORT_UPDATE - An imported service is updated. The service properties have changed.
-
IMPORT_WARNING - An imported service is experiencing problems but can continue to function.
The following properties are available on the event:
-
getType() - The type of the event.
-
getException() - Any exception, if present.
-
getExportReference() - An export reference, if applicable.
-
getImportReference() - An import reference, if applicable.
-
getSource() - The source of the event, the Remote Service Admin service.
All Remote Service Admin events must be posted, which is asynchronously, to the Event Admin service, if present, under the following topic:
org/osgi/service/remoteserviceadmin/<type>
Where <type>
represents the type of the event,
for example IMPORT_ERROR
.
The Event Admin event must have the following properties:
-
bundle
-(Bundle)
The Remote Service Admin bundle -
bundle.id
- (Long
) The id of the Remote Service Admin bundle. -
bundle.symbolicname
- (String
) The Bundle Symbolic Name of the Remote Service Adminbundle.version
- (Version
) The version of the Remote Service Admin bundle. -
bundle.signer
- (String[]
) Signer of the Remote Service Admin bundle -
exception
- (Throwable) The Exception, if present. Also reported on thecause
property for backward compatibility. -
exception.class
- (String
) The fully-qualified class name of the attached Exception. -
exception.message
-(String)
The message of the attached exception. Only set if the Exception message is notnull
. -
endpoint.service.id
- (Long
) Remote service id, if present -
endpoint.framework.uuid
- (String
) Remote service's Framework UUID, if present -
endpoint.id
- (String
) The id of the Endpoint, if present -
objectClass
-(String[])
The interface names, if present -
service.imported.configs
- (String+
) The configuration types of the imported services, if present -
timestamp
- (Long
) The time when the event occurred -
event
- (RemoteServiceAdminEvent
) TheRemoteServiceAdminEvent
object that caused this event.
The Endpoint Description Extender format is a possibility to deliver
Endpoint Descriptions in bundles. This section defines an XML schema and
how to locate XML definition resources that use this schema to define
Endpoint Descriptions. The definition resource is a simple property based
model that can define the same information as the properties on an
imported service. If a bundle with the description is
ready (ACTIVE
or lazy activation and in
the STARTING
state), then this static description can be
disseminated through the Endpoint Event Listeners that have specified an
interest in this description. If the bundle is stopped, the corresponding
Endpoints must be removed.
XML documents containing remote service descriptions must be specified by the Remote-Service header in the manifest. The structure of the Remote Service header is:
Remote-Service ::= header // See Common Header Syntax in Core
The value of the header is a comma separated list of paths. A path is:
-
A directory if it ends with a solidus (
'/' \u002F
). A directory is scanned for*.xml
files. -
A path with wildcards. Such a path can use the wildcards in its last component, as defined in the
findEntries
method. -
A complete path, not having wildcards not ending in a solidus (
'/' \u002F
).
The Remote-Service header has no architected directives or attributes, unrecognized attributes and directives must be ignored.
A Remote-Service manifest header specified in a fragment must be
ignored. However, XML documents referenced by a bundle's Remote-Service
manifest header can be contained in attached fragments. The required
behavior for this is implemented in the findEntries
method.
The extender must process each XML document specified in this header. If an XML document specified by the header cannot be located in the bundle and its attached fragments, the extender must log an error message with the Log Service, if present, and continue.
For example:
Remote-Service: lib/, remote/osgi/*.dsc, cnf/google.xml
This matches all resources in the lib directory matching
*.xml
, all resources in the /remote/osgi
directory that end with .dsc
, as well as the
google.xml
resource in the cnf
directory.
The namespace of these XML resources must be:
http://www.osgi.org/xmlns/rsa/v1.0.0
This namespace describes a set of Endpoint Descriptions, where each Endpoint Description can provide a set of properties. The structure of this schema is:
endpoint-descriptions ::= <endpoint-description>*
endpoint-description ::= <property>*
property ::= ( <array> | <list> | <set>| <xml> )?
array ::= <value> *
list ::= <value> *
set ::= <value> *
xml ::= <*> *
This structure is depicted in Figure 122.6 on page .
The property
element has the attributes listed in table
Table 122.2.
Table 122.2 Property Attributes
Attribute | Type | Description |
---|---|---|
name |
String |
The required name of the property. The type maps to
the XML Schema |
value-type |
|
The optional type name of the property, the default
is |
value |
String |
The value. Must be converted to the specified type if
this is not the |
A property can have an array
, list
,
set
, or xml
child element. If a child element is
present then it is an error if the value
attribute is
defined. It is also an error of there is no child element and no
value
attribute.
The array
, list
, or set
are
multi-valued. That is, they contain 0 or more
value
elements. A value element contains text (a string) that
must be converted to the given value-type or if not specified, left as is.
Conversion must trim the leading and trailing white
space characters as defined in the Character.isWhitespace
method. No trimming must be done for strings. An array of primitive
integers like int[] {1,42,97}
can be encoded as
follows:
<property name="integers" value-type="int">
<array>
<value> 1</value>
<value>42</value>
<value>97</value>
</array>
</property>
The xml
element is used to convey XML from other
namespaces, it is allowed to contain one foreign XML root element, with
any number of children, that will act as the root element of an XML
document. This root element will be included in the corresponding property
as a string. The XML element must be a valid XML document but not contain
the XML processing instructions, the part between the <?
and ?>
. The value-type
of the property must
be String
or not set when an xml
element is
used, using another type is invalid.
The xml
element can be used to embed configuration
information, making the Endpoint Description self contained.
The following is an example of an endpoint-descriptions
resource.
<?xml version="1.0" encoding="UTF-8"?>
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
<endpoint-description>
<property name="service.intents">
<list>
<value>SOAP</value>
<value>HTTP</value>
</list>
</property>
<property name="endpoint.id" value="http://ws.acme.com:9000/hello"/>
<property name="endpoint.package.version.com.acme" value="4.2"/>
<property name="objectClass">
<array>
<value>com.acme.Foo</value>
</array>
</property>
<property name="service.imported.configs" value="com.acme"/>
<property name="com.acme.ws.xml">
<xml>
<config xmlns="http://acme.com/defs">
<port>1029</port>
<host>www.acme.com</host>
</config>
</xml>
</property>
</endpoint-description>
</endpoint-descriptions>
Besides being in a separate resource, the static configuration as
described here could also be part of a larger XML file. In that case the
parser must ignore elements not part of the
http://www.osgi.org/xmlns/rsa/v1.0.0
namespace schema.
This namespace of the schema is:
http://www.osgi.org/xmlns/rsa/v1.0.0
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:rsa="http://www.osgi.org/xmlns/rsa/v1.0.0"
targetNamespace="http://www.osgi.org/xmlns/rsa/v1.0.0"
elementFormDefault="qualified" version="1.0.1">
<annotation>
<documentation xml:lang="en">
This is the XML Schema for endpoint descriptions used by
the Remote Service Admin Specification. Endpoint descriptions
are used to describe remote services to a client in cases
where a real live Discovery system isn't used. An extender,
such as a local Discovery Service can look for service
descriptions in installed bundles and inform the Topology
Manager of these remote services. The Topology Manager can then
instruct the Remote Service Admin to create client proxies for
these services.
</documentation>
</annotation>
<element name="endpoint-descriptions" type="rsa:Tendpoint-descriptions" />
<complexType name="Tendpoint-descriptions">
<sequence>
<element name="endpoint-description" type="rsa:Tendpoint-description"
minOccurs="1" maxOccurs="unbounded" />
<!--
It is non-deterministic, per W3C XML Schema 1.0:
http://www.w3.org/TR/xmlschema-1/#cos-nonambig to use
namespace="##any" below.
-->
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax" />
</sequence>
<anyAttribute processContents="lax" />
</complexType>
<complexType name="Tendpoint-description">
<annotation>
<documentation xml:lang="en">
A Distribution Provider can register a proxy with the properties
provided. Whether or not it is instructed to do so, is up to the
Topology Manager. If any 'intents' properties are specified then the
Distribution Provider should only register a proxy if it can support
those intents.
</documentation>
</annotation>
<sequence>
<element name="property" type="rsa:Tproperty" minOccurs="1"
maxOccurs="unbounded" />
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax" />
</sequence>
<anyAttribute processContents="lax" />
</complexType>
<complexType name="Tproperty" mixed="true">
<sequence>
<choice minOccurs="0" maxOccurs="1">
<element name="array" type="rsa:Tmulti-value"/>
<element name="list" type="rsa:Tmulti-value"/>
<element name="set" type="rsa:Tmulti-value"/>
<element name="xml" type="rsa:Txml"/>
</choice>
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax" />
</sequence>
<attribute name="name" type="string" use="required" />
<attribute name="value" type="string" use="optional" />
<attribute name="value-type" type="rsa:Tvalue-types" default="String" use="optional" />
<anyAttribute processContents="lax" />
</complexType>
<complexType name="Tmulti-value">
<sequence>
<element name="value" minOccurs="0" maxOccurs="unbounded" type="rsa:Tvalue"/>
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax" />
</sequence>
<anyAttribute processContents="lax" />
</complexType>
<complexType name="Tvalue" mixed="true">
<sequence>
<element name="xml" minOccurs="0" maxOccurs="1" type="rsa:Txml"/>
<any namespace="##other" minOccurs="0" maxOccurs="unbounded"
processContents="lax" />
</sequence>
<anyAttribute processContents="lax" />
</complexType>
<!-- Specifies the data type of a property or of the elements in a multi-value
property. Numerical and boolean values are trimmed before they are processed.
Simple types are automatically boxed if needed. Only the array data type
allows for simple type values. When specifying a simple type on any other
type of property it will automatically be boxed. -->
<simpleType name="Tvalue-types">
<restriction base="string">
<enumeration value="String" />
<enumeration value="long" />
<enumeration value="Long" />
<enumeration value="double" />
<enumeration value="Double" />
<enumeration value="float" />
<enumeration value="Float" />
<enumeration value="int" />
<enumeration value="Integer" />
<enumeration value="byte" />
<enumeration value="Byte" />
<enumeration value="char" />
<enumeration value="Character" />
<enumeration value="boolean" />
<enumeration value="Boolean" />
<enumeration value="short" />
<enumeration value="Short" />
</restriction>
</simpleType>
<!-- This complex type allows literal XML to be specified in an <xml/> tag (which
is more convenient than putting it in a CDATA section).
The embedded XML must be well-formed and not be in the rsa namespace. It will
be put in a String value of a property or in an element of a multi-value
property of base type String. The XML will be prefixed with the standard
<?XML ?> header which is copied from the enclosing document. Hence it will
carry the same version and encoding as the document in the rsa namespace. -->
<complexType name="Txml">
<sequence>
<any namespace="##other" minOccurs="1" maxOccurs="1"
processContents="lax" />
</sequence>
<anyAttribute processContents="lax" />
</complexType>
<attribute name="must-understand" type="boolean" default="false">
<annotation>
<documentation xml:lang="en">
This attribute should be used by extensions to documents
to require that the document consumer understand the
extension.
</documentation>
</annotation>
</attribute>
</schema>
A bundle containing Endpoint Description Extender resources can
indicate its dependency on the Remote Service Admin extender by
declaring a requirement on the osgi.extender
namespace.
Require-Capability: osgi.extender;
filter:="(&(osgi.extender=osgi.remoteserviceadmin.localdiscovery)
(version>=1.0)(!(version>=2.0)))"
With this constraint declared a bundle that depends on the extender will fail to resolve if no extender is present in the framework.
Implementations of this specification must provide this extender capability at version 1.0 as follows:
Provide-Capability: osgi.extender;
osgi.extender="osgi.remoteserviceadmin.localdiscovery";
version:Version="1.0";
uses:="org.osgi.service.remoteserviceadmin"
The reason that the extender capability is declared at version 1.0 is because the extender is unchanged from version 1.0 of this specification.
Discovery Providers use the
osgi.remoteserviceadmin.discovery
namespace to declare
themselves as such. The version defined for this namespace indicates the
version of this specification that the discovery provider
supports.
This namespace has a defined attribute, protocols
of
type List<String>
, which contains a list of the
discovery protocols supported by the discovery provider. Local discovery
providers (using the Endpoint Description Extender Format), should use the value
local
to indicate that they support this. Additionally, it
defines a version
attribute. Other values for the protocols
attribute are implementation specific.
Table 122.3 osgi.remoteserviceadmin.discovery Namespace
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
protocols |
CA |
M |
List<String> |
symbolic-name |
The discovery protocols supported. A value of
|
version |
CA |
M |
Version |
version |
This version must correspond to the version of the Remote Service Admin specification. |
Example: A discovery provider that provides local and SLP discovery:
Provide-Capability: osgi.remoteserviceadmin.discovery;
protocols:List<String>="SLP,local"; version:Version=1.1
Distribution providers advertise their supported distribution
mechanisms using configuration types. These are selected at runtime
using the service.exported.configs
service property.
Distribution providers can use the
osgi.remoteserviceadmin.distribution
namespace with
attribute configs
, of type List<String>
,
to advertise the supported config types.
Table 122.4 osgi.remoteserviceadmin.distribution Namespace
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
configs |
CA |
M |
List<String> |
symbolic-name |
Supported configuration types. See Endpoint Description . |
version |
CA |
M |
Version |
version |
This version must correspond to the version of the Remote Service Admin specification. |
Example: A Distribution provider that supports the
org.acme.jaxws
and org.acme.jaxrs
configuration types:
Provide-Capability: osgi.remoteserviceadmin.distribution;
configs:List<String>="org.acme.jaxws,org.acme.jaxrs"; version:Version=1.1
Remote Service Admin topology managers may use different policies
when determining which services to export and/or import. Topology
managers use the namespace osgi.remoteserviceadmin.topology
to declare this behavior. This namespace defines the policy
attribute of type List<String>
. Values are
implementation specific, but example definitions can be found at Example Use Cases.
Table 122.5 osgi.remoteserviceadmin.topology Namespace
Name | Kind | M/O | Type | Syntax | Description |
---|---|---|---|---|---|
policy |
CA |
M |
List<String> |
symbolic-name |
The policy used for importing and exporting services. In general the policy is implementation specific. |
version |
CA |
M |
Version |
version |
This version must correspond to the version of the Remote Service Admin specification. |
Example: A Topology manager that supports a promiscuous policy:
Provide-Capability: osgi.remoteserviceadmin.topology;
policy:List<String>=promiscuous; version:Version=1.1
The Distribution Provider provides the Remote
Service Admin service. To inform tools about this
service it must provide the osgi.service
namespace representing the RemoteServiceAdmin service. This capability must also declare a
uses constraint for the org.osgi.service.remoteserviceadmin
package:
Provide-Capability: osgi.service;
objectClass:List<String>=
"org.osgi.service.remoteserviceadmin.RemoteServiceAdmin";
uses:="org.osgi.service.remoteserviceadmin"
This capability must follow the rules defined for the osgi.service Namespace.
This section is not intended to be normative, but offers advice to
implementations as to how the complexity of supporting both the new
Endpoint Event Listener and Endpoint Listener services can be managed and
minimized. This advice applies to both Discovery Providers and Topology
Managers implementing Remote Service Admin 1.1
.
Endpoint Event Listeners and Endpoint Listeners have a very similar behavior and lifecycle. They also use the same property names to define their scope filter. It is therefore relatively simple for an Endpoint Description Provider to notify both Endpoint Listener and Endpoint Event Listeners using a single code path.
One possible mechanism is to track both the listener types using
the same Service Tracker. If the tracked Service Reference advertises
the EndpointEventListener
interface then it must be treated
as an Endpoint Event Listener. If not then the Endpoint Listener service
can be wrapped in an adapter that converts Endpoint Event Listener
events into the appropriate Endpoint Listener calls. The main
notification code path can then treat every listener as an Endpoint
Event Listener.
The Remote Service Admin 1.1
specification is
backward compatible with version 1.0
, meaning that version
1.1 actors must register an Endpoint Listener service. There is no
restriction requiring this listener to be the same service as the
Endpoint Event Listener, however there is a significant advantage to
combining the listeners into a single service registration.
By making the two listeners a single service object a bundle can guarantee that it will not receive multiple notifications for the same event. If the service registrations are separate then Endpoint Description Providers will see two separate listeners, and notify them both. As a single service registration only one event will occur, and using the highest mutually supported version of the Remote Service Admin Specification.
From a security point of view distribution is a significant threat. A Distribution Provider requires very significant capabilities to be able to proxy services. In many situations it will be required to grant the distribution provider All Permission. It is therefore highly recommended that Distribution Providers use trusted links and ensure that it is not possible to attack a system through the Remote Services Admin service and used discovery protocols.
Import and Export Registrations are capabilities. That is, they can only be obtained when the caller has the proper permissions but once obtained they are no longer checked. The caller should therefore be careful to share those objects with other bundles. Export and Import References are free to share.
The Remote Service Admin implementation requires a large set of permissions because it must be able to distribute potentially any service. Giving these extensive capabilities to all Topology Managers would make it harder to developer general Topology Managers that implements specific scenarios. For this reason, this specification provides an Endpoint Permission.
When an Endpoint Permission must be verified, it must be created with an Endpoint Description as argument, like:
sm.checkPermission( new EndpointPermission(anEndpoint,localUUID,READ));
The standard name and action constructor is used to define a
permission. The name argument is a filter expression. The filter for an
Endpoint Permission is applied to the properties of an Endpoint
Description. The localUUID
must map to the UUID of the
framework of the caller of this constructor, see Framework UUID. This localUUID
is used to allow a the
permissions to use the <<LOCAL>>
magic name in
the permission filter to refer to the local framework.
The filter expression can use the following magic value:
-
<<LOCAL>>
- This value represents the framework UUID of the framework that this bundle belongs to. The following example restricts the visibility to descriptions of local Endpoints:ALLOW { ...EndpointPermission "(endpoint.framework.uuid=<<LOCAL>>)" "READ" }
An Endpoint Permission that has the actions listed in the following table.
Table 122.6 Endpoint Permission Actions
Action | Methods | Description |
---|---|---|
IMPORT |
Import an Endpoint |
|
EXPORT |
Export a service |
|
READ |
See the presence of distributed services. The
|
Remote Service Admin Package Version 1.1.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.service.remoteserviceadmin; version="[1.1,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.service.remoteserviceadmin; version="[1.1,1.2)"
-
EndpointDescription
- A description of an endpoint that provides sufficient information for a compatible distribution provider to create a connection to this endpoint An Endpoint Description is easy to transfer between different systems because it is property based where the property keys are strings and the values are simple types. -
EndpointEvent
- An Endpoint Event. -
EndpointEventListener
- A white board service that represents a listener for endpoints. -
EndpointListener
- Deprecated white board service that represents a listener for endpoints. -
EndpointPermission
- A bundle's authority to export, import or read an Endpoint. -
ExportReference
- An Export Reference associates a service with a local endpoint. -
ExportRegistration
- An Export Registration associates a service to a local endpoint. -
ImportReference
- An Import Reference associates an active proxy service to a remote endpoint. -
ImportRegistration
- An Import Registration associates an active proxy service to a remote endpoint. -
RemoteConstants
- Provide the definition of the constants used in the Remote Service Admin specification. -
RemoteServiceAdmin
- A Remote Service Admin manages the import and export of services. -
RemoteServiceAdminEvent
- Provides the event information for a Remote Service Admin event. -
RemoteServiceAdminListener
- A RemoteServiceAdminEvent listener is notified synchronously of any export or import registrations and unregistrations.
A description of an endpoint that provides sufficient information for a
compatible distribution provider to create a connection to this endpoint
An Endpoint Description is easy to transfer between different systems because
it is property based where the property keys are strings and the values are
simple types. This allows it to be used as a communications device to convey
available endpoint information to nodes in a network.
An Endpoint Description reflects the perspective of an importer. That
is, the property keys have been chosen to match filters that are created by
client bundles that need a service. Therefore the map must not contain any
service.exported.*
property and must contain the corresponding
service.imported.*
ones.
The service.intents
property must contain the intents provided by the
service itself combined with the intents added by the exporting distribution
provider. Qualified intents appear fully expanded on this property.
Immutable
The map from which to create the Endpoint Description.
The keys in the map must be type String
and, since the
keys are case insensitive, there must be no duplicates with case
variation.
Create an Endpoint Description from a Map.
The endpoint.id,
service.imported.configs
and objectClass
properties must be set.
IllegalArgumentException
– When the properties are not proper for
an Endpoint Description.
A service reference that can be exported.
Map of properties. This argument can be null
.
The keys in the map must be type String
and, since the
keys are case insensitive, there must be no duplicates with case
variation.
Create an Endpoint Description based on a Service Reference and a Map of properties. The properties in the map take precedence over the properties in the Service Reference.
This method will automatically set the endpoint.framework.uuid and endpoint.service.id properties based on the specified Service Reference as well as the service.imported property if they are not specified as properties.
The endpoint.id,
service.imported.configs
and objectClass
properties must be set.
IllegalArgumentException
– When the properties are not proper for
an Endpoint Description
The EndpointDescription
object to be compared.
Compares this EndpointDescription
object to another object.
An Endpoint Description is considered to be equal to another Endpoint Description if their ids are equal.
true
if object
is a EndpointDescription
and is equal to this object; false
otherwise.
Returns the configuration types. A distribution provider exports a service with an endpoint. This endpoint uses some kind of communications protocol with a set of configuration parameters. There are many different types but each endpoint is configured by only one configuration type. However, a distribution provider can be aware of different configuration types and provide synonyms to increase the change a receiving distribution provider can create a connection to this endpoint. This value of the configuration types is stored in the RemoteConstants.SERVICE_IMPORTED_CONFIGS service property.
An unmodifiable list of the configuration types used for the associated endpoint and optionally synonyms.
Return the framework UUID for the remote service, if present. The value of the remote framework UUID is stored in the RemoteConstants.ENDPOINT_FRAMEWORK_UUID endpoint property.
Remote Framework UUID, or null
if this endpoint is not
associated with an OSGi framework having a framework UUID.
Returns the endpoint's id. The id is an opaque id for an endpoint. No two different endpoints must have the same id. Two Endpoint Descriptions with the same id must represent the same endpoint. The value of the id is stored in the RemoteConstants.ENDPOINT_ID property.
The id of the endpoint, never null
. The returned value
has leading and trailing whitespace removed.
Return the list of intents implemented by this endpoint. The intents are based on the service.intents on an imported service, except for any intents that are additionally provided by the importing distribution provider. All qualified intents must have been expanded. This value of the intents is stored in the RemoteConstants.SERVICE_INTENTS service property.
An unmodifiable list of expanded intents that are provided by this endpoint.
Provide the list of interfaces implemented by the exported service.
The value of the interfaces is derived from the objectClass
property.
An unmodifiable list of Java interface names implemented by this endpoint.
The name of the package for which a version is requested.
Provide the version of the given package name. The version is encoded by prefixing the given package name with endpoint.package.version., and then using this as an endpoint property key. For example:
endpoint.package.version.com.acme
The value of this property is in String format and will be converted to a
Version
object by this method.
The version of the specified package or
Version.emptyVersion
if the package has no version in
this Endpoint Description.
IllegalArgumentException
– If the version property value is not
String.
Returns all endpoint properties.
An unmodifiable map referring to the properties of this Endpoint Description.
Returns the service id for the service exported through this endpoint. This is the service id under which the framework has registered the service. This field together with the Framework UUID is a globally unique id for a service. The value of the remote service id is stored in the RemoteConstants.ENDPOINT_SERVICE_ID endpoint property.
Service id of a service or 0 if this Endpoint Description does not relate to an OSGi service.
Returns a hash code value for the object.
An integer which is a hash code value for this object.
The Endpoint Description to look at
Answers if this Endpoint Description refers to the same service instance as the given Endpoint Description. Two Endpoint Descriptions point to the same service if they have the same id or their framework UUIDs and remote service ids are equal.
True if this endpoint description points to the same service as the other
The filter to test.
Tests the properties of this EndpointDescription
against the
given filter using a case insensitive match.
true
If the properties of this
EndpointDescription
match the filter, false
otherwise.
IllegalArgumentException
– If filter
contains an invalid
filter string that cannot be parsed.
An Endpoint Event.
EndpointEvent
objects are delivered to all registered
EndpointEventListener services where the EndpointDescription
properties match one of the filters specified in the
EndpointEventListener.ENDPOINT_LISTENER_SCOPE registration properties
of the Endpoint Event Listener.
A type code is used to identify the type of event. The following event types are defined:
Additional event types may be defined in the future.
1.1
Immutable
An endpoint has been added.
This EndpointEvent
type indicates that a new endpoint has been
added. The endpoint is represented by the associated
EndpointDescription object.
The properties of an endpoint have been modified.
This EndpointEvent
type indicates that the properties of an
existing endpoint have been modified. The endpoint is represented by the
associated EndpointDescription object and its properties can be
obtained via EndpointDescription.getProperties(). The endpoint
properties still match the filters as specified in the
EndpointEventListener.ENDPOINT_LISTENER_SCOPE filter.
The properties of an endpoint have been modified and the new properties no longer match the listener's filter.
This EndpointEvent
type indicates that the properties of an
existing endpoint have been modified and no longer match the filter. The
endpoint is represented by the associated EndpointDescription
object and its properties can be obtained via
EndpointDescription.getProperties(). As a consequence of the
modification the filters as specified in the
EndpointEventListener.ENDPOINT_LISTENER_SCOPE do not match any
more.
An endpoint has been removed.
This EndpointEvent
type indicates that an endpoint has been
removed. The endpoint is represented by the associated
EndpointDescription object.
The event type. See getType().
The endpoint associated with the event.
Constructs a EndpointEvent
object from the given arguments.
Return the endpoint associated with this event.
The endpoint associated with the event.
Return the type of this event.
The type values are:
The type of this event.
A white board service that represents a listener for endpoints. An Endpoint Event Listener represents a participant in the distributed model that is interested in Endpoint Descriptions. This white board service can be used in many different scenarios. However, the primary use case is to allow a remote manager to be informed of Endpoint Descriptions available in the network and inform the network about available Endpoint Descriptions. Both the network bundle and the manager bundle register an Endpoint Event Listener service. The manager informs the network bundle about Endpoints that it creates. The network bundles then uses a protocol like SLP to announce these local end-points to the network. If the network bundle discovers a new Endpoint through its discovery protocol, then it sends an Endpoint Description to all the Endpoint Listener services that are registered (except its own) that have specified an interest in that endpoint. Endpoint Event Listener services can express their scope with the service property ENDPOINT_LISTENER_SCOPE. This service property is a list of filters. An Endpoint Description should only be given to a Endpoint Event Listener when there is at least one filter that matches the Endpoint Description properties. This filter model is quite flexible. For example, a discovery bundle is only interested in locally originating Endpoint Descriptions. The following filter ensures that it only sees local endpoints.
(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)
In the same vein, a manager that is only interested in remote Endpoint Descriptions can use a filter like:
(!(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72))
Where in both cases, the given UUID is the UUID of the local framework that can be found in the Framework properties. The Endpoint Event Listener's scope maps very well to the service hooks. A manager can just register all filters found from the Listener Hook as its scope. This will automatically provide it with all known endpoints that match the given scope, without having to inspect the filter string. In general, when an Endpoint Description is discovered, it should be dispatched to all registered Endpoint Event Listener services. If a new Endpoint Event Listener is registered, it should be informed about all currently known Endpoints that match its scope. If a getter of the Endpoint Listener service is unregistered, then all its registered Endpoint Description objects must be removed. The Endpoint Event Listener models a best effort approach. Participating bundles should do their utmost to keep the listeners up to date, but implementers should realize that many endpoints come through unreliable discovery processes. The Endpoint Event Listener supersedes the EndpointListener interface as it also supports notifications around modifications of endpoints.
1.1
Thread-safe
Specifies the interest of this listener with filters. This listener is
only interested in Endpoint Descriptions where its properties match the
given filter. The type of this property must be String+
.
The event containing the details about the change.
The filter from the ENDPOINT_LISTENER_SCOPE that
matches (or for EndpointEvent.MODIFIED_ENDMATCH and
EndpointEvent.REMOVED used to match) the endpoint, must
not be null
.
Notification that an endpoint has changed. Details of the change is captured in the Endpoint Event provided. This could be that an endpoint was added, removed or modified.
Deprecated white board service that represents a listener for endpoints. An Endpoint Listener represents a participant in the distributed model that is interested in Endpoint Descriptions. The Endpoint Listener is called back when matching endpoints are added or removed. Consumers interested in the modification of endpoints, when associated service properties are changed, should use an EndpointEventListener instead. This white board service can be used in many different scenarios. However, the primary use case is to allow a remote manager to be informed of Endpoint Descriptions available in the network and inform the network about available Endpoint Descriptions. Both the network bundle and the manager bundle register an Endpoint Listener service. The manager informs the network bundle about Endpoints that it creates. The network bundles then uses a protocol like SLP to announce these local end-points to the network. If the network bundle discovers a new Endpoint through its discovery protocol, then it sends an Endpoint Description to all the Endpoint Listener services that are registered (except its own) that have specified an interest in that endpoint. Endpoint Listener services can express their scope with the service property ENDPOINT_LISTENER_SCOPE. This service property is a list of filters. An Endpoint Description should only be given to a Endpoint Listener when there is at least one filter that matches the Endpoint Description properties. This filter model is quite flexible. For example, a discovery bundle is only interested in locally originating Endpoint Descriptions. The following filter ensure that it only sees local endpoints.
(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)
In the same vein, a manager that is only interested in remote Endpoint Descriptions can use a filter like:
(!(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72))
Where in both cases, the given UUID is the UUID of the local framework that can be found in the Framework properties. The Endpoint Listener's scope maps very well to the service hooks. A manager can just register all filters found from the Listener Hook as its scope. This will automatically provide it with all known endpoints that match the given scope, without having to inspect the filter string. In general, when an Endpoint Description is discovered, it should be dispatched to all registered Endpoint Listener services. If a new Endpoint Listener is registered, it should be informed about all currently known Endpoints that match its scope. If a getter of the Endpoint Listener service is unregistered, then all its registered Endpoint Description objects must be removed. The Endpoint Listener models a best effort approach. Participating bundles should do their utmost to keep the listeners up to date, but implementers should realize that many endpoints come through unreliable discovery processes.
As of 1.1. Replaced by EndpointEventListener.
Thread-safe
Specifies the interest of this listener with filters. This listener is
only interested in Endpoint Descriptions where its properties match the
given filter. The type of this property must be String+
.
The Endpoint Description to be published
The filter from the ENDPOINT_LISTENER_SCOPE
that matched the endpoint, must not be null
.
Register an endpoint with this listener.
If the endpoint matches one of the filters registered with the
ENDPOINT_LISTENER_SCOPE service property then this filter should
be given as the matchedFilter
parameter.
When this service is first registered or it is modified, it should
receive all known endpoints matching the filter.
The Endpoint Description that is no longer valid.
The filter from the ENDPOINT_LISTENER_SCOPE
that matched the endpoint, must not be null
.
Remove the registration of an endpoint. If an endpoint that was registered with the endpointAdded(EndpointDescription, String) method is no longer available then this method should be called. This will remove the endpoint from the listener. It is not necessary to remove endpoints when the service is unregistered or modified in such a way that not all endpoints match the interest filter anymore.
A bundle's authority to export, import or read an Endpoint.
-
The
export
action allows a bundle to export a service as an Endpoint. -
The
import
action allows a bundle to import a service from an Endpoint. -
The
read
action allows a bundle to read references to an Endpoint.
Permission to read an Endpoint is required in order to detect events
regarding an Endpoint. Untrusted bundles should not be able to detect the
presence of certain Endpoints unless they have the appropriate
EndpointPermission
to read the specific service.
Thread-safe
The action string export
. The export
action implies the
read
action.
The action string import
. The import
action implies the
read
action.
The filter string or "*" to match all endpoints.
The actions read
, import
, or
export
.
Create a new EndpointPermission with the specified filter.
The filter will be evaluated against the endpoint properties of a requested EndpointPermission.
There are three possible actions: read
, import
and
export
. The read
action allows the owner of this
permission to see the presence of distributed services. The
import
action allows the owner of this permission to import an
endpoint. The export
action allows the owner of this permission
to export a service.
IllegalArgumentException
– If the filter has an invalid syntax or
the actions are not valid.
The requested endpoint.
The UUID of the local framework. This is used
to support matching the
endpoint.framework.uuid endpoint property to the
<<LOCAL>>
value in the filter expression.
The actions read
, import
, or
export
.
Creates a new requested EndpointPermission
object to be used by
code that must perform checkPermission
.
EndpointPermission
objects created with this constructor cannot
be added to an EndpointPermission
permission collection.
IllegalArgumentException
– If the endpoint is null
or the
actions are not valid.
The object to test for equality.
Determines the equality of two EndpointPermission objects.
Checks that specified object has the same name, actions and endpoint as
this EndpointPermission
.
true If obj is a EndpointPermission
, and has the same
name, actions and endpoint as this EndpointPermission
object; false
otherwise.
Returns the canonical string representation of the actions. Always
returns present actions in the following canonical order: read
,
import
, export
.
The canonical string representation of the actions.
Returns the hash code value for this object.
Hash code value for this object.
The target permission to check.
Determines if a EndpointPermission
object "implies" the specified
permission.
true
if the specified permission is implied by this
object; false
otherwise.
An Export Reference associates a service with a local endpoint.
The Export Reference can be used to reference an exported service. When the
service is no longer exported, all methods must return null
.
Thread-safe
Consumers of this API must not implement this type
Return the Endpoint Description for the local endpoint.
The Endpoint Description for the local endpoint. Must be
null
when the service is no longer exported.
An Export Registration associates a service to a local endpoint.
The Export Registration can be used to delete the endpoint associated with an
this registration. It is created with the
RemoteServiceAdmin.exportService(ServiceReference,Map) method.
When this Export Registration has been closed, all methods must return
null
.
Thread-safe
Consumers of this API must not implement this type
Delete the local endpoint and disconnect any remote distribution
providers. After this method returns, all methods must return
null
.
This method has no effect when this registration has already been closed
or is being closed.
Return the exception for any error during the export process.
If the Remote Service Admin for some reasons is unable to properly
initialize this registration, then it must return an exception from this
method. If no error occurred, this method must return null
.
The error must be set before this Export Registration is returned.
Asynchronously occurring errors must be reported to the log.
The exception that occurred during the initialization of this
registration or null
if no exception occurred.
Return the Export Reference for the exported service.
The Export Reference for this registration, or null
if this Import Registration is closed.
IllegalStateException
– When this registration was not properly
initialized. See getException().
properties to be merged with the current service properties for the ServiceReference represented by this ExportRegistration. If null is passed then the original properties passed to RemoteServiceAdmin.exportService(ServiceReference, Map) will be used.
Update the endpoint represented by this ExportRegistration and return an updated EndpointDescription. If this method returns an updated EndpointDescription, then the object returned via getExportReference() must also have been updated to return this new object. If this method does not return an updated EndpointDescription then the object returned via getExportReference() should remain unchanged. When creating the updated EndpointDescription the ServiceReference originally passed to RemoteServiceAdmin.exportService(ServiceReference, Map) must be queried to pick up any changes to its service properties. If this argument is null then the original properties passed when creating this ExportRegistration should be used when constructing the updated EndpointDescription. Otherwise the new properties should be used, and replace the original properties for subsequent calls to the update method.
The updated EndpointDescription for this registration or null if there was a failure updating the endpoint. If a failure occurs then it can be accessed using getException().
IllegalStateException
– If this registration is closed, or when
this registration was not properly initialized. See
getException().
1.1
An Import Reference associates an active proxy service to a remote endpoint.
The Import Reference can be used to reference an imported service. When the
service is no longer imported, all methods must return null
.
Thread-safe
Consumers of this API must not implement this type
Return the Endpoint Description for the remote endpoint.
The Endpoint Description for the remote endpoint. Must be
null
when the service is no longer imported.
An Import Registration associates an active proxy service to a remote
endpoint.
The Import Registration can be used to delete the proxy associated with an
endpoint. It is created with the
RemoteServiceAdmin.importService(EndpointDescription) method.
When this Import Registration has been closed, all methods must return
null
.
Thread-safe
Consumers of this API must not implement this type
Close this Import Registration. This must close the connection to the
endpoint and unregister the proxy. After this method returns, all other
methods must return null
.
This method has no effect when this registration has already been closed
or is being closed.
Return the exception for any error during the import process.
If the Remote Service Admin for some reasons is unable to properly
initialize this registration, then it must return an exception from this
method. If no error occurred, this method must return null
.
The error must be set before this Import Registration is returned.
Asynchronously occurring errors must be reported to the log.
The exception that occurred during the initialization of this
registration or null
if no exception occurred.
Return the Import Reference for the imported service.
The Import Reference for this registration, or null
if this Import Registration is closed.
IllegalStateException
– When this registration was not properly
initialized. See getException().
The updated endpoint
Update the local service represented by this ImportRegistration. After this method returns the EndpointDescription returned via getImportReference() must have been updated.
true
if the endpoint was successfully updated,
false
otherwise. If the update fails then the
failure can be retrieved from getException().
IllegalStateException
– When this registration is closed, or if it
was not properly initialized. See getException().
IllegalArgumentException
– When the supplied
EndpointDescription does not represent the same endpoint
as this ImportRegistration.
1.1
Provide the definition of the constants used in the Remote Service Admin specification.
Immutable
Endpoint property identifying the universally unique id of the exporting framework. Can be absent if the corresponding endpoint is not for an OSGi service.
The value of this property must be of type String
.
Endpoint property identifying the id for this endpoint. This service property must always be set.
The value of this property must be of type String
.
Prefix for an endpoint property identifying the interface Java package
version for an interface. For example, the property
endpoint.package.version.com.acme=1.3
describes the version of
the package for the com.acme.Foo
interface. This endpoint
property for an interface package does not have to be set. If not set,
the value must be assumed to be 0.
Since endpoint properties are stored in a case insensitive map, case variants of a package name are folded together.
The value of properties having this prefix must be of type String
.
Endpoint property identifying the service id of the exported service. Can be absent or 0 if the corresponding endpoint is not for an OSGi service.
The value of this property must be of type Long
.
Service property identifying the configuration types supported by a distribution provider. Registered by the distribution provider on one of its services to indicate the supported configuration types.
The value of this property must be of type String
,
String[]
, or Collection
of String
.
Remote Services Specification
Service property identifying the intents supported by a distribution provider. Registered by the distribution provider on one of its services to indicate the vocabulary of implemented intents.
The value of this property must be of type String
,
String[]
, or Collection
of String
.
Remote Services Specification
Service property identifying the configuration types that should be used to export the service. Each configuration type represents the configuration parameters for an endpoint. A distribution provider should create an endpoint for each configuration type that it supports.
This property may be supplied in the properties
Dictionary
object passed to the
BundleContext.registerService
method. The value of this property
must be of type String
, String[]
, or Collection
of String
.
Remote Services Specification
Service property identifying the intents that the distribution provider must implement to distribute the service. Intents listed in this property are reserved for intents that are critical for the code to function correctly, for example, ordering of messages. These intents should not be configurable.
This property may be supplied in the properties
Dictionary
object passed to the
BundleContext.registerService
method. The value of this property
must be of type String
, String[]
, or Collection
of String
.
Remote Services Specification
Service property identifying the extra intents that the distribution
provider must implement to distribute the service. This property is
merged with the service.exported.intents
property before the
distribution provider interprets the listed intents; it has therefore the
same semantics but the property should be configurable so the
administrator can choose the intents based on the topology. Bundles
should therefore make this property configurable, for example through the
Configuration Admin service.
This property may be supplied in the properties
Dictionary
object passed to the
BundleContext.registerService
method. The value of this property
must be of type String
, String[]
, or Collection
of String
.
Remote Services Specification
Service property marking the service for export. It defines the
interfaces under which this service can be exported. This list must be a
subset of the types under which the service was registered. The single
value of an asterisk ('*'
\u002A) indicates all the interface
types under which the service was registered excluding the non-interface
types. It is strongly recommended to only export interface types and not
concrete classes due to the complexity of creating proxies for some type
of concrete classes.
This property may be supplied in the properties
Dictionary
object passed to the
BundleContext.registerService
method. The value of this property
must be of type String
, String[]
, or Collection
of String
.
Remote Services Specification
Service property identifying the service as imported. This service property must be set by a distribution provider to any value when it registers the endpoint proxy as an imported service. A bundle can use this property to filter out imported services.
The value of this property may be of any type.
Remote Services Specification
Service property identifying the configuration types used to import the service. Any associated properties for this configuration types must be properly mapped to the importing system. For example, a URL in these properties must point to a valid resource when used in the importing framework. If multiple configuration types are listed in this property, then they must be synonyms for exactly the same remote endpoint that is used to export this service.
The value of this property must be of type String
,
String[]
, or Collection
of String
.
Remote Services Specification
, SERVICE_EXPORTED_CONFIGS
Service property identifying the intents that this service implement. This property has a dual purpose:
-
A bundle can use this service property to notify the distribution provider that these intents are already implemented by the exported service object.
-
A distribution provider must use this property to convey the combined intents of: The exporting service, and the intents that the exporting distribution provider adds, and the intents that the importing distribution provider adds.
To export a service, a distribution provider must expand any qualified
intents. Both the exporting and importing distribution providers must
recognize all intents before a service can be distributed.
The value of this property must be of type String
,
String[]
, or Collection
of String
.
Remote Services Specification
A Remote Service Admin manages the import and export of services. A Distribution Provider can expose a control interface. This interface allows a Topology Manager to control the export and import of services. The API allows a Topology Manager to export a service, to import a service, and find out about the current imports and exports.
Thread-safe
Consumers of this API must not implement this type
The Service Reference to export.
The properties to create a local Endpoint that can be
implemented by this Remote Service Admin. If this is null
,
the Endpoint will be determined by the properties on the service.
The properties are the same as given for an exported service. They
override any properties in the specified Service Reference (case
insensitive). The properties objectClass
and
service.id
, in any case variant, are ignored. Those
properties in the Service Reference cannot be overridden. This
parameter can be null
, this should be treated as an empty
map.
Export a service to a given Endpoint. The Remote Service Admin must
create an Endpoint from the given description that can be used by other
Distribution Providers to connect to this Remote Service Admin and use
the exported service.
The property keys of a Service Reference are case insensitive while the
property keys of the specified properties
map are case sensitive.
A property key in the specified properties
map must therefore
override any case variant property key in the properties of the specified
Service Reference.
If the caller does not have the appropriate
EndpointPermission[endpoint,EXPORT]
for an Endpoint, and the Java
Runtime Environment supports permissions, then the
getException method on the
corresponding returned ExportRegistration will return a
SecurityException
.
A Collection
of ExportRegistrations for the
specified Service Reference and properties. Multiple Export
Registrations may be returned because a single service can be
exported to multiple Endpoints depending on the available
configuration type properties and the intents that they support.
The result is never null
but may be empty if this Remove
Service Admin does not recognize any of the configuration types,
or if the Remote Service Admin cannot support the relevant
intents.
IllegalArgumentException
– If any of the properties for this
configuration type has a value that is not syntactically correct,
or if the service properties and the overlaid properties do not
contain a RemoteConstants.SERVICE_EXPORTED_INTERFACES
entry. This means that implementations must not ignore invalid
values for property names that they recognize.
Return the currently active Export References.
If the caller does not have the appropriate
EndpointPermission[endpoint,READ]
for an Endpoint, and the Java
Runtime Environment supports permissions, then returned collection will
not contain a reference to the exported Endpoint.
A Collection
of ExportReferences that are
currently active.
Return the currently active Import References.
If the caller does not have the appropriate
EndpointPermission[endpoint,READ]
for an Endpoint, and the Java
Runtime Environment supports permissions, then returned collection will
not contain a reference to the imported Endpoint.
A Collection
of ImportReferences that are
currently active.
The Endpoint Description to be used for import.
Import a service from an Endpoint. The Remote Service Admin must use the
given Endpoint to create a proxy. This method can return null
if
the service could not be imported.
An Import Registration that combines the Endpoint Description and
the Service Reference or null
if the Endpoint could not
be imported.
SecurityException
– If the caller does not have the appropriate
EndpointPermission[endpoint,IMPORT]
for the Endpoint, and
the Java Runtime Environment supports permissions.
Provides the event information for a Remote Service Admin event.
Immutable
A fatal exporting error occurred. The Export Registration has been closed.
Add an export registration. The Remote Service Admin will send this event when it exports a service. When the RemoteServiceAdminListener service is registered, the Remote Service Admin must notify the listener of all existing Export Registrations.
Remove an export registration. The Remote Service Admin will send this event when it removes the export of a service.
Update an export registration. The Remote Service Admin will send this event when it exports a service.
1.1
A problematic situation occurred, the export is still active.
A fatal importing error occurred. The Import Registration has been closed.
Add an import registration. The Remote Service Admin will send this event when it imports a service. When the RemoteServiceAdminListener service is registered, the Remote Service Admin must notify the listener of all existing Import Registrations.
Remove an import registration. The Remote Service Admin will send this event when it removes the import of a service.
Update an import registration. The Remote Service Admin will send this event when it updates a service.
1.1
A problematic situation occurred, the import is still active.
The event type.
The source bundle, must not be null
.
The exportReference, can not be null
.
Any exceptions encountered, can be null
.
Create a Remote Service Admin Event for an export notification.
The event type.
The source bundle, must not be null
.
The importReference, can not be null
.
Any exceptions encountered, can be null
.
Create a Remote Service Admin Event for an import notification.
Return the exception for this event.
The exception or null
.
Return the Export Reference for this event.
The Export Reference or null
.
Return the Import Reference for this event.
The Import Reference or null
.
Return the bundle source of this event.
The bundle source of this event.
A RemoteServiceAdminEvent listener is notified synchronously of any export or import registrations and unregistrations.
If the Java Runtime Environment supports permissions, then filtering is done.
RemoteServiceAdminEvent
objects are only delivered to the listener if
the bundle which defines the listener object's class has the appropriate
EndpointPermission[endpoint,READ]
for the endpoint referenced by the
event.
Thread-safe
The RemoteServiceAdminEvent object.
Receive notification of any export or import registrations and unregistrations as well as errors and warnings.
Remote Service Admin Namespaces Version 1.0.
Bundles should not need to import this package at runtime since all the types in this package just contain constants for capability and requirement namespaces specified by the OSGi Working Group.
-
DiscoveryNamespace
- Remote Services Discovery Provider Capability and Requirement Namespace. -
DistributionNamespace
- Remote Services Distribution Provider Capability and Requirement Namespace. -
TopologyNamespace
- Remote Services Topology Manager Capability and Requirement Namespace.
Remote Services Discovery Provider Capability and Requirement Namespace.
This class defines the names for the attributes and directives for this namespace.
Immutable
The capability attribute used to specify the discovery protocols
supported by this discovery provider. The value of this attribute must be
of type String
or List<String>
.
Remote Services Distribution Provider Capability and Requirement Namespace.
This class defines the names for the attributes and directives for this namespace.
Immutable
The capability attribute used to specify the config types supported by
this distribution provider. The value of this attribute must be of type
String
or List<String>
.
Remote Services Topology Manager Capability and Requirement Namespace.
This class defines the names for the attributes and directives for this namespace.
Immutable
The capability attribute used to specify the policy or policies supported
by this topology manager. The value of this attribute must be of type
String
or List<String>
. Policy names are typically
implementation specific, however the Remote Services Specification
defines the promiscuous and fail-over policies for
common use cases.
The attribute value for Topology managers with a fail-over policy
The attribute value for Topology managers with a promiscuous policy
[1]OSGi Service Property Namespacehttps://docs.osgi.org/reference/service-property-namespace.html
[3]Service Location Protocol (SLP)http://en.wikipedia.org/wiki/Service_Location_Protocol
[4]JGroupshttp://www.jgroups.org/
[6]Service Component Architecture (SCA)http://www.osoa.org/display/Main/Home