OSGi™ Service Platform
Release 3

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:

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

OSGi™ Service Platform
Release 3

Copyright © OSGi Alliance (2000, 2003). All Rights Reserved. Licensed under the OSGi Specification License, Version 1.0