Producer
Date: 2016-06-25

org.osgi.service.wireadmin

## Interface Producer

-     public interface Producer

  Data Producer, a service that can generate values to be used by `Consumer` services.

  Service objects registered under the Producer interface are expected to produce values (internally generated or from external sensors). The value can be of different types. When delivering a value to a `Wire` object, the Producer service should coerce the value to be an instance of one of the types specified by `Wire.getFlavors()`. The classes are specified in order of preference.

  When the data represented by the Producer object changes, this object should send the updated value by calling the `update` method on each of `Wire` objects passed in the most recent call to this object's `consumersConnected(Wire[])` method. These `Wire` objects will pass the value on to the associated `Consumer` service object.

  The Producer service may use the information in the `Wire` object's properties to schedule the delivery of values to the `Wire` object.

  Producer service objects must register with a `service.pid` and a `WireConstants.WIREADMIN_PRODUCER_FLAVORS` property. It is recommended that a Producer service object also registers with a `service.description` property. Producer service objects must register with a `WireConstants.WIREADMIN_PRODUCER_FILTERS` property if the Producer service will be performing filtering instead of the `Wire` object.

  If an exception is thrown by a Producer object method, a `WireAdminEvent` of type `WireAdminEvent.PRODUCER_EXCEPTION` is broadcast by the Wire Admin service.

  Security Considerations. Data producing bundles will require `ServicePermission[Producer,REGISTER]` to register a Producer service. In general, only the Wire Admin service should have `ServicePermission[Producer,GET]`. Thus only the Wire Admin service may directly call a Producer service. Care must be taken in the sharing of `Wire` objects with other bundles.

  Producer services must be registered with scope names when they can send different types of objects (composite) to the Consumer service. The Producer service should have `WirePermission` for each of these scope names.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `consumersConnected(Wire[] wires)` Update the list of `Wire` objects to which this `Producer` object is connected.
    `java.lang.Object` | `polled(Wire wire)` Return the current value of this `Producer` object.

- - ### Method Detail

    - #### polled

          java.lang.Object polled(Wire wire)

      Return the current value of this `Producer` object.

      This method is called by a `Wire` object in response to the Consumer service calling the `Wire` object's `poll` method. The Producer should coerce the value to be an instance of one of the types specified by `Wire.getFlavors()`. The types are specified in order of preference. The returned value should be as new or newer than the last value furnished by this object.

      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 `consumersConnected(Wire[])` method).

      If the Producer service returns an `Envelope` object that has an impermissible scope name, then the Wire object must ignore (or remove) the transfer.

      If the `Wire` object has a scope set, the return value must be an array of `Envelope` objects (`Envelope[]`). The `Wire` object must have removed any `Envelope` objects that have a scope name that is not in the Wire object's scope.

      Parameters:
        `wire` - The `Wire` object which is polling this service.
      Returns:
        The current value of the Producer service or `null` if the value cannot be coerced into a compatible type. Or an array of `Envelope` objects.

    - #### consumersConnected

          void consumersConnected(Wire[] wires)

      Update the list of `Wire` objects to which this `Producer` object is connected.

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

      The Wire Admin service must call this method asynchronously. This implies that implementors of a Producer service 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 Producer service is connected. May be `null` if the Producer is not currently connected to any `Wire` objects.