* Copyright (c) OSGi Alliance (2002, 2013). All Rights Reserved.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
Service objects registered under the
Consumer interface are expected
to consume values from a Producer service via a
Wire object. A
Consumer service may poll the Producer service by calling the
method. The Consumer service will also receive an updated
value when called at it's
method. The Producer
service should have coerced the value to be an instance of one of the types
specified by the
method, or one of their
Consumer service objects must register with a
service.pid and a
property. It is recommended
that Consumer service objects also register with a
Exception is thrown by any of the
Consumer methods, a
WireAdminEvent of type
broadcast by the Wire Admin service.
Security Considerations - Data consuming bundles will require
ServicePermission[Consumer,REGISTER]. In general, only the Wire Admin
service bundle should have this permission. Thus only the Wire Admin service
may directly call a Consumer service. Care must be taken in the sharing of
Wire objects with other bundles.
Consumer services must be registered with their scope when they can receive
different types of objects from the Producer service. The Consumer service
WirePermission for each of these scope names.
Wireobject with an updated value from the Producer service.
Note: This method may be called by a
Wire object prior to this
object being notified that it is connected to that
When the Consumer service can receive
Envelope objects, it must
have registered all scope names together with the service object, and
each of those names must be permitted by the bundle's
WirePermission. If an
Envelope object is delivered with
updated method, then the Consumer service should assume that
the security check has been performed.
Wireobject which is delivering the updated value.
valueThe updated value. The value should be an instance of one of the types specified by the
Wireobjects to which this Consumer service is connected.
This method is called when the Consumer service is first registered and
subsequently whenever a
Wire associated with this Consumer
service becomes connected, is modified or becomes disconnected.
The Wire Admin service must call this method asynchronously. This implies that implementors of Consumer can be assured that the callback will not take place during registration when they execute the registration in a synchronized method.
wiresAn array of the current and complete list of
Wireobjects to which this Consumer service is connected. May be
nullif the Consumer service is not currently connected to any