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 Consumer, a service that can receive udpated values from
020 * {@link Producer} services.
021 *
022 * <p>
023 * Service objects registered under the <code>Consumer</code> interface are
024 * expected to consume values from a Producer service via a <code>Wire</code>
025 * object. A Consumer service may poll the Producer service by calling the
026 * {@link Wire#poll} method. The Consumer service will also receive an updated
027 * value when called at it's {@link #updated} method. The Producer service
028 * should have coerced the value to be an instance of one of the types specified
029 * by the {@link Wire#getFlavors} method, or one of their subclasses.
030 *
031 * <p>
032 * Consumer service objects must register with a <code>service.pid</code> and a
033 * {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} property. It is recommended
034 * that Consumer service objects also register with a
035 * <code>service.description</code> property.
036 *
037 * <p>
038 * If an <code>Exception</code> is thrown by any of the <code>Consumer</code>
039 * methods, a <code>WireAdminEvent</code> of type
040 * {@link WireAdminEvent#CONSUMER_EXCEPTION} is broadcast by the Wire Admin
041 * service.
042 *
043 * <p>
044 * Security Considerations - Data consuming bundles will require
045 * <code>ServicePermission[Consumer,REGISTER]</code>. In general, only the Wire
046 * Admin service bundle should have this permission. Thus only the Wire Admin
047 * service may directly call a Consumer service. Care must be taken in the
048 * sharing of <code>Wire</code> objects with other bundles.
049 * <p>
050 * Consumer services must be registered with their scope when they can receive
051 * different types of objects from the Producer service. The Consumer service
052 * should have <code>WirePermission</code> for each of these scope names.
053 *
054 * @version $Revision: 5673 $
055 */
056 public interface Consumer {
057 /**
058 * Update the value. This Consumer service is called by the <code>Wire</code>
059 * object with an updated value from the Producer service.
060 *
061 * <p>
062 * Note: This method may be called by a <code>Wire</code> object prior to this
063 * object being notified that it is connected to that <code>Wire</code> object
064 * (via the {@link #producersConnected} method).
065 * <p>
066 * When the Consumer service can receive <code>Envelope</code> objects, it
067 * must have registered all scope names together with the service object,
068 * and each of those names must be permitted by the bundle's
069 * <code>WirePermission</code>. If an <code>Envelope</code> object is delivered
070 * with the <code>updated</code> method, then the Consumer service should
071 * assume that the security check has been performed.
072 *
073 * @param wire The <code>Wire</code> object which is delivering the updated
074 * value.
075 * @param value The updated value. The value should be an instance of one of
076 * the types specified by the {@link Wire#getFlavors} method.
077 */
078 public void updated(Wire wire, Object value);
079
080 /**
081 * Update the list of <code>Wire</code> objects to which this Consumer service
082 * is connected.
083 *
084 * <p>
085 * This method is called when the Consumer service is first registered and
086 * subsequently whenever a <code>Wire</code> associated with this Consumer
087 * service becomes connected, is modified or becomes disconnected.
088 *
089 * <p>
090 * The Wire Admin service must call this method asynchronously. This implies
091 * that implementors of Consumer can be assured that the callback will not
092 * take place during registration when they execute the registration in a
093 * synchronized method.
094 *
095 * @param wires An array of the current and complete list of <code>Wire</code>
096 * objects to which this Consumer service is connected. May be
097 * <code>null</code> if the Consumer service is not currently connected
098 * to any <code>Wire</code> objects.
099 */
100 public void producersConnected(Wire[] wires);
101 }