This specification defines two different functions that are provided by a Mediator extender:

A Service Provider bundle can provide access to all its Service Providers through OSGi services by declaring a requirement on the osgi.serviceloader.registrar extender. This requirement activates a Mediator to inspect the osgi.serviceloader capabilities. If no register directive is used then all Service Providers for the given Service Type must be registered. Otherwise, each capability can select one Service Provider with the register directive. The fully qualified name selects a specific Service Provider, allowing different Service Providers to be registered with different service properties. The Mediator will then register an OSGi service factory for each selected capability. The osgi.serviceloader capability's attributes are used to decorate the OSGi service registration with service properties. The service factory returns a new instance for each service get.

Consumers are classes that use the Service Loader API to find Service Provider instances. Since the Service Loader API requires full visibility the Service API fails to work inside an OSGi bundle. A osgi.serviceloader.processor extender, which is the Mediator, processes bundles that require this capability by modifying calls to the Service Loader API to ensures that the Service Loader has visibility to published Service Providers.

A Consumer's bundle by default receives visibility to all published Service Providers. Service Providers are published when a bundle declares one or more osgi.serviceloader capabilities for a Service Type. If the Consumer has an osgi.serviceloader requirement for the given Service Type then the Mediator must only expose the bundles that are wired to those requirements and for each bundle provide all its Service Providers.

The Service Loader Mediator can process the Consumer by modifying calls to the Service Loader API. This specification does not detail how the Mediator ensures that the Consumer has visibility to other Service Providers. However, a Mediator could for example set an appropriate Thread Context Class Loader during the call to the Service Loader's constructor by weaving the Consumer's byte codes.

Processing is an opt-in process, the Consumer bundle must declare that it is willing to be processed. The opt-in is handled by a requirement to the osgi.serviceloader.processor extender. This requirement must have a single cardinality (the default) since the Mediator uses the wiring to select the Consumer to process when multiple Mediators are present.

For example, the following requirement in a manifest enables a bundle to be processed:

Require-Capability:
    osgi.extender;
        filter:="(&(osgi.extender=osgi.serviceloader.processor)
                 (version>=1.0)(!(version>=2.0)))"

If the extender osgi.serviceloader.processor requirement is satisfied then the wired Mediator must process the Consumer.

The Mediator must give visibility to all bundles with published Service Providers unless the Consumer restricts the visibility by having osgi.serviceloader requirements. Bundles publish a Service Type, meaning all their Service Providers for that type, by having at least one osgi.serviceloader capability for that Service Type.

A Consumer's bundle can restrict its visibility to certain bundles by declaring an osgi.serviceloader requirement for each Service Type it wants to use. Only bundles wired from those requirement provide their advertised Service Providers. If no such requirements are declared then all bundles with the published Service Type become available.

The cardinality can be used to select a single Service Provider's bundle or multiple bundles if it needs to see all Service Provider bundles. The requirement can be made optional if the Consumer's bundle can work also when no Service Provider bundle is available. See osgi.serviceloader Namespace for more details.

For example, a requirement that restricts visibility to the org.example.Foo Service Providers could look like:

Require-Capability:                             
    osgi.serviceloader;
    filter:="(osgi.serviceloader=org.example.Foo)";
    cardinality:=multiple

In this example, any bundle that publishes the org.example.Foo Service Type will contribute its Service Providers.

Visibility can also be restricted to bundles that publish with capability's attributes. Any bundle that has at least one matching capability will then be able to contribute all its Service Providers. For example, the following example selects only bundles that have the classified property set:

osgi.serviceloader; filter:="(classified=*)"

With Service Registrations, see Registering Services, the capability can discriminate between multiple Service Providers in the same bundle. The Service Loader API does not have this feature: any wired requirement has visibility to all Service Providers in the wired bundle, regardless of the registered directive.

A Consumer can only see Service Provider instances of bundles that are active during the time the next instance is created. That is, the Mediator must treat the life cycle of the Service Provider as if it was a service. However, the Service Loader implementations perform extensive class loader techniques and cache results. The exact life cycle of the Service Provider bundle with respect to the Consumer is therefore impossible to enforce.

The Service Loader API does not have a life cycle, objects are assumed to stay alive during the duration of the VM's process and due to the use of Class.forName in the Service Loader implementations. Therefore a Mediator should refresh a Consumer bundle when it is using a Service Provider and that Service Provider's bundle becomes stopped otherwise long running applications can run out of memory when bundles are regularly updated.

A legacy JAR for which there is no more source code uses the Service Loader API to get access to com.example.Codec instances through the Service Loader API.

It is wrapped in a bundle that then has the following manifest:

Manifest-Version:       1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName:    com.example.impl
Bundle-Version:         23.98.1.v199101232310.02011
Import-Package:         com.example; version=3.45
Bundle-ClassPath:       legacy.jar

The manifest must then declare that the bundle must be processed, this is triggered by requiring the osgi.serviceloader.processor extender:

