org.apache.sling.commons.osgi

## Class RankedServices<T>

- java.lang.Object
- - org.apache.sling.commons.osgi.RankedServices<T>

Type Parameters:
  `T` - Service type

All Implemented Interfaces:
  Iterable<T>

    @ProviderType
    public final class RankedServices<T>
    extends Object
    implements 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"

### Nested Class Summary

Nested Classes
`static interface` `RankedServices.ChangeListener` Notification for changes on services list.

### Constructor Summary

Constructors
Constructor and Description
`RankedServices()` Deprecated. Use `RankedServices(Order)` to explicitly give the order.
`RankedServices(Order order)` Instantiate without change listener but with a given order.
`RankedServices(Order order, RankedServices.ChangeListener changeListener)` Instantiate with change listener.
`RankedServices(RankedServices.ChangeListener changeListener)` Deprecated. Use `RankedServices(Order order, ChangeListener changeListener)` instead

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`void` `bind(T service, Map<String,Object> props)` Handle bind service event.
`Collection<T>` `get()` Deprecated. Use `getList()` instead
`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).
`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).
`void` `unbind(T service, Map<String,Object> props)` Handle unbind service event.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

### Constructor Detail

#### RankedServices

    @Deprecated
    public RankedServices()

Deprecated. Use `RankedServices(Order)` to explicitly give the order.
Instantiate without change listener in ascending order (lowest service ranking first).

#### RankedServices

    @Deprecated
    public RankedServices(RankedServices.ChangeListener changeListener)

Deprecated. Use `RankedServices(Order order, ChangeListener changeListener)` instead
Instantiate with change listener in ascending order (lowest service ranking first).

Parameters:
  `changeListener` - Change listener

#### RankedServices

    public RankedServices(Order order)

Instantiate without change listener but with a given order.

Parameters:
  `order` - the order in which the services should be returned in `iterator()` and `get()`. Either `Order.ASCENDING` or `Order.DESCENDING`. Use `Order.DESCENDING` if you want to have the service with the highest ranking returned first (this is the service which would also be chosen by `BundleContext.getServiceReference(String)`).
Since:
  2.4

#### RankedServices

    public RankedServices(Order order,
                          RankedServices.ChangeListener changeListener)

Instantiate with change listener.

Parameters:
  `order` - the order in which the services should be returned in `iterator()` and `get()`. Either `Order.ASCENDING` or `Order.DESCENDING`. Use `Order.DESCENDING` if you want to have the service with the highest ranking returned first (this is the service which would also be chosen by `BundleContext.getServiceReference(String)`).
  `changeListener` - Change listener
Since:
  2.4

### Method Detail

#### bind

    public void bind(T service,
                     Map<String,Object> props)

Handle bind service event.

Parameters:
  `service` - Service instance
  `props` - Service reference properties

#### unbind

    public void unbind(T service,
                       Map<String,Object> props)

Handle unbind service event.

Parameters:
  `service` - Service instance
  `props` - Service reference properties

#### get

    public 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 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 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 `Iterable<T>`
Returns:
  Iterator with service instances.