WireAdmin
Date: 2016-06-25

org.osgi.service.wireadmin

## Interface WireAdmin

-     public interface WireAdmin

  Wire Administration service.

  This service can be used to create `Wire` objects connecting a Producer service and a Consumer service. `Wire` objects also have wire properties that may be specified when a `Wire` object is created. The Producer and Consumer services may use the `Wire` object's properties to manage or control their interaction. The use of `Wire` object's properties by a Producer or Consumer services is optional.

  Security Considerations. A bundle must have `ServicePermission[WireAdmin,GET]` to get the Wire Admin service to create, modify, find, and delete `Wire` objects.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Wire` | `createWire(java.lang.String producerPID, java.lang.String consumerPID, java.util.Dictionary properties)` Create a new `Wire` object that connects a Producer service to a Consumer service.
    `void` | `deleteWire(Wire wire)` Delete a `Wire` object.
    `Wire[]` | `getWires(java.lang.String filter)` Return the `Wire` objects that match the given `filter`.
    `void` | `updateWire(Wire wire, java.util.Dictionary properties)` Update the properties of a `Wire` object.

- - ### Method Detail

    - #### createWire

          Wire createWire(java.lang.String producerPID,
                        java.lang.String consumerPID,
                        java.util.Dictionary properties)

      Create a new `Wire` object that connects a Producer service to a Consumer service. The Producer service and Consumer service do not have to be registered when the `Wire` object is created.

      The `Wire` configuration data must be persistently stored. All `Wire` connections are reestablished when the `WireAdmin` service is registered. A `Wire` can be permanently removed by using the `deleteWire(Wire)` method.

      The `Wire` object's properties must have case insensitive `String` objects as keys (like the Framework). However, the case of the key must be preserved.

      The `WireAdmin` service must automatically add the following `Wire` properties:

      - `WireConstants.WIREADMIN_PID` set to the value of the `Wire` object's persistent identity (PID). This value is generated by the Wire Admin service when a `Wire` object is created.
      - `WireConstants.WIREADMIN_PRODUCER_PID` set to the value of Producer service's PID.
      - `WireConstants.WIREADMIN_CONSUMER_PID` set to the value of Consumer service's PID.
      If the `properties` argument already contains any of these keys, then the supplied values are replaced with the values assigned by the Wire Admin service.

      The Wire Admin service must broadcast a `WireAdminEvent` of type `WireAdminEvent.WIRE_CREATED` after the new `Wire` object becomes available from `getWires(String)`.

      Parameters:
        `producerPID` - The `service.pid` of the Producer service to be connected to the `Wire` object.
        `consumerPID` - The `service.pid` of the Consumer service to be connected to the `Wire` object.
        `properties` - The `Wire` object's properties. This argument may be `null` if the caller does not wish to define any `Wire` object's properties.
      Returns:
        The `Wire` object for this connection.
      Throws:
        `java.lang.IllegalArgumentException` - If `properties` contains invalid wire types or case variants of the same key name.

    - #### deleteWire

          void deleteWire(Wire wire)

      Delete a `Wire` object.

      The `Wire` object representing a connection between a Producer service and a Consumer service must be removed. The persistently stored configuration data for the `Wire` object must destroyed. The `Wire` object's method `Wire.isValid()` will return `false` after it is deleted.

      The Wire Admin service must broadcast a `WireAdminEvent` of type `WireAdminEvent.WIRE_DELETED` after the `Wire` object becomes invalid.

      Parameters:
        `wire` - The `Wire` object which is to be deleted.

    - #### updateWire

          void updateWire(Wire wire,
                        java.util.Dictionary properties)

      Update the properties of a `Wire` object. The persistently stored configuration data for the `Wire` object is updated with the new properties and then the Consumer and Producer services will be called at the respective `Consumer.producersConnected(Wire[])` and `Producer.consumersConnected(Wire[])` methods.

      The Wire Admin service must broadcast a `WireAdminEvent` of type `WireAdminEvent.WIRE_UPDATED` after the updated properties are available from the `Wire` object.

      Parameters:
        `wire` - The `Wire` object which is to be updated.
        `properties` - The new `Wire` object's properties or `null` if no properties are required.
      Throws:
        `java.lang.IllegalArgumentException` - If `properties` contains invalid wire types or case variants of the same key name.

    - #### getWires

          Wire[] getWires(java.lang.String filter)
                          throws org.osgi.framework.InvalidSyntaxException

      Return the `Wire` objects that match the given `filter`.

      The list of available `Wire` objects is matched against the specified `filter`.`Wire` objects which match the `filter` must be returned. These `Wire` objects are not necessarily connected. The Wire Admin service should not return invalid `Wire` objects, but it is possible that a `Wire` object is deleted after it was placed in the list.

      The filter matches against the `Wire` object's properties including `WireConstants.WIREADMIN_PRODUCER_PID`, `WireConstants.WIREADMIN_CONSUMER_PID` and `WireConstants.WIREADMIN_PID`.

      Parameters:
        `filter` - Filter string to select `Wire` objects or `null` to select all `Wire` objects.
      Returns:
        An array of `Wire` objects which match the `filter` or `null` if no `Wire` objects match the `filter`.
      Throws:
        `org.osgi.framework.InvalidSyntaxException` - If the specified `filter` has an invalid syntax.
      See Also:
        `Filter`