Require-Capability:                                         
  osgi.extender;
    filter:="(&(osgi.extender=osgi.serviceloader.processor)
             (version>=1.0)(!(version>=2.0)))"

With this manifest, the Consumer bundle has full visibility to all Service Provider bundles that are published. The following lines can be added to restrict the visibility to codecs that have support for WAVE formats (although all Service Providers in that bundle will be visible to the consumer).

,
    osgi.serviceloader;
     filter:="(&(format=WAVE)(osgi.serviceloader=com.example.Codec))"

Service Providers are implementation classes that are advertised under a Service Type according to the rules in the Service Loader API. A Service Provider is advertised with a Provider Configuration File in a JAR. In an OSGi environment the Service Provider must reside in the same bundle as the advertisement or be imported. A single Provider Configuration File can contain multiple Service Providers. See Java Service Loader API.

Service Providers can be used in two different scenarios:

A Service Type must be published to allow its use it in these scenarios. Publishing a Service Type consists of providing one or more osgi.serviceloader capabilities for an advertised Service Type, see osgi.serviceloader Namespace. These osgi.serviceloader capabilities must specify a fully qualified class name of the Service Type, there is no wildcarding allowed. Therefore, publishing a service implicitly makes all corresponding Service Providers available to Consumers.

If a bundle does not provide osgi.serviceloader capabilities then it does not publish any Service Providers and its Service Providers can therefore not be used by Consumers. They can then also not be registered as OSGi services, see OSGi Services. Tools can use the advertisement of the Service Provider in the JAR to automatically generate the osgi.serviceloader capabilities in the manifest.

For example, the following capability publishes all the Service Providers in its bundle that advertise the com.example.Codec interface:

Provide-Capability:
  osgi.serviceloader;
    osgi.serviceloader=com.example.Codec;
    uses:="com.example"

A Service Provider bundle must not require the osgi.serviceloader.processor extender unless it needs to be processed; publishing a Service Type is sufficient to allow Consumers to use the published Service Types.

The Service Provider can have its osgi.serviceloader capabilities be registered as services that provide instances from the Service Providers. For this, the Service Provider bundle must require the osgi.serviceloader.registrar extender, which is the Mediator. For example:

Require-Capability:
    osgi.extender;
        filter:="(&(osgi.extender=osgi.serviceloader.registrar)
                 (version>=1.0)(!(version>=2.0)))"

The registrar must then inspect each osgi.serviceloader capability and register an associated OSGi Service for each Service Provider selected by that capability. A Service Provider is selected when:

A register directive selects a Service Provider if it contains the fully qualified name of the Service Provider, that is, the implementation class. Selection only works for services, Consumer will always see all Service Providers regardless of the register directive due to limitations in the Service Loader API.

For example, the following manifest selects all Service Providers of the com.example.Foo Service Type since no register directive is present:

Provide-Capability:
    osgi.serviceloader;
        uses:="com.example";
        osgi.serviceloader=com.example.Foo

Selected Service Providers must be registered as defined in Registering Services, with the capability's attributes as decorating service properties. Private service properties (attributes that start with a full stop ('.' \u002E) and the defined capability attributes in the osgi.serviceloader namespace are not registered as service properties.

The following example would register the format service property but not the .hint service property for the com.acme.impl.WaveFoo Service Provider.

    osgi.serviceloader;
        osgi.serviceloader=com.example.Foo;
        uses:="com.example";
        format=WAVE;
        .hint=E5437Qy7;
        register:="com.acme.impl.WaveFoo"

The Mediator must only register OSGi services for selected Service Providers; the Service Provider bundle can therefore decide not to register certain Service Providers and register them with another mechanism, for example Declarative Services or in a bundle activator.

Since the Mediator must use the bundle context of the Service Provider to register the OSGi service the Service Provider bundle must have the proper Service Permission REGISTER for the Service Type.

A Foo Codecs JAR needs to be ported to OSGi, it provides a Service Provider for the org.example.Codec Service Type. In this example the JAR is given a new manifest:

Manifest-Version:       1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName:    com.example.foo.codecs
Import-Package:         com.example; version=3.45

To ensure that the bundle opts in to registering its services it must require the osgi.serviceloader.registrar extender.

Require-Capability:                                         
    osgi.extender; 
        filter:="(&(osgi.extender=osgi.serviceloader.registrar)
                 (version>=1.0)(!(version>=2.0)))"

To publish two Service Providers for the same type, two capabilities must be declared:

Provide-Capability:
    osgi.serviceloader;
        osgi.serviceloader="com.example.Codec";
        format:List<String>="WAVE,WMF";
      register:="com.acme.impl.FooWaveCodec";
      uses:="com.example,org.apache.common.codecs",
    osgi.serviceloader;
        osgi.serviceloader="com.example.Codec";
        format:List<String>=SINUS;
      register:="com.acme.impl.sinus.FooSinusCodec";
      uses:="com.example"

This example implicitly publishes the Service Type com.example.Codec multiple times with different attributes. Consumers that match any of these capabilities will however have visibility to all Service Providers since the Service Loader API cannot discriminate between different Service Providers from the same bundle.

