Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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[GET,WireAdmin]` to get the Wire Admin service to create, modify, find, and delete `Wire` objects.

Method Summary
`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

    public 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(org.osgi.service.wireadmin.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 type of the value of the property must be one of the following:

       type        = basetype
        | vector | arrays

       basetype = String | Integer | Long
        | Float | Double | Byte
        | Short | Character
        | Boolean

       primitive   = long | int | short
        | char | byte | double | float

       arrays   = primitive '[]' | basetype '[]'

       vector   = Vector of basetype

  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(java.lang.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 case variants of the same key name.

### deleteWire

    public 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

    public 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(org.osgi.service.wireadmin.Wire[])` and `Producer.consumersConnected(org.osgi.service.wireadmin.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.

### getWires

    public Wire[] getWires(java.lang.String filter)
                    throws 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:
    `InvalidSyntaxException` - If the specified `filter` has an invalid syntax.
  See Also:
    `Filter`

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.