bundles/org.eclipse.osgi.services/src/org/osgi/service/wireadmin/Producer.java

/*
 * Copyright (c) OSGi Alliance (2002, 2015). 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.
 * 
 * <p>
 * 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 {@code 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.
 * 
 * <p>
 * When the data represented by the Producer object changes, this object should
 * send the updated value by calling the {@code update} method on each of
 * {@code Wire} objects passed in the most recent call to this object's
 * {@link #consumersConnected(Wire[])} method. These {@code Wire} objects will
 * pass the value on to the associated {@code Consumer} service object.
 * 
 * <p>
 * The Producer service may use the information in the {@code Wire} object's
 * properties to schedule the delivery of values to the {@code Wire} object.
 * 
 * <p>
 * Producer service objects must register with a {@code service.pid} and a
 * {@link WireConstants#WIREADMIN_PRODUCER_FLAVORS} property. It is recommended
 * that a Producer service object also registers with a
 * {@code 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 {@code Wire}
 * object.
 * 
 * <p>
 * If an exception is thrown by a Producer object method, a
 * {@code WireAdminEvent} of type {@link WireAdminEvent#PRODUCER_EXCEPTION} is
 * broadcast by the Wire Admin service.
 * 
 * <p>
 * Security Considerations. Data producing bundles will require
 * {@code ServicePermission[Producer,REGISTER]} to register a Producer service.
 * In general, only the Wire Admin service should have
 * {@code ServicePermission[Producer,GET]}. Thus only the Wire Admin service may
 * directly call a Producer service. Care must be taken in the sharing of
 * {@code Wire} objects with other bundles.
 * <p>
 * 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 {@code WirePermission} for each of these scope names.
 * 
 * @author $Id$
 */
public interface Producer {
	/**
	 * Return the current value of this {@code Producer} object.
	 * 
	 * <p>
	 * This method is called by a {@code Wire} object in response to the
	 * Consumer service calling the {@code Wire} object's {@code 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 preference. The returned value should be as new or newer than
	 * the last value furnished by this object.
	 * 
	 * <p>
	 * Note: This method may be called by a {@code Wire} object prior to this
	 * object being notified that it is connected to that {@code Wire} object
	 * (via the {@link #consumersConnected(Wire[])} method).
	 * <p>
	 * If the Producer service returns an {@code Envelope} object that has an
	 * impermissible scope name, then the Wire object must ignore (or remove)
	 * the transfer.
	 * <p>
	 * If the {@code Wire} object has a scope set, the return value must be an
	 * array of {@code Envelope} objects ({@code Envelope[]}). The {@code Wire}
	 * object must have removed any {@code Envelope} objects that have a scope
	 * name that is not in the Wire object's scope.
	 * 
	 * @param wire The {@code Wire} object which is polling this service.
	 * @return The current value of the Producer service or {@code null} if the
	 *         value cannot be coerced into a compatible type. Or an array of
	 *         {@code Envelope} objects.
	 */
	public Object polled(Wire wire);

	/**
	 * Update the list of {@code Wire} objects to which this {@code Producer}
	 * object is connected.
	 * 
	 * <p>
	 * This method is called when the Producer service is first registered and
	 * subsequently whenever a {@code Wire} associated with this Producer
	 * becomes connected, is modified or becomes disconnected.
	 * 
	 * <p>
	 * 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 {@code Wire}
	 *        objects to which this Producer service is connected. May be
	 *        {@code null} if the Producer is not currently connected to any
	 *        {@code Wire} objects.
	 */
	public void consumersConnected(Wire[] wires);
}