ServiceReference
Date: 2016-06-24

org.osgi.framework

## Interface ServiceReference<S>

- Type Parameters:
    `S` - Type of Service.
  All Superinterfaces:
    java.lang.Comparable<java.lang.Object>

      @ProviderType
      public interface ServiceReference<S>
      extends java.lang.Comparable<java.lang.Object>

  A reference to a service.

  The Framework returns `ServiceReference` objects from the `BundleContext.getServiceReference` and `BundleContext.getServiceReferences` methods.

  A `ServiceReference` object may be shared between bundles and can be used to examine the properties of the service and to get the service object.

  Every service registered in the Framework has a unique `ServiceRegistration` object and may have multiple, distinct `ServiceReference` objects referring to it. `ServiceReference` objects associated with a `ServiceRegistration` object have the same `hashCode` and are considered equal (more specifically, their `equals()` method will return `true` when compared).

  If the same service object is registered multiple times, `ServiceReference` objects associated with different `ServiceRegistration` objects are not equal.

  See Also:
    `BundleContext.getServiceReference(Class)`, `BundleContext.getServiceReference(String)`, `BundleContext.getServiceReferences(Class, String)`, `BundleContext.getServiceReferences(String, String)`, `BundleContext.getService(ServiceReference)`, `BundleContext.getServiceObjects(ServiceReference)`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(java.lang.Object reference)` Compares this `ServiceReference` with the specified `ServiceReference` for order.
    `Bundle` | `getBundle()` Returns the bundle that registered the service referenced by this `ServiceReference` object.
    `java.lang.Object` | `getProperty(java.lang.String key)` Returns the property value to which the specified property key is mapped in the properties `Dictionary` object of the service referenced by this `ServiceReference` object.
    `java.lang.String[]` | `getPropertyKeys()` Returns an array of the keys in the properties `Dictionary` object of the service referenced by this `ServiceReference` object.
    `Bundle[]` | `getUsingBundles()` Returns the bundles that are using the service referenced by this `ServiceReference` object.
    `boolean` | `isAssignableTo(Bundle bundle, java.lang.String className)` Tests if the bundle that registered the service referenced by this `ServiceReference` and the specified bundle use the same source for the package of the specified class name.

- - ### Method Detail

    - #### getProperty

          java.lang.Object getProperty(java.lang.String key)

      Returns the property value to which the specified property key is mapped in the properties `Dictionary` object of the service referenced by this `ServiceReference` object.

      Property keys are case-insensitive.

      This method must continue to return property values after the service has been unregistered. This is so references to unregistered services (for example, `ServiceReference` objects stored in the log) can still be interrogated.

      Parameters:
        `key` - The property key.
      Returns:
        The property value to which the key is mapped; `null` if there is no property named after the key.

    - #### getPropertyKeys

          java.lang.String[] getPropertyKeys()

      Returns an array of the keys in the properties `Dictionary` object of the service referenced by this `ServiceReference` object.

      This method will continue to return the keys after the service has been unregistered. This is so references to unregistered services (for example, `ServiceReference` objects stored in the log) can still be interrogated.

      This method is case-preserving ; this means that every key in the returned array must have the same case as the corresponding key in the properties `Dictionary` that was passed to the `BundleContext.registerService(String[],Object,Dictionary)` or `ServiceRegistration.setProperties(Dictionary)` methods.

      Returns:
        An array of property keys.

    - #### getBundle

          Bundle getBundle()

      Returns the bundle that registered the service referenced by this `ServiceReference` object.

      This method must return `null` when the service has been unregistered. This can be used to determine if the service has been unregistered.

      Returns:
        The bundle that registered the service referenced by this `ServiceReference` object; `null` if that service has already been unregistered.
      See Also:
        `BundleContext.registerService(String[],Object,Dictionary)`

    - #### getUsingBundles

          Bundle[] getUsingBundles()

      Returns the bundles that are using the service referenced by this `ServiceReference` object. Specifically, this method returns the bundles whose usage count for that service is greater than zero.
      Returns:
        An array of bundles whose usage count for the service referenced by this `ServiceReference` object is greater than zero; `null` if no bundles are currently using that service.
      Since:
        1.1

    - #### isAssignableTo

          boolean isAssignableTo(Bundle bundle,
                               java.lang.String className)

      Tests if the bundle that registered the service referenced by this `ServiceReference` and the specified bundle use the same source for the package of the specified class name.

      This method performs the following checks:

      1. Get the package name from the specified class name.
      2. For the bundle that registered the service referenced by this `ServiceReference` (registrant bundle); find the source for the package. If no source is found then return `true` if the registrant bundle is equal to the specified bundle; otherwise return `false`.
      3. If the package source of the registrant bundle is equal to the package source of the specified bundle then return `true`; otherwise return `false`.
      Parameters:
        `bundle` - The `Bundle` object to check.
        `className` - The class name to check.
      Returns:
        `true` if the bundle which registered the service referenced by this `ServiceReference` and the specified bundle use the same source for the package of the specified class name. Otherwise `false` is returned.
      Throws:
        `java.lang.IllegalArgumentException` - If the specified `Bundle` was not created by the same framework instance as this `ServiceReference`.
      Since:
        1.3

    - #### compareTo

          int compareTo(java.lang.Object reference)

      Compares this `ServiceReference` with the specified `ServiceReference` for order.

      If this `ServiceReference` and the specified `ServiceReference` have the same `service id` they are equal. This `ServiceReference` is less than the specified `ServiceReference` if it has a lower `service ranking` and greater if it has a higher service ranking. Otherwise, if this `ServiceReference` and the specified `ServiceReference` have the same `service ranking`, this `ServiceReference` is less than the specified `ServiceReference` if it has a higher `service id` and greater if it has a lower service id.

      Specified by:
        `compareTo` in interface `java.lang.Comparable<java.lang.Object>`
      Parameters:
        `reference` - The `ServiceReference` to be compared.
      Returns:
        Returns a negative integer, zero, or a positive integer if this `ServiceReference` is less than, equal to, or greater than the specified `ServiceReference`.
      Throws:
        `java.lang.IllegalArgumentException` - If the specified `ServiceReference` was not created by the same framework instance as this `ServiceReference`.
      Since:
        1.4