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[GET,WireAdmin] 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[REGISTER,Consumer|Producer] 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.1.1.1 $ * @author Open Services Gateway Initiative */ 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[PRODUCE], and for a Consumer service when * the registering bundle has WirePermission[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 ); }