org.osgi.service.wireadmin.Producer Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2002, 2008). 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
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* 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.
*/
package org.osgi.service.wireadmin;
/**
* Data Producer, a service that can generate values to be used by
* {@link Consumer} services.
*
*
* Service objects registered under the Producer interface are expected to
* produce values (internally generated or from external sensors). The value can
* be of different types. When delivering a value to a Wire object,
* the Producer service should coerce the value to be an instance of one of the
* types specified by {@link Wire#getFlavors}. The classes are specified in
* order of preference.
*
*
* When the data represented by the Producer object changes, this object should
* send the updated value by calling the update method on each of
* Wire objects passed in the most recent call to this object's
* {@link #consumersConnected} method. These Wire objects will pass
* the value on to the associated Consumer service object.
*
*
* The Producer service may use the information in the Wire object's
* properties to schedule the delivery of values to the Wire object.
*
*
* Producer service objects must register with a service.pid and a
* {@link WireConstants#WIREADMIN_PRODUCER_FLAVORS} property. It is recommended
* that a Producer service object also registers with a
* service.description property. Producer service objects must
* register with a {@link WireConstants#WIREADMIN_PRODUCER_FILTERS} property if
* the Producer service will be performing filtering instead of the
* Wire object.
*
*
* If an exception is thrown by a Producer object method, a
* WireAdminEvent of type {@link WireAdminEvent#PRODUCER_EXCEPTION}
* is broadcast by the Wire Admin service.
*
*
* Security Considerations. Data producing bundles will require
* ServicePermission[Producer,REGISTER] to register a Producer
* service. In general, only the Wire Admin service should have
* ServicePermission[Producer,GET]. Thus only the Wire Admin service
* may directly call a Producer service. Care must be taken in the sharing of
* Wire objects with other bundles.
*
* Producer services must be registered with scope names when they can send
* different types of objects (composite) to the Consumer service. The Producer
* service should have WirePermission for each of these scope names.
*
* @version $Revision: 5673 $
*/
public interface Producer {
/**
* Return the current value of this Producer object.
*
*
* This method is called by a Wire object in response to the
* Consumer service calling the Wire object's poll
* method. The Producer should coerce the value to be an instance of one of
* the types specified by {@link Wire#getFlavors}. The types are specified
* in order of of preference. The returned value should be as new or newer
* than the last value furnished by this object.
*
*
* Note: This method may be called by a Wire object prior to this
* object being notified that it is connected to that Wire object
* (via the {@link #consumersConnected} method).
*
* If the Producer service returns an Envelope object that has an
* unpermitted scope name, then the Wire object must ignore (or remove) the
* transfer.
*
* If the Wire object has a scope set, the return value must be
* an array of Envelope objects (Envelope[]). The
* Wire object must have removed any Envelope objects
* that have a scope name that is not in the Wire object's scope.
*
* @param wire The Wire object which is polling this service.
* @return The current value of the Producer service or null if
* the value cannot be coerced into a compatible type. Or an array
* of Envelope objects.
*/
public Object polled(Wire wire);
/**
* Update the list of Wire objects to which this
* Producer object is connected.
*
*
* This method is called when the Producer service is first registered and
* subsequently whenever a Wire associated with this Producer
* becomes connected, is modified or becomes disconnected.
*
*
* The Wire Admin service must call this method asynchronously. This implies
* that implementors of a Producer service can be assured that the callback
* will not take place during registration when they execute the
* registration in a synchronized method.
*
* @param wires An array of the current and complete list of Wire
* objects to which this Producer service is connected. May be
* null if the Producer is not currently connected to any
* Wire objects.
*/
public void consumersConnected(Wire[] wires);
}