|
OSGi™ Service Platform Release 3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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(java.lang.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[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.
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 |
public boolean isValid()
A connected Wire must always be disconnected before becoming invalid.
WireAdmin.deleteWire(org.osgi.service.wireadmin.Wire)
;
true otherwise.public boolean isConnected()
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.
public java.lang.Class[] getFlavors()
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.
WireConstants.WIREADMIN_CONSUMER_FLAVORS
property
or the value of the property is not of type Class[].public void update(java.lang.Object 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(org.osgi.service.wireadmin.Wire, java.lang.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.
value
- The updated value. The value should be an instance of
one of the types returned by getFlavors()
.WireConstants.WIREADMIN_FILTER
public java.lang.Object poll()
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(org.osgi.service.wireadmin.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.
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()
.public java.lang.Object getLastValue()
The returned value is the most recent, valid value passed to the
update(java.lang.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.
public java.util.Dictionary getProperties()
public java.lang.String[] getScope()
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.
public boolean hasScope(java.lang.String name)
name
- The scope name
|
OSGi™ Service Platform Release 3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |