Consumer
Date: 2016-06-25

org.osgi.service.wireadmin

## Interface Consumer

-     public interface Consumer

  Data Consumer, a service that can receive updated values from `Producer` services.

  Service objects registered under the `Consumer` interface are expected to consume values from a Producer service via a `Wire` object. A Consumer service may poll the Producer service by calling the `Wire.poll()` method. The Consumer service will also receive an updated value when called at it's `updated(Wire, Object)` method. The Producer service should have coerced the value to be an instance of one of the types specified by the `Wire.getFlavors()` method, or one of their subclasses.

  Consumer service objects must register with a `service.pid` and a `WireConstants.WIREADMIN_CONSUMER_FLAVORS` property. It is recommended that Consumer service objects also register with a `service.description` property.

  If an `Exception` is thrown by any of the `Consumer` methods, a `WireAdminEvent` of type `WireAdminEvent.CONSUMER_EXCEPTION` is broadcast by the Wire Admin service.

  Security Considerations - Data consuming bundles will require `ServicePermission[Consumer,REGISTER]`. In general, only the Wire Admin service bundle should have this permission. Thus only the Wire Admin service may directly call a Consumer service. Care must be taken in the sharing of `Wire` objects with other bundles.

  Consumer services must be registered with their scope when they can receive different types of objects from the Producer service. The Consumer service should have `WirePermission` for each of these scope names.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `producersConnected(Wire[] wires)` Update the list of `Wire` objects to which this Consumer service is connected.
    `void` | `updated(Wire wire, java.lang.Object value)` Update the value.

- - ### Method Detail

    - #### updated

          void updated(Wire wire,
                     java.lang.Object value)

      Update the value. This Consumer service is called by the `Wire` object with an updated value from the Producer service.

      Note: This method may be called by a `Wire` object prior to this object being notified that it is connected to that `Wire` object (via the `producersConnected(Wire[])` method).

      When the Consumer service can receive `Envelope` objects, it must have registered all scope names together with the service object, and each of those names must be permitted by the bundle's `WirePermission`. If an `Envelope` object is delivered with the `updated` method, then the Consumer service should assume that the security check has been performed.

      Parameters:
        `wire` - The `Wire` object which is delivering the updated value.
        `value` - The updated value. The value should be an instance of one of the types specified by the `Wire.getFlavors()` method.

    - #### producersConnected

          void producersConnected(Wire[] wires)

      Update the list of `Wire` objects to which this Consumer service is connected.

      This method is called when the Consumer service is first registered and subsequently whenever a `Wire` associated with this Consumer service becomes connected, is modified or becomes disconnected.

      The Wire Admin service must call this method asynchronously. This implies that implementors of Consumer can be assured that the callback will not take place during registration when they execute the registration in a synchronized method.

      Parameters:
        `wires` - An array of the current and complete list of `Wire` objects to which this Consumer service is connected. May be `null` if the Consumer service is not currently connected to any `Wire` objects.