Class RankedServices<T>

  • Type Parameters:
    T - Service type
    All Implemented Interfaces:
    java.lang.Iterable<T>

    @ProviderType
    public final class RankedServices<T>
    extends java.lang.Object
    implements java.lang.Iterable<T>
    Helper class that collects all services registered via OSGi bind/unbind methods. The services are ordered by service ranking and can be iterated directly using this object instance. Implementation is thread-safe.

    With Declarative Services 1.3 supporting field injection with multiple cardinality (leveraging Collections), this class should only be used if DS 1.3 cannot be used for some reason. DS 1.3 is using the same ordering as ServiceReference.compareTo(Object).

    Usage example:

    1. Define a dynamic reference with cardinality OPTIONAL_MULTIPLE in your service:

     @Reference(name = "myService", referenceInterface = MyService.class,
         cardinality = ReferenceCardinality.OPTIONAL_MULTIPLE, policy = ReferencePolicy.DYNAMIC)
     private final RankedServices<MyService> myServices = new RankedServices<MyService>(Order.DESCENDING);
     

    2. Define bind/unbind methods that delegate to the RankedServices instance:

     void bindMyService(MyService service, Map<String, Object> props) {
       myServices.bind(service, props);
     }
     void unbindMyService(MyService service, Map<String, Object> props) {
       myServices.unbind(service, props);
     }
     

    To access the list of referenced services you can access them in a thread-safe manner:

     for (MyService service : myServices) {
       // your code...
     }
     

    Optionally you can pass in a RankedServices.ChangeListener instance to get notified when the list of referenced services has changed.

    Since:
    2.3
    See Also:
    "OSGi Compendium 6.0, Declarative Services 1.3, Reference Field Option, ยง112.3.8.1"
    • Method Detail

      • bind

        public void bind​(T service,
                         java.util.Map<java.lang.String,​java.lang.Object> props)
        Handle bind service event.
        Parameters:
        service - Service instance
        props - Service reference properties
      • unbind

        public void unbind​(T service,
                           java.util.Map<java.lang.String,​java.lang.Object> props)
        Handle unbind service event.
        Parameters:
        service - Service instance
        props - Service reference properties
      • get

        public java.util.Collection<T> get()
        Deprecated.
        Use getList() instead
        Lists all services registered in OSGi, sorted by service ranking (either ascending or descending depending on the order given in the constructor).
        Returns:
        Collection of service instances
      • getList

        public java.util.List<T> getList()
        Lists all services registered in OSGi, sorted by service ranking (either ascending or descending depending on the order given in the constructor).
        Returns:
        List of service instances
      • iterator

        public java.util.Iterator<T> iterator()
        Iterates all services registered in OSGi, sorted by service ranking (either ascending or descending depending on the order given in the constructor).
        Specified by:
        iterator in interface java.lang.Iterable<T>
        Returns:
        Iterator with service instances.