001 /*
002 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.wireadmin;
017
018 /**
019 * Data Producer, a service that can generate values to be used by
020 * {@link Consumer} services.
021 *
022 * <p>
023 * Service objects registered under the Producer interface are expected to
024 * produce values (internally generated or from external sensors). The value can
025 * be of different types. When delivering a value to a <code>Wire</code> object,
026 * the Producer service should coerce the value to be an instance of one of the
027 * types specified by {@link Wire#getFlavors}. The classes are specified in
028 * order of preference.
029 *
030 * <p>
031 * When the data represented by the Producer object changes, this object should
032 * send the updated value by calling the <code>update</code> method on each of
033 * <code>Wire</code> objects passed in the most recent call to this object's
034 * {@link #consumersConnected} method. These <code>Wire</code> objects will pass
035 * the value on to the associated <code>Consumer</code> service object.
036 *
037 * <p>
038 * The Producer service may use the information in the <code>Wire</code> object's
039 * properties to schedule the delivery of values to the <code>Wire</code> object.
040 *
041 * <p>
042 * Producer service objects must register with a <code>service.pid</code> and a
043 * {@link WireConstants#WIREADMIN_PRODUCER_FLAVORS} property. It is recommended
044 * that a Producer service object also registers with a
045 * <code>service.description</code> property. Producer service objects must
046 * register with a {@link WireConstants#WIREADMIN_PRODUCER_FILTERS} property if
047 * the Producer service will be performing filtering instead of the
048 * <code>Wire</code> object.
049 *
050 * <p>
051 * If an exception is thrown by a Producer object method, a
052 * <code>WireAdminEvent</code> of type {@link WireAdminEvent#PRODUCER_EXCEPTION}
053 * is broadcast by the Wire Admin service.
054 *
055 * <p>
056 * Security Considerations. Data producing bundles will require
057 * <code>ServicePermission[Producer,REGISTER]</code> to register a Producer
058 * service. In general, only the Wire Admin service should have
059 * <code>ServicePermission[Producer,GET]</code>. Thus only the Wire Admin service
060 * may directly call a Producer service. Care must be taken in the sharing of
061 * <code>Wire</code> objects with other bundles.
062 * <p>
063 * Producer services must be registered with scope names when they can send
064 * different types of objects (composite) to the Consumer service. The Producer
065 * service should have <code>WirePermission</code> for each of these scope names.
066 *
067 * @version $Revision: 5673 $
068 */
069 public interface Producer {
070 /**
071 * Return the current value of this <code>Producer</code> object.
072 *
073 * <p>
074 * This method is called by a <code>Wire</code> object in response to the
075 * Consumer service calling the <code>Wire</code> object's <code>poll</code>
076 * method. The Producer should coerce the value to be an instance of one of
077 * the types specified by {@link Wire#getFlavors}. The types are specified
078 * in order of of preference. The returned value should be as new or newer
079 * than the last value furnished by this object.
080 *
081 * <p>
082 * Note: This method may be called by a <code>Wire</code> object prior to this
083 * object being notified that it is connected to that <code>Wire</code> object
084 * (via the {@link #consumersConnected} method).
085 * <p>
086 * If the Producer service returns an <code>Envelope</code> object that has an
087 * unpermitted scope name, then the Wire object must ignore (or remove) the
088 * transfer.
089 * <p>
090 * If the <code>Wire</code> object has a scope set, the return value must be
091 * an array of <code>Envelope</code> objects (<code>Envelope[]</code>). The
092 * <code>Wire</code> object must have removed any <code>Envelope</code> objects
093 * that have a scope name that is not in the Wire object's scope.
094 *
095 * @param wire The <code>Wire</code> object which is polling this service.
096 * @return The current value of the Producer service or <code>null</code> if
097 * the value cannot be coerced into a compatible type. Or an array
098 * of <code>Envelope</code> objects.
099 */
100 public Object polled(Wire wire);
101
102 /**
103 * Update the list of <code>Wire</code> objects to which this
104 * <code>Producer</code> object is connected.
105 *
106 * <p>
107 * This method is called when the Producer service is first registered and
108 * subsequently whenever a <code>Wire</code> associated with this Producer
109 * becomes connected, is modified or becomes disconnected.
110 *
111 * <p>
112 * The Wire Admin service must call this method asynchronously. This implies
113 * that implementors of a Producer service can be assured that the callback
114 * will not take place during registration when they execute the
115 * registration in a synchronized method.
116 *
117 * @param wires An array of the current and complete list of <code>Wire</code>
118 * objects to which this Producer service is connected. May be
119 * <code>null</code> if the Producer is not currently connected to any
120 * <code>Wire</code> objects.
121 */
122 public void consumersConnected(Wire[] wires);
123 }