The Mediator must track bundles that are wired to its osgi.extender=osgi.serviceloader.registrar capability. These are called the managed bundles. For all managed bundles the Mediator must enumerate all osgi.serviceloader capabilities and register selected Service Providers as OSGi services. A Service Provider is selected by an osgi.serviceloader capability when:

An osgi.serviceloader capability that selects a Service Provider is said to decorate that Service Provider. A capability can decorate multiple Service Providers of the same Service Type and the same Service Provider can be decorated by different capabilities. Figure 133.2 depicts the resulting relations and their cardinalities since the relations are non-trivial.

Figure 133.2 Cardinality Service Type

The OSGi service for each selected Service Provider must be registered under the advertised Service Type of the Service Provider, which must match the Service Type specified in the capability.

The Mediator must register an OSGi service factory with the bundle context of the Service Provider's bundle. The OSGi service factory must be implemented such that it creates a new instance for each bundle that gets the service. This behavior is similar, though not quite identical, to the ServiceLoader.load() method that gives each consumer a separate instance of the service. The difference is that different users inside a bundle will share the same instance.

Each service registration is controlled by a decorating osgi.serviceloader capability. The attributes on this capability must be registered with the OSGi service as service properties, except for:

The following service property must be registered, overriding any identical named properties in the decorating capability:

The Mediator should not verify class space consistency since the OSGi framework already enforces this as long as the publishing capability specifies the uses directive.

Any services registered in the OSGi Service Registry must be unregistered when the Service Provider's bundle is stopped or the Mediator is stopped.

The Service Loader API causes issues in a modular environment because it requires a class loader that has wide visibility. In a modular environment like OSGi the Consumer, the Service Type, and the Service Provider can, and should, all reside in different modules because they represent different concerns. Best practice requires that only the Service Type is shared between these actors. However, for the Service Loader to work as it was designed the Consumer must provide a class loader that has visibility of the Service Provider. The Service Provider is an implementation class, exporting such classes is the anathema of modularity. However, since the standard JRE provides application wide visibility this was never a major concern.

The simplest solution is to make the Service Loader aware of OSGi, its API clear is mappable to the OSGi service layer. However, the Service Loader is not extensible. The result is that using the Service Loader in OSGi fails in general because the Service Loader is unable to find the Service Providers. The issues are:

Consumers are not written for OSGi and require help to successfully use the Service Loader API. It is the Mediator's responsibility to ensure that bundles that are wired to published Service Types have access to these Service Provider's instances through the Service Loader API.

This specification does not define how this is done. There are a number of possibilities and it is up to the Mediator to provide the guarantee to the Consumer that it has been properly processed.

A Mediator must only process Consumer's bundles that are wired to the osgi.extender capability for the osgi.serviceloader.processor extender. Since Consumers must require this extender capability with the default cardinality of 1 there can at most be one extender wired to a Consumer.

The Mediator must process the Consumer bundle in such a way that when the Consumer uses the Service Loader API it receives all the Service Providers of bundles that:

The Mediator must verify that the Consumer has Service Permission GET for the given Service Type since the Consumer uses the Service Type as a service. This specification therefore reuses the Service Permission for this purpose. The check must be done with the ServicePermission(String,String) constructor using the bundle's Access Control Context or the bundle's hasPermission method.

There is a life cycle mismatch between the Service Loader API and the dynamic OSGi world. A Service Loader provides a Consumer with an object that could come from a bundle that is later stopped and/or refreshed. Such an object becomes stale. Mediators should attempt to refresh bundles that have access to these stale objects.

The Mediator will require significant permissions to perform its tasks. First, it will require access to the Bundle Context of the Service Provider bundle, which means it must have Admin Permission:

AdminPermission[<Service Provider Bundles>,CONTEXT|METADATA|CLASS]

Since it will have to register on behalf of the Service Provider bundle it must have complete liberty to register services:

ServicePermission[<Service Type>,REGISTER]

Depending on the way the Consumers are processed additional requirements may be necessary.

The Mediator connects two parties; it must ensure that neither party will receive additional permissions.

Consumers must have:

ServicePermission[<Service Type>,GET] 
PackagePermission[<Service Type's package>,IMPORT]
CapabilityPermission["osgi.extender", REQUIRE]
CapabilityPermission["osgi.serviceloader", REQUIRE]

The Mediator must ensure that the Consumer has the ServicePermission before it provides the instance. It must use the Bundle Context hasPermission method or the bundle's Access Control Context to verify this.

Service Providers must have:

ServicePermission[<Service Type>,REGISTER] 
PackagePermission[<Service Type's package>,IMPORT]
CapabilityPermission["osgi.extender", REQUIRE]
CapabilityPermission["osgi.serviceloader", PROVIDE]

The Mediator must ensure that the Service Provider has the ServicePermission before it provides the instance. It must use the Bundle Context hasPermission method or the bundle's Access Control Context to verify this.