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.

"Consumers of this API must not implement this interface"

Method Summary

Modifier and Type	Method and Description
Wire	createWire(java.lang.String producerPID, java.lang.String consumerPID, java.util.Dictionary<java.lang.String,?> 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<java.lang.String,?> properties) Update the properties of a Wire object.

Method Detail

createWire

Wire createWire(java.lang.String producerPID,
                java.lang.String consumerPID,
                java.util.Dictionary<java.lang.String,?> 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<java.lang.String,?> 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 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