Wire
Date: 2016-06-25

org.osgi.service.wireadmin

## Interface Wire

-     public interface Wire

  A connection between a Producer service and a Consumer service.

  A `Wire` object connects a Producer service to a Consumer service. Both the Producer and Consumer services are identified by their unique `service.pid` values. The Producer and Consumer services may communicate with each other via `Wire` objects that connect them. The Producer service may send updated values to the Consumer service by calling the `update(Object)` method. The Consumer service may request an updated value from the Producer service by calling the `poll()` method.

  A Producer service and a Consumer service may be connected through multiple `Wire` objects.

  Security Considerations. `Wire` objects are available to Producer and Consumer services connected to a given `Wire` object and to bundles which can access the `WireAdmin` service. A bundle must have `ServicePermission[WireAdmin,GET]` to get the `WireAdmin` service to access all `Wire` objects. A bundle registering a Producer service or a Consumer service must have the appropriate `ServicePermission[Consumer|Producer,REGISTER]` to register the service and will be passed `Wire` objects when the service object's `consumersConnected` or `producersConnected` method is called.

  Scope. Each Wire object can have a scope set with the `setScope` method. This method should be called by a Consumer service when it assumes a Producer service that is composite (supports multiple information items). The names in the scope must be verified by the `Wire` object before it is used in communication. The semantics of the names depend on the Producer service and must not be interpreted by the Wire Admin service.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Class[]` | `getFlavors()` Return the list of data types understood by the Consumer service connected to this `Wire` object.
    `java.lang.Object` | `getLastValue()` Return the last value sent through this `Wire` object.
    `java.util.Dictionary` | `getProperties()` Return the wire properties for this `Wire` object.
    `java.lang.String[]` | `getScope()` Return the calculated scope of this `Wire` object.
    `boolean` | `hasScope(java.lang.String name)` Return true if the given name is in this `Wire` object's scope.
    `boolean` | `isConnected()` Return the connection state of this `Wire` object.
    `boolean` | `isValid()` Return the state of this `Wire` object.
    `java.lang.Object` | `poll()` Poll for an updated value.
    `void` | `update(java.lang.Object value)` Update the value.

- - ### Method Detail

    - #### isValid

          boolean isValid()

      Return the state of this `Wire` object.

      A connected `Wire` must always be disconnected before becoming invalid.

      Returns:
        `false` if this `Wire` object is invalid because it has been deleted via `WireAdmin.deleteWire(Wire)`; `true` otherwise.

    - #### isConnected

          boolean isConnected()

      Return the connection state of this `Wire` object.

      A `Wire` is connected after the Wire Admin service receives notification that the Producer service and the Consumer service for this `Wire` object are both registered. This method will return `true` prior to notifying the Producer and Consumer services via calls to their respective `consumersConnected` and `producersConnected` methods.

      A `WireAdminEvent` of type `WireAdminEvent.WIRE_CONNECTED` must be broadcast by the Wire Admin service when the `Wire` becomes connected.

      A `Wire` object is disconnected when either the Consumer or Producer service is unregistered or the `Wire` object is deleted.

      A `WireAdminEvent` of type `WireAdminEvent.WIRE_DISCONNECTED` must be broadcast by the Wire Admin service when the `Wire` becomes disconnected.

      Returns:
        `true` if both the Producer and Consumer for this `Wire` object are connected to the `Wire` object; `false` otherwise.

    - #### getFlavors

          java.lang.Class[] getFlavors()

      Return the list of data types understood by the Consumer service connected to this `Wire` object. Note that subclasses of the classes in this list are acceptable data types as well.

      The list is the value of the `WireConstants.WIREADMIN_CONSUMER_FLAVORS` service property of the Consumer service object connected to this object. If no such property was registered or the type of the property value is not `Class[]`, this method must return `null`.

      Returns:
        An array containing the list of classes understood by the Consumer service or `null` if the `Wire` is not connected, or the consumer did not register a `WireConstants.WIREADMIN_CONSUMER_FLAVORS` property or the value of the property is not of type `Class[]`.

    - #### update

          void update(java.lang.Object value)

      Update the value.

      This methods is called by the Producer service to notify the Consumer service connected to this `Wire` object of an updated value.

      If the properties of this `Wire` object contain a `WireConstants.WIREADMIN_FILTER` property, then filtering is performed. If the Producer service connected to this `Wire` object was registered with the service property `WireConstants.WIREADMIN_PRODUCER_FILTERS`, the Producer service will perform the filtering according to the rules specified for the filter. Otherwise, this `Wire` object will perform the filtering of the value.

      If no filtering is done, or the filter indicates the updated value should be delivered to the Consumer service, then this `Wire` object must call the `Consumer.updated(Wire, Object)` method with the updated value. If this `Wire` object is not connected, then the Consumer service must not be called and the value is ignored.

      If the value is an `Envelope` object, and the scope name is not permitted, then the `Wire` object must ignore this call and not transfer the object to the Consumer service.

      A `WireAdminEvent` of type `WireAdminEvent.WIRE_TRACE` must be broadcast by the Wire Admin service after the Consumer service has been successfully called.

      Parameters:
        `value` - The updated value. The value should be an instance of one of the types returned by `getFlavors()`.
      See Also:
        `WireConstants.WIREADMIN_FILTER`

    - #### poll

          java.lang.Object poll()

      Poll for an updated value.

      This methods is normally called by the Consumer service to request an updated value from the Producer service connected to this `Wire` object. This `Wire` object will call the `Producer.polled(Wire)` method to obtain an updated value. If this `Wire` object is not connected, then the Producer service must not be called.

      If this `Wire` object has a scope, then this method must return an array of `Envelope` objects. The objects returned must match the scope of this object. The `Wire` object must remove all `Envelope` objects with a scope name that is not in the `Wire` object's scope. Thus, the list of objects returned must only contain `Envelope` objects with a permitted scope name. If the array becomes empty, `null` must be returned.

      A `WireAdminEvent` of type `WireAdminEvent.WIRE_TRACE` must be broadcast by the Wire Admin service after the Producer service has been successfully called.

      Returns:
        A value whose type should be one of the types returned by `getFlavors()`,`Envelope[]`, or `null` if the `Wire` object is not connected, the Producer service threw an exception, or the Producer service returned a value which is not an instance of one of the types returned by `getFlavors()`.

    - #### getLastValue

          java.lang.Object getLastValue()

      Return the last value sent through this `Wire` object.

      The returned value is the most recent, valid value passed to the `update(Object)` method or returned by the `poll()` method of this object. If filtering is performed by this `Wire` object, this methods returns the last value provided by the Producer service. This value may be an `Envelope[]` when the Producer service uses scoping. If the return value is an Envelope object (or array), it must be verified that the Consumer service has the proper WirePermission to see it.

      Returns:
        The last value passed though this `Wire` object or `null` if no valid values have been passed or the Consumer service has no permission.

    - #### getProperties

          java.util.Dictionary getProperties()

      Return the wire properties for this `Wire` object.
      Returns:
        The properties for this `Wire` object. The returned `Dictionary` must be read only.

    - #### getScope

          java.lang.String[] getScope()

      Return the calculated scope of this `Wire` object. The purpose of the `Wire` object's scope is to allow a Producer and/or Consumer service to produce/consume different types over a single `Wire` object (this was deemed necessary for efficiency reasons). Both the Consumer service and the Producer service must set an array of scope names (their scope) with the service registration property `WIREADMIN_PRODUCER_SCOPE`, or `WIREADMIN_CONSUMER_SCOPE` when they can produce multiple types. If a Producer service can produce different types, it should set this property to the array of scope names it can produce, the Consumer service must set the array of scope names it can consume. The scope of a `Wire` object is defined as the intersection of permitted scope names of the Producer service and Consumer service.

      If neither the Consumer, or the Producer service registers scope names with its service registration, then the `Wire` object's scope must be `null`.

      The `Wire` object's scope must not change when a Producer or Consumer services modifies its scope.

      A scope name is permitted for a Producer service when the registering bundle has `WirePermission[name,PRODUCE]`, and for a Consumer service when the registering bundle has `WirePermission[name,CONSUME]`.

      If either Consumer service or Producer service has not set a `WIREADMIN_*_SCOPE` property, then the returned value must be `null`.

      If the scope is set, the `Wire` object must enforce the scope names when `Envelope` objects are used as a parameter to update or returned from the `poll` method. The `Wire` object must then remove all `Envelope` objects with a scope name that is not permitted.

      Returns:
        A list of permitted scope names or null if the Produce or Consumer service has set no scope names.

    - #### hasScope

          boolean hasScope(java.lang.String name)

      Return true if the given name is in this `Wire` object's scope.
      Parameters:
        `name` - The scope name
      Returns:
        true if the name is listed in the permitted scope names