/* * $Header: /home/wistrand/cvs/knopflerfish.org/osgi/bundles/wireadmin/src/org/osgi/service/wireadmin/Producer.java,v 1.1.1.1 2004/03/05 20:35:18 wistrand Exp $ * * Copyright (c) The Open Services Gateway Initiative (2002). * All Rights Reserved. * * Implementation of certain elements of the Open Services Gateway Initiative * (OSGI) Specification may be subject to third party intellectual property * rights, including without limitation, patent rights (such a third party may * or may not be a member of OSGi). OSGi is not responsible and shall not be * held responsible in any manner for identifying or failing to identify any or * all such third party intellectual property rights. * * This document and the information contained herein are provided on an "AS * IS" basis and OSGI DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL * NOT INFRINGE ANY RIGHTS AND ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR * FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL OSGI BE LIABLE FOR ANY * LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTIAL, * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH THIS * DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH LOSS OR DAMAGE. * * All Company, brand and product names may be trademarks that are the sole * property of their respective owners. All rights reserved. */ 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[REGISTER,Producer] to * register a Producer service. In general, only the Wire Admin service * should have ServicePermission[GET,Producer]. 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: 1.1.1.1 $ * @author Open Services Gateway Initiative */ 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); }