org.osgi.service.wireadmin
Interface Wire

public interface Wire

A connection between a Producer service and a Consumer service.

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 update(Object) method. The Consumer service may request an updated value from the Producer service by calling the 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.

Consumers of this API must not implement this interface

Method Summary

java.lang.Class[]	getFlavors() Return the list of data types understood by the Consumer service connected to this Wire object.
java.lang.Object	getLastValue() Return the last value sent through this Wire object.
java.util.Dictionary	getProperties() Return the wire properties for this Wire object.
java.lang.String[]	getScope() Return the calculated scope of this Wire object.
boolean	hasScope(java.lang.String name) Return true if the given name is in this Wire object's scope.
boolean	isConnected() Return the connection state of this Wire object.
boolean	isValid() Return the state of this Wire object.
java.lang.Object	poll() Poll for an updated value.
void	update(java.lang.Object value) Update the value.

Method Detail

isValid

boolean isValid()

Return the state of this Wire object.

A connected Wire must always be disconnected before becoming invalid.

Returns:

false if this Wire object is invalid because it has been deleted via WireAdmin.deleteWire(Wire); true otherwise.

isConnected

boolean isConnected()

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 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 WireAdminEvent.WIRE_DISCONNECTED must be broadcast by the Wire Admin service when the Wire becomes disconnected.

Returns:

true if both the Producer and Consumer for this Wire object are connected to the Wire object; false otherwise.

getFlavors

java.lang.Class[] getFlavors()

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 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.

Returns:

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 WireConstants.WIREADMIN_CONSUMER_FLAVORS property or the value of the property is not of type Class[].

update

void update(java.lang.Object value)

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 WireConstants.WIREADMIN_FILTER property, then filtering is performed. If the Producer service connected to this Wire object was registered with the service property 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 Consumer.updated(Wire, Object) 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 WireAdminEvent.WIRE_TRACE must be broadcast by the Wire Admin service after the Consumer service has been successfully called.

Parameters:

value - The updated value. The value should be an instance of one of the types returned by getFlavors().

See Also:

WireConstants.WIREADMIN_FILTER

poll

java.lang.Object poll()

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 Producer.polled(Wire) 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 WireAdminEvent.WIRE_TRACE must be broadcast by the Wire Admin service after the Producer service has been successfully called.

Returns:

A value whose type should be one of the types returned by 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 getFlavors().

getLastValue

java.lang.Object getLastValue()

Return the last value sent through this Wire object.

The returned value is the most recent, valid value passed to the update(Object) method or returned by the 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.

Returns:

The last value passed though this Wire object or null if no valid values have been passed or the Consumer service has no permission.

getProperties

java.util.Dictionary getProperties()

Return the wire properties for this Wire object.

Returns:

The properties for this Wire object. The returned Dictionary must be read only.

getScope

java.lang.String[] getScope()

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.

Returns:

A list of permitted scope names or null if the Produce or Consumer service has set no scope names.

hasScope

boolean hasScope(java.lang.String name)

Return true if the given name is in this Wire object's scope.

Parameters:

name - The scope name

Returns:

true if the name is listed in the permitted scope names