KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > wireadmin > Producer


1 /*
2  * $Header: /cvshome/build/org.osgi.service.wireadmin/src/org/osgi/service/wireadmin/Producer.java,v 1.10 2006/07/11 00:54:10 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.service.wireadmin;
19
20 /**
21  * Data Producer, a service that can generate values to be used by
22  * {@link Consumer} services.
23  *
24  * <p>
25  * Service objects registered under the Producer interface are expected to
26  * produce values (internally generated or from external sensors). The value can
27  * be of different types. When delivering a value to a <code>Wire</code> object,
28  * the Producer service should coerce the value to be an instance of one of the
29  * types specified by {@link Wire#getFlavors}. The classes are specified in
30  * order of preference.
31  *
32  * <p>
33  * When the data represented by the Producer object changes, this object should
34  * send the updated value by calling the <code>update</code> method on each of
35  * <code>Wire</code> objects passed in the most recent call to this object's
36  * {@link #consumersConnected} method. These <code>Wire</code> objects will pass
37  * the value on to the associated <code>Consumer</code> service object.
38  *
39  * <p>
40  * The Producer service may use the information in the <code>Wire</code> object's
41  * properties to schedule the delivery of values to the <code>Wire</code> object.
42  *
43  * <p>
44  * Producer service objects must register with a <code>service.pid</code> and a
45  * {@link WireConstants#WIREADMIN_PRODUCER_FLAVORS} property. It is recommended
46  * that a Producer service object also registers with a
47  * <code>service.description</code> property. Producer service objects must
48  * register with a {@link WireConstants#WIREADMIN_PRODUCER_FILTERS} property if
49  * the Producer service will be performing filtering instead of the
50  * <code>Wire</code> object.
51  *
52  * <p>
53  * If an exception is thrown by a Producer object method, a
54  * <code>WireAdminEvent</code> of type {@link WireAdminEvent#PRODUCER_EXCEPTION}
55  * is broadcast by the Wire Admin service.
56  *
57  * <p>
58  * Security Considerations. Data producing bundles will require
59  * <code>ServicePermission[Producer,REGISTER]</code> to register a Producer
60  * service. In general, only the Wire Admin service should have
61  * <code>ServicePermission[Producer,GET]</code>. Thus only the Wire Admin service
62  * may directly call a Producer service. Care must be taken in the sharing of
63  * <code>Wire</code> objects with other bundles.
64  * <p>
65  * Producer services must be registered with scope names when they can send
66  * different types of objects (composite) to the Consumer service. The Producer
67  * service should have <code>WirePermission</code> for each of these scope names.
68  *
69  * @version $Revision: 1.10 $
70  */
71 public interface Producer {
72     /**
73      * Return the current value of this <code>Producer</code> object.
74      *
75      * <p>
76      * This method is called by a <code>Wire</code> object in response to the
77      * Consumer service calling the <code>Wire</code> object's <code>poll</code>
78      * method. The Producer should coerce the value to be an instance of one of
79      * the types specified by {@link Wire#getFlavors}. The types are specified
80      * in order of of preference. The returned value should be as new or newer
81      * than the last value furnished by this object.
82      *
83      * <p>
84      * Note: This method may be called by a <code>Wire</code> object prior to this
85      * object being notified that it is connected to that <code>Wire</code> object
86      * (via the {@link #consumersConnected} method).
87      * <p>
88      * If the Producer service returns an <code>Envelope</code> object that has an
89      * unpermitted scope name, then the Wire object must ignore (or remove) the
90      * transfer.
91      * <p>
92      * If the <code>Wire</code> object has a scope set, the return value must be
93      * an array of <code>Envelope</code> objects (<code>Envelope[]</code>). The
94      * <code>Wire</code> object must have removed any <code>Envelope</code> objects
95      * that have a scope name that is not in the Wire object's scope.
96      *
97      * @param wire The <code>Wire</code> object which is polling this service.
98      * @return The current value of the Producer service or <code>null</code> if
99      * the value cannot be coerced into a compatible type. Or an array
100      * of <code>Envelope</code> objects.
101      */
102     public Object JavaDoc polled(Wire wire);
103
104     /**
105      * Update the list of <code>Wire</code> objects to which this
106      * <code>Producer</code> object is connected.
107      *
108      * <p>
109      * This method is called when the Producer service is first registered and
110      * subsequently whenever a <code>Wire</code> associated with this Producer
111      * becomes connected, is modified or becomes disconnected.
112      *
113      * <p>
114      * The Wire Admin service must call this method asynchronously. This implies
115      * that implementors of a Producer service can be assured that the callback
116      * will not take place during registration when they execute the
117      * registration in a synchronized method.
118      *
119      * @param wires An array of the current and complete list of <code>Wire</code>
120      * objects to which this Producer service is connected. May be
121      * <code>null</code> if the Producer is not currently connected to any
122      * <code>Wire</code> objects.
123      */
124     public void consumersConnected(Wire[] wires);
125 }
126
Popular Tags