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. * * @version $Revision: 1.1.1.1 $ * @author Open Services Gateway Initiative */ 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 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: *
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 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. */ 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; }