org.osgi.framework

## Interface ServiceReference<S>

Type Parameters:
  `S` - Type of Service.

All Superinterfaces:
  Comparable<Object>

    @ProviderType
    public interface ServiceReference<S>
    extends Comparable<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.

Author:
  $Id: 1454244c30992b7a52ac3838b03bc584c3495816 $
See Also:
  `BundleContext.getServiceReference(Class)`, `BundleContext.getServiceReference(String)`, `BundleContext.getServiceReferences(Class, String)`, `BundleContext.getServiceReferences(String, String)`, `BundleContext.getService(ServiceReference)`, `BundleContext.getServiceObjects(ServiceReference)`

### Method Summary

All Methods Instance Methods Abstract Methods
`int` `compareTo(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.
`Dictionary<String,Object>` `getProperties()` Returns a copy of the properties of the service referenced by this `ServiceReference` object.
`Object` `getProperty(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.
`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, 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

    Object getProperty(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

    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,
                           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:
  `IllegalArgumentException` - If the specified `Bundle` was not created by the same framework instance as this `ServiceReference`.
Since:
  1.3

#### compareTo

    int compareTo(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 `Comparable<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:
  `IllegalArgumentException` - If the specified `ServiceReference` was not created by the same framework instance as this `ServiceReference`.
Since:
  1.4

#### getProperties

    Dictionary<String,Object> getProperties()

Returns a copy of the properties of the service referenced by this `ServiceReference` object.

This method will continue to return the properties 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.

The returned `Dictionary` object:

- Must map property values by using property keys in a case-insensitive manner.
- Must return property keys is a case-preserving manner. This means that the keys 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.
- Is the property of the caller and can be modified by the caller but any changes are not reflected in the properties of the service. `ServiceRegistration.setProperties(Dictionary)` must be called to modify the properties of the service.

Returns:
  A copy of the properties of the service referenced by this `ServiceReference` object
Since:
  1.9