ServiceRegistration
Date: 2016-06-24

org.osgi.framework

## Interface ServiceRegistration<S>

- Type Parameters:
    `S` - Type of Service.

      @ProviderType
      public interface ServiceRegistration<S>

  A registered service.

  The Framework returns a `ServiceRegistration` object when a `BundleContext.registerService` method invocation is successful. The `ServiceRegistration` object is for the private use of the registering bundle and should not be shared with other bundles.

  The `ServiceRegistration` object may be used to update the properties of the service or to unregister the service.

  See Also:
    `BundleContext.registerService(String[],Object,Dictionary)`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ServiceReference<S>` | `getReference()` Returns a `ServiceReference` object for a service being registered.
    `void` | `setProperties(java.util.Dictionary<java.lang.String,?> properties)` Updates the properties associated with a service.
    `void` | `unregister()` Unregisters a service.

- - ### Method Detail

    - #### getReference

          ServiceReference<S> getReference()

      Returns a `ServiceReference` object for a service being registered.

      The `ServiceReference` object may be shared with other bundles.

      Returns:
        `ServiceReference` object.
      Throws:
        `java.lang.IllegalStateException` - If this `ServiceRegistration` object has already been unregistered.

    - #### setProperties

          void setProperties(java.util.Dictionary<java.lang.String,?> properties)

      Updates the properties associated with a service.

      The `Constants.OBJECTCLASS`, `Constants.SERVICE_BUNDLEID`, `Constants.SERVICE_ID` and `Constants.SERVICE_SCOPE` keys cannot be modified by this method. These values are set by the Framework when the service is registered in the OSGi environment.

      The following steps are required to modify service properties:

      1. The service's properties are replaced with the provided properties.
      2. A service event of type `ServiceEvent.MODIFIED` is fired.
      Parameters:
        `properties` - The properties for this service. See `Constants` for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties this method should be called again.
      Throws:
        `java.lang.IllegalStateException` - If this `ServiceRegistration` object has already been unregistered.
        `java.lang.IllegalArgumentException` - If `properties` contains case variants of the same key name.

    - #### unregister

          void unregister()

      Unregisters a service. Remove a `ServiceRegistration` object from the Framework service registry. All `ServiceReference` objects associated with this `ServiceRegistration` object can no longer be used to interact with the service once unregistration is complete.

      The following steps are required to unregister a service:

      1. The service is removed from the Framework service registry so that it can no longer be obtained.
      2. A service event of type `ServiceEvent.UNREGISTERING` is fired so that bundles using this service can release their use of the service. Once delivery of the service event is complete, the `ServiceReference` objects for the service may no longer be used to get a service object for the service.
      3. For each bundle whose use count for this service is greater than zero:
         - The bundle's use count for this service is set to zero.
         - If the service was registered with a `ServiceFactory` object, the `ServiceFactory.ungetService` method is called to release the service object for the bundle.
      Throws:
        `java.lang.IllegalStateException` - If this `ServiceRegistration` object has already been unregistered.
      See Also:
        `BundleContext.ungetService(ServiceReference)`, `ServiceFactory.ungetService(Bundle, ServiceRegistration, Object)`