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
update(Object) method. The Consumer service may request an
updated value from the Producer service by calling the
A Producer service and a Consumer service may be connected through multiple
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
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
producersConnected method is called.
Scope. Each Wire object can have a scope set with the
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 SummaryModifier and TypeMethodDescription
Class<?>Return the list of data types understood by the Consumer service connected to this
Wireobject.Return the last value sent through this
Wireobject.Return the wire properties for this
getScope()Return the calculated scope of this
booleanReturn true if the given name is in this
booleanReturn the connection state of this
isValid()Return the state of this
poll()Poll for an updated value.
voidUpdate the value.
isValidboolean isValid()Return the state of this
Wiremust always be disconnected before becoming invalid.
Wireobject is invalid because it has been deleted via
isConnectedboolean isConnected()Return the connection state of this
Wireis connected after the Wire Admin service receives notification that the Producer service and the Consumer service for this
Wireobject are both registered. This method will return
trueprior to notifying the Producer and Consumer services via calls to their respective
WireAdminEvent.WIRE_CONNECTEDmust be broadcast by the Wire Admin service when the
Wireobject is disconnected when either the Consumer or Producer service is unregistered or the
Wireobject is deleted.
WireAdminEvent.WIRE_DISCONNECTEDmust be broadcast by the Wire Admin service when the
trueif both the Producer and Consumer for this
Wireobject are connected to the
getFlavorsClass<?> getFlavors()Return the list of data types understood by the Consumer service connected to this
Wireobject. 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_FLAVORSservice 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
- An array containing the list of classes understood by the
Consumer service or
Wireis not connected, or the consumer did not register a
WireConstants.WIREADMIN_CONSUMER_FLAVORSproperty or the value of the property is not of type
(Object value)Update the value.
This methods is called by the Producer service to notify the Consumer service connected to this
Wireobject of an updated value.
If the properties of this
Wireobject contain a
WireConstants.WIREADMIN_FILTERproperty, then filtering is performed. If the Producer service connected to this
Wireobject 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
Wireobject 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
Wireobject must call the
Consumer.updated(Wire, Object)method with the updated value. If this
Wireobject is not connected, then the Consumer service must not be called and the value is ignored.
If the value is an
Envelopeobject, and the scope name is not permitted, then the
Wireobject must ignore this call and not transfer the object to the Consumer service.
WireAdminEvent.WIRE_TRACEmust be broadcast by the Wire Admin service after the Consumer service has been successfully called.
pollObject 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
Wireobject will call the
Producer.polled(Wire)method to obtain an updated value. If this
Wireobject is not connected, then the Producer service must not be called.
Wireobject has a scope, then this method must return an array of
Envelopeobjects. The objects returned must match the scope of this object. The
Wireobject must remove all
Envelopeobjects with a scope name that is not in the
Wireobject's scope. Thus, the list of objects returned must only contain
Envelopeobjects with a permitted scope name. If the array becomes empty,
nullmust be returned.
WireAdminEvent.WIRE_TRACEmust be broadcast by the Wire Admin service after the Producer service has been successfully called.
getLastValueObject getLastValue()Return the last value sent through this
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
Wireobject, this methods returns the last value provided by the Producer service. This value may be an
Envelopewhen 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.
- The last value passed though this
nullif no valid values have been passed or the Consumer service has no permission.
getPropertiesReturn the wire properties for this
- The properties for this
Wireobject. The returned
Dictionarymust be read only.
getScopeString getScope()Return the calculated scope of this
Wireobject. The purpose of the
Wireobject's scope is to allow a Producer and/or Consumer service to produce/consume different types over a single
Wireobject (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_CONSUMER_SCOPEwhen 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
Wireobject 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
Wireobject's scope must be
Wireobject'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
If either Consumer service or Producer service has not set a
WIREADMIN_*_SCOPEproperty, then the returned value must be
If the scope is set, the
Wireobject must enforce the scope names when
Envelopeobjects are used as a parameter to update or returned from the
Wireobject must then remove all
Envelopeobjects with a scope name that is not permitted.
- A list of permitted scope names or null if the Produce or Consumer service has set no scope names.
(String name)Return true if the given name is in this
name- The scope name
- true if the name is listed in the permitted scope names