* A Wire object connects a Producer service to a Consumer service.
* Both the Producer and Consumer services are identified by their unique
* service.pid values. The Producer and Consumer services may
* communicate with each other via Wire objects that connect them.
* The Producer service may send updated values to the Consumer service by
* calling the {@link #update}method. The Consumer service may request an
* updated value from the Producer service by calling the {@link #poll}method.
*
*
* A Producer service and a Consumer service may be connected through multiple
* Wire objects.
*
*
* Security Considerations. Wire objects are available to Producer
* and Consumer services connected to a given Wire object and to
* bundles which can access the WireAdmin service. A bundle must have
* ServicePermission[WireAdmin,GET] to get the WireAdmin
* service to access all Wire objects. A bundle registering a
* Producer service or a Consumer service must have the appropriate
* ServicePermission[Consumer|Producer,REGISTER] to register the
* service and will be passed Wire objects when the service object's
* consumersConnected or producersConnected method is
* called.
*
*
* Scope. Each Wire object can have a scope set with the setScope
* method. This method should be called by a Consumer service when it assumes a
* Producer service that is composite (supports multiple information items). The
* names in the scope must be verified by the Wire object before it
* is used in communication. The semantics of the names depend on the Producer
* service and must not be interpreted by the Wire Admin service.
*
* @version $Revision: 1.9 $
*/
public interface Wire {
/**
* Return the state of this Wire object.
*
*
* A connected Wire must always be disconnected before becoming
* invalid.
*
* @return false if this Wire object is invalid
* because it has been deleted via {@link WireAdmin#deleteWire};
* true otherwise.
*/
public boolean isValid();
/**
* Return the connection state of this Wire object.
*
*
* A Wire is connected after the Wire Admin service receives
* notification that the Producer service and the Consumer service for this
* Wire object are both registered. This method will return
* true prior to notifying the Producer and Consumer services via
* calls to their respective consumersConnected and
* producersConnected methods.
*
* A WireAdminEvent of type {@link WireAdminEvent#WIRE_CONNECTED}
* must be broadcast by the Wire Admin service when the Wire
* becomes connected.
*
*
* A Wire object is disconnected when either the Consumer or
* Producer service is unregistered or the Wire object is
* deleted.
*
* A WireAdminEvent of type
* {@link WireAdminEvent#WIRE_DISCONNECTED}must be broadcast by the Wire
* Admin service when the Wire becomes disconnected.
*
* @return true if both the Producer and Consumer for this
* Wire object are connected to the Wire
* object; false otherwise.
*/
public boolean isConnected();
/**
* Return the list of data types understood by the Consumer service
* connected to this Wire object. Note that subclasses of the
* classes in this list are acceptable data types as well.
*
*
* The list is the value of the
* {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS}service property of the
* Consumer service object connected to this object. If no such property was
* registered or the type of the property value is not Class[],
* this method must return null.
*
* @return An array containing the list of classes understood by the
* Consumer service or null if the Wire is not
* connected, or the consumer did not register a
* {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS}property or the
* value of the property is not of type Class[].
*/
public Class[] getFlavors();
/**
* Update the value.
*
*
* This methods is called by the Producer service to notify the Consumer
* service connected to this Wire object of an updated value.
*
* If the properties of this Wire object contain a
* {@link WireConstants#WIREADMIN_FILTER}property, then filtering is
* performed. If the Producer service connected to this Wire
* object was registered with the service property
* {@link WireConstants#WIREADMIN_PRODUCER_FILTERS}, the Producer service
* will perform the filtering according to the rules specified for the
* filter. Otherwise, this Wire object will perform the filtering
* of the value.
*
* If no filtering is done, or the filter indicates the updated value should
* be delivered to the Consumer service, then this Wire object
* must call the {@link Consumer#updated}method with the updated value. If
* this Wire object is not connected, then the Consumer service
* must not be called and the value is ignored.
*
* If the value is an Envelope object, and the scope name is not
* permitted, then the Wire object must ignore this call and not
* transfer the object to the Consumer service.
*
*
* A WireAdminEvent of type {@link WireAdminEvent#WIRE_TRACE}
* must be broadcast by the Wire Admin service after the Consumer service
* has been successfully called.
*
* @param value The updated value. The value should be an instance of one of
* the types returned by {@link #getFlavors}.
* @see WireConstants#WIREADMIN_FILTER
*/
public void update(Object value);
/**
* Poll for an updated value.
*
*
* This methods is normally called by the Consumer service to request an
* updated value from the Producer service connected to this Wire
* object. This Wire object will call the {@link Producer#polled}
* method to obtain an updated value. If this Wire object is not
* connected, then the Producer service must not be called.
*
*
* If this Wire object has a scope, then this method must return
* an array of Envelope objects. The objects returned must match
* the scope of this object. The Wire object must remove all
* Envelope objects with a scope name that is not in the
* Wire object's scope. Thus, the list of objects returned must
* only contain Envelope objects with a permitted scope name. If
* the array becomes empty, null must be returned.
*
*
* A WireAdminEvent of type {@link WireAdminEvent#WIRE_TRACE}
* must be broadcast by the Wire Admin service after the Producer service
* has been successfully called.
*
* @return A value whose type should be one of the types returned by
* {@link #getFlavors},Envelope[], or null
* if the Wire object is not connected, the Producer
* service threw an exception, or the Producer service returned a
* value which is not an instance of one of the types returned by
* {@link #getFlavors}.
*/
public Object poll();
/**
* Return the last value sent through this Wire object.
*
*
* The returned value is the most recent, valid value passed to the
* {@link #update}method or returned by the {@link #poll}method of this
* object. If filtering is performed by this Wire object, this
* methods returns the last value provided by the Producer service. This
* value may be an Envelope[] when the Producer service uses
* scoping. If the return value is an Envelope object (or array), it must be
* verified that the Consumer service has the proper WirePermission to see
* it.
*
* @return The last value passed though this Wire object or
* null if no valid values have been passed or the
* Consumer service has no permission.
*/
public Object getLastValue();
/**
* Return the wire properties for this Wire object.
*
* @return The properties for this Wire object. The returned
* Dictionary must be read only.
*/
public Dictionary getProperties();
/**
* Return the calculated scope of this Wire object.
*
* The purpose of the Wire object's scope is to allow a Producer
* and/or Consumer service to produce/consume different types over a single
* Wire object (this was deemed necessary for efficiency
* reasons). Both the Consumer service and the Producer service must set an
* array of scope names (their scope) with the service registration property
* WIREADMIN_PRODUCER_SCOPE, or
* WIREADMIN_CONSUMER_SCOPE when they can produce multiple types.
* If a Producer service can produce different types, it should set this
* property to the array of scope names it can produce, the Consumer service
* must set the array of scope names it can consume. The scope of a
* Wire object is defined as the intersection of permitted scope
* names of the Producer service and Consumer service.
*
* If neither the Consumer, or the Producer service registers scope names
* with its service registration, then the Wire object's scope
* must be null.
*
* The Wire object's scope must not change when a Producer or
* Consumer services modifies its scope.
*
* A scope name is permitted for a Producer service when the registering
* bundle has WirePermission[name,PRODUCE], and for a Consumer
* service when the registering bundle has WirePermission[name,CONSUME].
*
* If either Consumer service or Producer service has not set a
* WIREADMIN_*_SCOPE property, then the returned value must be
* null.
*
* If the scope is set, the Wire object must enforce the scope
* names when Envelope objects are used as a parameter to update
* or returned from the poll method. The Wire object
* must then remove all Envelope objects with a scope name that
* is not permitted.
*
* @return A list of permitted scope names or null if the Produce or
* Consumer service has set no scope names.
*/
public String[] getScope();
/**
* Return true if the given name is in this Wire object's scope.
*
* @param name The scope name
* @return true if the name is listed in the permitted scope names
*/
public boolean hasScope(String name);
}