* 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.
*
* @version $Revision: 1.9 $
*/
public interface WireAdmin {
/**
* 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 {@link #deleteWire}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:
*
Wire object's persistent identity (PID). This value is
* generated by the Wire Admin service when a Wire object is
* created.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
* {@link WireAdminEvent#WIRE_CREATED}after the new Wire object
* becomes available from {@link #getWires}.
*
* @param producerPID The service.pid of the Producer service to
* be connected to the Wire object.
* @param consumerPID The service.pid of the Consumer service to
* be connected to the Wire object.
* @param properties The Wire object's properties. This argument
* may be null if the caller does not wish to define any
* Wire object's properties.
* @return The Wire object for this connection.
*
* @throws java.lang.IllegalArgumentException If properties
* contains invalid wire types or case variants of the same key
* name.
*/
public Wire createWire(String producerPID, String consumerPID,
Dictionary properties);
/**
* 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 {@link Wire#isValid}will return
* false after it is deleted.
*
*
* The Wire Admin service must broadcast a WireAdminEvent of type
* {@link WireAdminEvent#WIRE_DELETED}after the Wire object
* becomes invalid.
*
* @param wire The Wire object which is to be deleted.
*/
public void deleteWire(Wire wire);
/**
* 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
* {@link Consumer#producersConnected}and
* {@link Producer#consumersConnected}methods.
*
*
* The Wire Admin service must broadcast a WireAdminEvent of type
* {@link WireAdminEvent#WIRE_UPDATED}after the updated properties are
* available from the Wire object.
*
* @param wire The Wire object which is to be updated.
* @param 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.
*/
public void updateWire(Wire wire, Dictionary properties);
/**
* 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 {@link WireConstants#WIREADMIN_PRODUCER_PID},
* {@link WireConstants#WIREADMIN_CONSUMER_PID}and
* {@link WireConstants#WIREADMIN_PID}.
*
* @param filter Filter string to select Wire objects or
* null to select all Wire objects.
* @return 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 org.osgi.framework.Filter
*/
public Wire[] getWires(String filter) throws InvalidSyntaxException;
}